在线开发高级组件

使用说明

当低代码平台提供的全局高级组件无法满足您的开发需求时，支持开发者自定义组件包，上传后可在高级页面中使用。自定义组件的开发流程如下：

1. 下载系统预置的组件模板到本地。
2. 基于模板，在本地根据自身业务需求开发组件。
3. 将已开发好的组件上传到组件库。

场景描述

本章节以开发网站中常用的标签切换页面为例，向您介绍如何基于组件模板在线开发组件。参考华为消费者业务网站（如图1所示），页面中主要包含标签栏和详情展示模块两部分，可以通过切换标签来控制详情展示模块中的展示内容。

图1 消费者业务网站示例

本章节主要在高级页面中，通过两个组件（标签页组件、信息展示组件）复现上述场景。其中，标签页组件包含产品类别（手机、笔记本、平板等），信息展示组件用于展示不同产品类别的图片信息。两个组件通过事件-动作机制实现交互，在标签页组件中注册标签切换事件，此事件绑定信息展示组件中切换产品图片的动作。

本章节使用的示例组件开发过程中，使用了前端开发框架Vue及组件库Element。事件-动作机制的详情介绍，请参见如何实现组件交互。

操作步骤

1. 下载组件模板。
   1. 在应用开发页面，单击，选择“环境管理 > 环境配置”，进入新版环境配置。
   2. 在主菜单中，选择“维护”。
   3. 在左侧导航栏中，选择“全局元素 > 页面资产管理 > 组件模板”。

      在组件模板页面，您可以查看到系统预置的几种Widget模板。

      表1 组件模板列表

      组件模板名称	功能
      widgetVueTemplate	自定义组件需要使用Vue库时，请选用该模板。
      widgetPropertyTemplate	自定义组件需要通过自定义属性栏配置属性时，请选用该模板。
      widgetActionTemplate	自定义组件需要添加动作属性时，请选用该模板。该类型组件开发过程，请参考如何实现组件交互。
      widgetEventTemplate	自定义组件需要添加事件属性时，请选用该模板。该类型组件开发过程，请参考在线开发高级组件。
      widgetBridgeTemplate	自定义组件需要通过桥接器调用后台数据时，请选用该模板。该类型组件开发过程，请参考如何调用后台接口。
      widgetPageMacroTemplate	需要使用页面宏来存储变量时，请选用该模板。

   4. 下载组件模板。

      根据需求选择模板，在组件模板详情页中单击“下载”按钮，在“下载组件模板”弹窗中输入组件名称，单击“保存”按钮即可。

      本章节示例中同时开发标签页组件和信息展示组件，由于本例中组件基于Vue框架实现，所以优先选择widgetVueTemplate模板，标签页组件取名为TabsWidget，信息展示组件取名为DisplayWidget。模板组件下载方法如下图所示（以下载TabsWidget为例）：

      图2 下载组件模板示例
      
      图3 保存模板
      
      

      若选择“下载原始模板”，下载到本地的组件包中，组件名称不会被修改。

2. 初识组件文件结构。

   将下载到本地的组件包进行解压，使用您熟悉的开发工具进行开发。本章节以1中下载的TabsWidget组件为例，介绍组件包的文件结构以及各文件的功能。

   表2 组件文件结构

   文件名	文件说明
   TabsWidget.js	组件逻辑文件，整个Widget的渲染核心JS，在组件编辑状态和页面最终的发布运行态都会被加载执行。主要包含的预置API说明，请参见高级页面组件中预置的API。
   TabsWidget.editor.js	组件属性定义文件，负责组件在编辑状态时，需要渲染的界面和逻辑。“*.editor.js”只在组件编辑状态被加载，主要包含： propertiesConfig：主要负责组件配置页面中，右侧的属性配置逻辑。 create方法仅在组件首次被创建时，调用一次。
   TabsWidget.css	组件的样式文件，在该文件中编写组件的CSS样式。
   TabsWidget.ftl	组件DOM结构文件，需要在服务端提前渲染的部分可以写在此文件中，相当于HTML文件，负责样式展示。
   packageinfo.json	组件的元数据描述文件，定义了如下内容。 widegtApi name：组件的名称。 widgetDescription：组件的描述信息。 authorName: ：组件的作者信息。 localFileBasePath：组件本地调测路径。 i18n：指定组件的国际化资源文件（本例模板中未体现）。 requires：依赖的库名称和版本号。 width：在绝对布局高级页面中，添加该组件时的默认宽度，单位为px，不填写默认为200px（本例模板中未体现）。 height：在绝对布局高级页面中，添加该组件时的默认高度，单位为px，不填写默认为200px（本例模板中未体现）。
   messages-zh/messages-en.json	组件的国际化资源文件，用于配置多语言（本例模板中未体现）。

