开发一个 Enhancer 前端组件

1. 介绍

• Enhancer组件 由 组件配置页面(configurator) 和 组件本身(widget) 两部分组成。
• 组件配置页面会将用户的配置保存成一个 JSON。
• 组件在预览页面会包含在一个指定的窗口容器内，获得配置的 JSON。
• 推荐先前往 Enhancer 教程, 将 必修 部分看一遍。

配置页面(configurator)

下图为 enhancer-timeline 组件的配置页面

一般配置页面分为 数据源配置 和 其他配置项, 上图中左边是数据源配置, 右边是其他配置项。

配置页面生成的 JSON 如下:

{
  "dataSourceId": 1,       // 数据源 id, 通过这个id能获取到组件数据
  "direction": "vertical", // 展示方向
  "showCenter": true,      // 居中显示
  "icon":"fas fa-tag",     // 节点图标
  "iconSize": 16,          // 图标大小
  "titleFontSize": 16,     // 标题字体大小
  "contentFontSize": 14,   // 内容字体大小
  "footerFontSize": 12     // 底部字体大小
}

组件预览页面(widget)

下图为 enhancer-timeline 组件的预览页面:

2. 创建组件

这里我们准备开发一个列表组件, 组件名叫 widget-dev-demo. 以列表的形式渲染从数据源获取到的数据, 该组件可以控制列表中的数据是否是单行渲染。 下图中左右两部分分别是不同配置的展示

2.1 环境准备

• 请到 node.js 去下载安装 node。

• 全局安装组件开发工具 ewtool:

    npm install ewtool -g --registry=https://registry.npm.taobao.org

2.2 初始化组件

打开命令行终端, 运行下面的命令:

mkdir widget-dev-demo
cd widget-dev-demo
ewtool
npm install --registry=https://registry.npm.taobao.org
npm start

3. 熟悉组件开发界面

启动 widget-dev-demo 组件开发后, 会在默认浏览器中打开页面并显示如下:

如果你的默认浏览器不是 Chrome, 建议换成 Chrome 来查看。

3.1 场景列表

• 自定义场景: 每个组件都会有很多的配置项, 为了展示不同配置的效果, 可以点击下面的另存为按钮, 把组件的配置另存为一个场景。
• 定向场景: 定向场景专门用于测试组件的不同API和状态是否能正常运行, 组件开发完成时可以用这些场景来测试组件。

3.2 组件配置区

开发者需要将组件的不同配置项渲染在这块区域。

3.3 操作按钮

从左到右分别是:

预览组件, 保存配置, 另存为(将组件配置另存为一个场景), 查看配置。

3.4 注意

如果在还没有点击 保存配置 按钮之前就点击了 预览组件 按钮, 会打开新页面显示如下:

会看到组件一直在加载中, 这是因为此时组件的配置还没保存过, 需要先点 保存配置 按钮。

4. 开发配置器

widget-dev-demo 组件配置器的具体代码请参考 configurator, 下面介绍一下主要步骤:

4.1 在 contruct 函数里初始化 html 元素

const tplHTML = template({
  locale: locale()
});

$('body').html(tplHTML);

// 初始化数据源配置器
this.dataSourceConfig = Enhancer.DatasourceManager.createConfigurator('dataSourceDom', {
  supportedTypes: ['rdb', 'http', 'static', 'jsonp'],
  dataSpecification: 'dataSpecification', // 组件数据格式说明 
  onSave: (source) => {
    this.profile.dataSourceId = source.id;
  }
});

4.2 在 setProfile 函数里回填之前保存过的配置项

// 用保存过的数据源Id区加载数据源, 然后回填给数据源配置器
if (this.profile.dataSourceId) {
  Enhancer.DatasourceManager.getDatasource(this.profile.dataSourceId, (source) => {
    this.dataSourceConfig.setConfig(source);
  });
}

// 回填 单行显示 配置项
if (this.profile.oneLine) {
  $('input[name=oneLine]').prop('checked', true);
}

4.3 在 getProfile 函数里检查配置的合法性并返回新的配置数据

由于 widget-dev-demo 组件只有一个 数据源 配置项和一个 单行显示 的配置项, 因此 getProfile 函数只会返回这两个字段。

return {
  dataSourceId: this.profile.dataSourceId,
  oneLine: $('input[name=oneLine]').prop('checked')
};

开发完成后的效果

5. 开发组件

widget-dev-demo 组件的具体代码请参考widget, 主要代码如下:

// 获取组件所在的 html 容器
const $container = this.getContainer();

// 通过配置器里保存的数据源Id加载数据
this.getSourceData(profile.dataSourceId, (data) => {
  // 将 数据源数据(data.rows) 和 配置数据(profile.oneLine) 塞给 tpl 模版进行渲染 
  $container.html(tpl({
    locale: locale(),
    data: data.rows,
    oneLine: profile.oneLine
  }));

  // 通知平台 组件已经初始化完成
  this.trig('complete');
});

6. 配置&预览组

6.1 配置数据源

1. 回到配置页面。
2. 由于是本地开发, 数据源类型请选择 静态数据。

3. 将下面的数据粘贴到数据源编辑器里。

   {
     "rows": [{
       "content": "In locavore voluptate assumenda. Non raw denim sapiente aute small batch fap. Raw denim cliche lo-fi umami cray incididunt sunt before they sold out. Viral mollit flexitarian locavore, beard readymade eiusmod anim."
     }, {
       "content": "Lorem Ipsum has been the industry's standard dummy text eve. Lorem Ipsum has been the industry's standard dummy text eve. Lorem Ipsum has been the industry's standard dummy text eve. Lorem Ipsum has been the industry's standard dummy text eve"
     }, {
       "content": "Lorem Ipsum has been the industry's standard dummy text eve"
     }]
   }

4. 点击 保存数据源 按钮。
5. 点击 保存 按钮。

6.2 预览组件

1. 到配置页面, 点击 预览 按钮后可以看到的效果如下:
   

   以列表的形式渲染数据, 当宽度不够时文字自动换行显示。

2. 到配置页面, 将 单行显示 复选框勾上, 然后点 保存 按钮, 然后再点 预览 按钮可以看到的效果如下:
   

   以列表的形式渲染数据, 当宽度不够时超出部分会显示成省略号。

7. 发布组件

组件发布可以通过下面两种方式来发布, 任选其一即可

方式一: 命令发布

1. 打开命令行终端, 切换到 widget-dev-demo 目录下。
2. 运行下面的命令:

ewtool login // 用在 enhancer 平台上注册的用户名、密码进行登录, 如已登录过请忽略
ewtool release

方式二: 网页发布

1. 打开命令行终端, 切换到 widget-dev-demo 目录下。

2. 运行下面的命令:

   ewtool pack // 会将组件代码打包到 widget-dev-demo/release 下

3. 用浏览器打开 https://developer.enhancer.io/myWidgets, 点击 添加第一个组件, 在组件添加页面 填写组件相关内容 然后提交组件。
4. 组件发布完成后可以在浏览器里打开我的组件, 然后继续完善组件相关的信息