新建并开发自定义组件
背景信息
当系统预置的组件无法满足用户需求时，用户可自定义组件包进行上传，在页面中进行使用。在开发自定义组件前，请仔细阅读自定义组件开发规范章节内容，了解组件的开发规范。
场景描述
本节以开发网站中常用的标签切换页面为例，向您介绍如何基于组件模板在线开发组件。如图1所示，页面中主要包含标签栏和详情展示两部分，通过切换标签栏来控制详情展示中的内容。
在页面开发中，通过两个自定义组件（标签页组件、详情展示组件）实现上述场景，其中标签页组件包含产品类别（手机、笔记本、平板等），详情展示组件用于展示不同产品类别的图片信息。两个组件通过事件和动作机制实现交互，在标签页组件中注册标签切换事件，此事件绑定详情展示组件中切换产品图片的动作。
操作步骤
- 下载组件模板。
- 参考登录AstroCanvas界面中操作，登录AstroCanvas界面。
- 单击页面右上角的“管理”，进入AstroCanvas管理页面。
- 在左侧导航栏中，选择“页面资产管理 > 组件模板”。
- 系统预置的模板如表1所示，请根据需求选择模板，选中后在模板详情页单击“下载”。
本章节示例中同时开发标签页组件和详情展示组件，由于本例中组件基于Vue框架实现，所以优先选择widgetVueTemplate模板。
表1 组件模板列表 组件模板名称
功能
widgetVueTemplate
当需要使用Vue library时，请选用该模板。
widgetPropertyTemplate
当需要自定义组件的一些属性时，请选用该模板。自定义属性会显示在组件的属性配置界面。
widgetActionTemplate
当自定义组件需要添加动作属性时，请选用该模板。
事件和动作都是Widget的配置属性，用于实现Widget之间的交互。例如，单击某个Widget内的按钮，另外一个Widget需要进行数据更新操作，或者是需要跳转到同个App下的其他页面，这时需要通过事件和动作的机制来实现。单击按钮是触发一个事件，该Widget需要选用“widgetEventTemplate”模板，数据更新操作或者页面跳转操作是一个动作，该Widget需要选用“widgetActionTemplate”模板。
widgetEventTemplate
当自定义组件需要添加事件属性时，请选用该模板。
widgetBridgeTemplate
当自定义组件需要通过桥接器调用后台数据时，请选用该模板。
widgetPageMacroTemplate
当需要使用页面宏来存储变量时，请选用该模板。
- 在“下载组件模板”弹出框中，设置标签页组件名称为“TabsWidget”，单击“保存”。同样基于widgetVueTemplate模板下载，设置详情展示组件名称为“DisplayWidget”。
如果选择“下载原始模板”，下载到本地的包中组件名称不会被修改。
- 将下载到本地的Widget包进行解压，认识组件结构。
本章节以下载的TabsWidget组件为例，说明组件包的文件结构及各文件的功能。
表2 组件文件结构 文件名
文件说明
TabsWidget.js
组件逻辑文件，整个Widget的渲染核心JS，在组件编辑状态和页面最终的发布运行态都会被加载执行。主要包含的预置API说明请参见表3。
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
组件的国际化资源文件，用于配置多语言（本例模板中未体现）。
- 编写TabsWidget组件DOM结构及逻辑。
- 在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}); } } }); - 在TabsWidget组件包“TabsWidget.ftl”文件中，修改DOM结构。
- 在TabsWidget组件包“TabsWidget.js”文件中的render函数下，修改注册的Vue实例。
- 编写DisplayWidget组件DOM结构及逻辑。
- 在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变量为组件包上传后的路径，在组件模板中已包含获取此变量的逻辑，在此直接使用即可（此例也展示了组件中如何引入本地图片的基本方法）。
- 在DisplayWidget组件包DisplayWidget.ftl文件中实现DOM结构。
- 在DisplayWidget组件包“DisplayWidget.js”文件中的render函数下，修改注册的Vue实例。
- 注册、实现事件和动作。
- 在TabsWidget组件包“TabsWidget.js”文件中的init函数中注册页签切换的事件。
示例代码如下所示：
if((typeof(Studio) != "undefined") && Studio) { var sendEventConfig = [{ "name": "param" }]; Studio.registerEvents( thisObj, "switchingTab", {"zh_CN": "切换标签", "en_US": "Switching Tab"}, sendEventConfig ); } - 在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(); ：获取组件的桥接器属性配置值。
- 在TabsWidget组件包“TabsWidget.js”文件中的init函数中注册页签切换的事件。
- 定义组件依赖库及组件在绝对布局中默认尺寸。
本节开发的示例组件TabsWidget依赖Vue和Element库，DisplayWidget依赖Vue库。所依赖的Vue库已在之前选择的组件模板“widgetVueTemplate”中定义，这里只需要在TabsWidget组件包的packageinfo.json文件中定义所依赖的Element库即可。
- 查询AstroCanvas预置库信息，本例以查询库“Element”为例。
在AstroCanvas界面中，搜索所需库“Element”，单击
，查看库ID和版本号信息。本例中查询的Element库ID为“global_Element”，库最新版本号为“101.0.8”。
图2 查看库详情
图3 查看库ID和版本
- 修改TabsWidget组件包中“packageinfo.json”文件的requires、width、height属性。
- DisplayWidget组件只依赖Vue库，且在下载时选择的widgetVueTemplate组件模板，所依赖的Vue库已在模板中定义，本例无需修改，只需修改width、height属性。
- 查询AstroCanvas预置库信息，本例以查询库“Element”为例。
- 将组件的全部文件重新打成zip包（请直接打包，不要在文件夹外打包）。