3. 组件DOM结构及逻辑编写。
   • TabsWidget组件
     1. 在TabsWidget组件包TabsWidget.js文件中的render函数下，修改注册的Vue实例。

        thisObj.vm = new Vue({
            el: $("#Tabswidget", elem)[0],
            data:{
                activeName: "phone",
                //定义页签栏中的所含项目
                tabs: [
                    {label:"手机",name:"phone"},
                    {label:"笔记本",name:"PC"},
                    {label:"平板",name:"pad"},
                    {label:"智慧屏",name:"HiSilicon"},
                    {label:"穿戴",name:"wearableDevice"}
                ]
            },
            methods:{
                //此函数在切换页签时触发，用于触发后续步骤中TabsWidget组件注册的切换页签事件
                handleClick: function () {
                    thisObj.triggerEvent("switchingTab", {param: this.activeName});
                }
            }
        });

     2. 在TabsWidget组件包TabsWidget.ftl文件中，修改DOM结构。

        <div id="TabsWidget">
           <!-- 此处用到了Element提供的el-tabs组件  -->
           <el-tabs v-model="activeName" @tab-click="handleClick">
              <el-tab-pane
                      v-for="(tab, index) in tabs"
                      :key="index"
                      :label="tab.label"
                      :name="tab.name"
              ></el-tab-pane>
           </el-tabs>
        </div>

   • DisplayWidget组件
     1. 在DisplayWidget组件包DisplayWidget.js文件中的render函数下，修改注册的Vue实例。

        thisObj.vm = new Vue({
            el: $("#showtabs", elem)[0],
            data:{
                imgSrc: widgetBasePath + "img/phone.png",
                //定义信息展示组件中展示的图片路径信息
                sources: {
                    phone: widgetBasePath + "img/phone.png",
                    PC: widgetBasePath + "img/PC.png",
                    pad: widgetBasePath + "img/pad.png",
                    HiSilicon: widgetBasePath + "img/hisilicon.png",
                    wearableDevice: widgetBasePath + "img/wearableDevice.png"
                }
            },
            methods:{
                //此方法将在后续步骤中DisplayWidget组件注册的切换展示信息的动作中调用
                switchPic: function (param) {
                    this.imgSrc = this.sources[param];
                }
            }
        });

        

        • 上述代码中定义的展示图片文件可单击img.zip获取，下载后解压到DisplayWidget目录中即可正常使用。
        • 本示例代码中，widgetBasePath变量为组件包上传后的路径，在组件模板中已包含获取此变量的逻辑，在此直接使用即可（此例也展示了组件中如何引入本地图片的基本方法）。
     2. 在DisplayWidget组件包DisplayWidget.ftl文件中，实现DOM结构。

        <div id="showTabs">
           <img :src="imgSrc">
        </div>

4. 注册、实现事件和动作。
   1. 在TabsWidget组件包TabsWidget.js文件中的init函数中，注册页签切换的事件。

      if((typeof(Studio) != "undefined") && Studio)
      {
          var sendEventConfig = [{
              "name": "param"
          }];
          Studio.registerEvents(
              thisObj,
              "switchingTab",
              {"zh_CN": "切换标签", "en_US": "Switching Tab"},
              sendEventConfig
          );
      }

   2. 在DisplayWidget组件包DisplayWidget.js文件中的init函数中，注册切换展示图片的动作。

      if((typeof(Studio) != "undefined") && Studio)
      {
          var receiveActionConfig = {
              "name": "param"
          };
          Studio.registerAction(
              thisObj,
              "switchingPicture",
              {"zh_CN": "切换图片", "en_US": "Switching Picture"},
              receiveActionConfig,
              $.proxy(thisObj.switchingPicture, thisObj),
          );
      }

      在DisplayWidget组件包DisplayWidget.js文件中的组件示例中（即与init和render方法在同级作用域）实现上述注册的动作，示例代码如下所示：

      switchingPicture: function (event) {
          if (event && event.eventParam) {
              this.vm.switchPic(event.eventParam.param);
          }
      }

      

      “DisplayWidget.js”文件中第一行代码“var DisplayWidget = StudioWidgetWrapper.extend();”，其含义为新建的自定义组件继承于AstroZero平台定义的StudioWidgetWrapper类，此为开发规范，基于此类开发的自定义组件可以使用平台提供的如下方法：

      • “var widgetProperties = thisObj.getProperties(); ”用于获取组件的自定义属性配置值。
      • “var elem = thisObj.getContainer();” 用于获取组件的DOM元素。
      • “var connectorProperties = thisObj.getConnectorProperties();” 用于获取组件的桥接器属性配置值。

