新建并开发自定义组件
操作场景
当系统预置的组件无法满足用户需求时，用户可自定义组件包进行上传，在页面中进行使用。在开发自定义组件前，请仔细阅读自定义组件开发规范章节内容，了解组件的开发规范。下面以开发网站中常用的柱状图（vue2+Echarts）组件为例，向您介绍如何开发自定义组件。
开发自定义组件
- 下载图表模板。
- 参考登录AstroCanvas界面中操作，登录AstroCanvas界面。
- 单击页面右上角的“管理”，进入AstroCanvas管理页面。
- 在左侧导航栏中，选择“页面资产管理 > 组件模板”。
表1 组件模板列表 组件模板名称
功能
EchartsWidgetTemplate
基于Echarts实现的一个柱状图组件模板，包含基本配置项、单击系列的事件交互、数据对接等能力。
SelectWidgetTemplate
基于elmentUI和Vue2实现一个通用的下拉框组件模板，包含基本配置项、交互、数据对接等能力。
widgetVueTemplate
当需要使用Vue library时，请选用该模板。
widgetPropertyTemplate
当需要自定义组件的一些属性时，请选用该模板。自定义属性会显示在组件的属性配置界面。
widgetActionTemplate
当自定义组件需要添加动作属性时，请选用该模板。
事件和动作都是Widget的配置属性，用于实现Widget之间的交互。例如，单击某个Widget内的按钮，另外一个Widget需要进行数据更新操作，或者是需要跳转到同个应用下的其他页面，这时需要通过事件和动作的机制来实现。单击按钮是触发一个事件，该Widget需要选用“widgetEventTemplate”模板，数据更新操作或者页面跳转操作是一个动作，该Widget需要选用“widgetActionTemplate”模板。
widgetEventTemplate
当自定义组件需要添加事件属性时，请选用该模板。
widgetBridgeTemplate
当自定义组件需要通过桥接器调用后台数据时，请选用该模板。
widgetPageMacroTemplate
当需要使用页面宏来存储变量时，请选用该模板。
- 在组件模板列表中，单击“EchartsWidgetTemplate”，进入模板详情页。
图2 选择EchartsWidgetTemplate模板
- 单击“下载”，将EchartsWidgetTemplate组件模板包下载到本地。
- 解压已下载的组件模板包，认识组件结构。
表2 组件文件结构 文件名
文件说明
EchartsWidgetTemplate.js
组件逻辑文件，整个Widget的渲染核心JS，在组件编辑状态和页面最终的发布运行态都会被加载执行。主要包含的预置API说明请参见表3。
EchartsWidgetTemplate.editor.js
组件属性定义文件，负责组件在编辑状态时需要渲染的界面和逻辑。“*.editor.js”只在组件编辑状态被加载，主要包含：
- propertiesConfig方法：主要负责组件配置页面中右侧的属性配置逻辑。
- create方法：仅在组件首次被创建时调用一次。
EchartsWidgetTemplate.css
组件的样式文件，在该文件中编写组件的CSS样式。
EchartsWidgetTemplate.ftl
组件DOM结构文件，需要在服务端提前渲染的部分可以写在此文件中，相当于HTML文件，负责样式展示。
packageinfo.json
组件的元数据描述文件。
- widegtApi name：组件的名称。
- widgetDescription：组件的描述信息。
- authorName: ：组件的作者信息。
- localFileBasePath：组件本地调测路径。
- i18n：指定组件的国际化资源文件（本例模板中未体现）。
- requires：依赖的库名称和版本号。
- width：在绝对布局高级页面中，添加该组件时的默认宽度，单位为px，不填写默认为200px（本例模板中未体现）。
- height：在绝对布局高级页面中，添加该组件时的默认高度，单位为px，不填写默认为200px（本例模板中未体现）。
messages-zh/messages-en.json
组件的国际化资源文件，用于配置多语言（本例模板中未体现）。
- 了解核心逻辑代码。
- EchartsWidgetTemplate.js
init()函数：组件初始化入口API，初始化组件通用能力，负责注册组件事件和组件动作。
/* * 组件初始化入口API,初始化组件通用能力，负责注册组件事件和组件动作 */ init() { this._super.apply(this, arguments); // 组件通用能力构建，调用父类constructor,必须要写 this.getWidgetI18n().then(() => this.render()); // 渲染组件 },render()函数：组件核心渲染API，负责组件的实例化和数据调用，以及事件和动作的实际实现。/** * 组件核心渲染api，负责组件的实例化、数据调用及事件、动作的实际实现 */ render() { const widgetContainer = this.getContainer(); if (!widgetContainer) return; this.initI18n(); this.initReaderVm(this.getProps(), widgetContainer); this.registerWidgetActionAndEvent(); this.registerResizeEvent(() => this?.readerVm?.echartsInst?.resize()); },beforeDestroy()函数：组件销毁回调事件，负责组件在销毁期间的内存释放逻辑实现，需要把组件绑定的一些dom事件及全局的引用销毁。
/** * 组件销毁回调事件，负责组件在销毁期间的内存释放逻辑实现，需要把组件绑定的一些dom事件及全局的引用销毁 */ beforeDestroy() { $(window).off('resize'); this.readerVm && this.readerVm.$destroy && this.readerVm.$destroy(); },initReaderVm()函数：初始化运行态组件VM实例。
/** * 初始化运行态组件VM实例 * @param {*} props 组件配置项 * @param {*} widgetContainer 组件容器 */ initReaderVm(props, widgetContainer) { const { commonProps } = props; const thisObj = this; thisObj.readerVm = new window.Vue(...) },registerWidgetActionAndEvent()函数：注册组件对外暴露的事件和动作。
/** * 注册组件对外暴露的的事件和动作 */ registerWidgetActionAndEvent() { if (!window.Studio) { return; } window.Studio.registerEvents(this, 'clickSeries', { zh_CN: '点击系列', en_US: 'Click Series' }); window.Studio.registerAction( this, 'highlightSeries', { zh_CN: '高亮系列', en_US: 'Highlight Series' }, [], (...args) => this.readerVm.highlightSeries(...args), ); }, - EchartsWidgetTemplate.ftl
- EchartsWidgetTemplate.js
- 对下载的模板进行重命名，本示例修改为BarGraph。
- 进入解压后的目录，修改文件名称，即将EchartsWidgetTemplate.css修改为BarGraph.css，EchartsWidgetTemplate.editor.js修改为BarGraph.editor.js，EchartsWidgetTemplate.ftl修改为BarGraph.ftl，EchartsWidgetTemplate.js修改为BarGraph.js。
图3 修改后效果
- 进入重名后的BarGraph.css文件，将组件ID替换为“BarGraph”，可通过搜索“EchartsWidgetTemplate”关键字进行批量替换。
图4 修改组件ID
- 按照上述操作，替换BarGraph.editor.js、BarGraph.ftl、BarGraph.js和packageinfo.json文件中组件ID。
如果自定义组件需要在不同的语言环境下使用，messages-zh.json和messages-en.json文件中的“EchartsWidgetTemplate”关键字也请替换为“BarGraph”。
- 进入解压后的目录，修改文件名称，即将EchartsWidgetTemplate.css修改为BarGraph.css，EchartsWidgetTemplate.editor.js修改为BarGraph.editor.js，EchartsWidgetTemplate.ftl修改为BarGraph.ftl，EchartsWidgetTemplate.js修改为BarGraph.js。
- 完成上述操作后，将所有文件打成zip包（请直接打包，不要在文件夹外打包），且包名为“BarGraph.zip”。