5. 定义组件依赖库及组件在绝对布局中默认尺寸。

   本节开发的示例组件TabsWidget依赖Vue和Element库，DisplayWidget依赖Vue库。所依赖的Vue库已在之前选择的组件模板“widgetVueTemplate”中定义，这里只需要在TabsWidget组件包的packageinfo.json文件中定义所依赖的Element库即可。

   1. 在新版环境配置中，查看库ID和版本号。

      以查询Element库为例，在开发环境新版环境配置的“维护 > 全局元素 > 页面资产管理 > 库”，搜索库，查看库ID和版本号信息。

      图4 查询库信息
      
      图5 查看库版本和ID
      

      本例中查询的Element库ID为：global_Element，库最新版本号为：101.0.4。

   2. 在TabsWidget组件包的packageinfo.json中，修改requires、width、height属性。
      示例代码如下所示：

      "requires": [
          {
            "name": "global_Vue",
            "version": "100.7"
          },
          {
            "name": "global_Element",
            "version": "101.0.4"
          }
      ],
      "width": "900",
      "height": "55",

   3. DisplayWidget组件只依赖Vue库，且在下载时选择的widgetVueTemplate组件模板，所依赖的Vue库已在模板中定义，本例无需修改，只需修改width、height属性。
      示例代码如下所示：

      "width": "900",
      "height": "560",

6. 上传自定义组件。
   1. 将开发好的组件代码压缩到后缀为.zip的压缩文件中（TabsWidget.zip、DisplayWidget.zip），也可以单击TabsWidget.zip、DisplayWidget.zip，获取示例组件包。
   2. 在开发环境新版环境配置的“维护 > 全局元素 > 页面资产管理 > 组件”，单击“提交新组件”。
   3. 在提交新组件页面，设置组件基本信息，并上传压缩文件，单击“提交”。
      图6 上传自定义组件示例
      

      表3 上传组件参数说明

      参数	说明
      名字	新提交组件的名称，系统会根据组件包名称自动填充。 示例：TabsWidget
      上传图标	组件的显示图标。
      上传源文件	组件源文件包，单击“请选择源文件(.zip)”，可选择源文件上传。
      组件ID	资产ID，前缀不可编辑，上传组件包后会自动填写。
      分类	组件所属分类，上传组件后，该组件将会在页面的该分类下进行展示。
      领域	组件包应用的领域，一般保持默认“通用”。
      场景	组件包的应用场景。 高级页面：组件适用于高级页面开发场景。 标准页面：组件适用于标准页面开发场景。 业务大屏：组件适用于Astro Canvas大屏页面开发场景。 业务小屏：组件适用于Astro Canvas小屏页面开发场景。 可同时勾选多项，勾选后，在相应类型页面开发中，才可使用该组件。
      发行说明	组件的描述信息，需要配置不同语种下的描述信息。 此处配置的信息，将会在组件详情页的“概况”页签中进行展示。

7. 组件功能测试。
   1. 在高级页面中，分别拖入上传的示例组件TabsWidget和DisplayWidget，并调整布局。
      图7 拖入组件调整布局
      
   2. 选中TabsWidget组件，在右侧“事件”页签，单击“切换标签”后的。
   3. 在“编辑事件 ”页面，单击“新建动作”，选择“DisplayWidget > 切换图片”。
   4. 单击“确定”，完成组件间交互设置。
   5. 在页面上方，单击，保存高级页面。
   6. 单击，发布页面，打开发布的页面网址测试效果。

      单击TabsWidget组件上的标签栏，会在DisplayWidget组件详情页进行相应的切换展示。