# 创建自定义标准组件
平台内置了很多标准组件，详情请参见[平台标准组件介绍](https://support.huaweicloud.com/usermanual-astrozero/astrozero_05_0131.html)。同时页面经常会有一些通用的交互模块，例如"人员选择"、"部门选择"等，这些页面交互模块可能会在多个页面中用到，逻辑也相对独立。面对这个情况，平台提供了让开发者自己创建组件的特性，称之为"自定义标准组件"。通过这个特性，开发者就能够将这样的交互模块抽象成标准页面组件，使页面的构建更加快速灵活。自定义组件在使用时与标准组件一致。
#### 适用场景
- 在不同的页面中，可重复使用的模块。
- 复杂的页面拆分成多个低耦合的模块，有助于代码维护。
#### 使用语言
Vue是一套用于构建用户界面的渐进式框架，与其它大型框架不同的是可以自底向上逐层应用Vue。Vue易于上手，也便于与系统进行整合。
开发自定义组件前，请先了解JS和Vue相关知识，具备一定的JS和Vue开发经验。
#### 自定义组件结构
- 自定义组件包，目录结构如下。
```
// 组件目录结构
my-package.zip
├── components
| └── my-component // my-component 组件
| ├── custom-property-editor // 自定义属性编辑控件（可选）
| │ └── index.js //
| ├── custom-panel // 自定义属性面板（可选）
| │ └── index.js //
| ├── design-time // 组件设计态代码（可选）
| │ └── index.js //
| ├── resources // 组件图片资源（可选）
| │ └── default.png //
| ├── index.js // 组件运行态代码
| ├── my-component.json // 组件定义文件
├── manifest.json // 组件清单文件
└── README.md // 组件包说明文件
```
- 组件zip包的目录及文件的名称不能是中文，且编译后的组件包大小应在1M以内。
- 组件名遵循**Vue组件命名** ，并且要在当前应用中唯一。您可参考[Vue框架指南](https://vuejs.org/v2/guide/index.html)定义Vue组件代码，并参考[Vue组件打包指南](https://vuejs.org/v2/cookbook/packaging-sfc-for-npm.html)对Vue组件进行打包，打包后才能使用。
表1组件包文件说明
| 目录/文件 | 是否可选 | 描述 |
|:---|:---|:---|
| custom-property-editor/index.js | 可选 | 自定义属性的编辑控件。 |
| custom-panel/index.js | 可选 | 自定义属性的面板。 |
| design-time/index.js | 可选 | 组件设计态。 |
| resources目录 | 可选 | 组件相关静态资源，如组件图片。 |
| index.js | - | 组件运行态。 |
| my-component.json | - | 组件定义文件。 |
- 组件包样例。 单击[链接](https://obs-for-bj4-gongyouyun-update.obs.cn-north-4.myhuaweicloud.com/obs/deploy/test-project.zip)，可下载样例包。
图1目录格式
- 组件描述文件。 组件描述文件test-project.json是自定义组件配置面板的规格文件，用于校验和辅助编写自定义组件配置面板json文件。该文件编写需遵循JSON Schema规范，以便于与主流的编辑器（vscode、atom、sublime text和webstorm）集成。
组件描述文件在插件包位置如下：
图2组件描述文件
组件描述文件，既可以在插件包开发时修改，也可以在插件包编译以后修改。编译之后，组件描述文件的位置如下所示。
图3编译后的组件描述文件位置
图4组件描述
样例代码：
```
{
// 下面的属性会用于页面组件右侧属性中
"name": "my-component",
"title": "%component.title%",
"description": "%component.description%",
"category": "add-on",
"icon": {
"default": "./resources/default.png",
"hover": "./resources/hover.png"
},
// ... 此处省略了组件的其他属性
}
```
表2组件约束
| 参数名 | 功能 | 限制 | 描述 |
|:---|:---|:---|:---|
| name | 组件名 | - 需要以英文字母开头，支持数字与特殊字符"_"、"-"，不支持中文，长度在64字符以内。 - 建议由厂商名_组件名_版本号组成，例如aaa_img-button_1.1.1。 | - 组件名会存放在界面元数据的type中，如type: "my-component1"。 - 配置文件中的名称，用于后台元数据存储、解析等。 - zip包名应该与name值保持一致，例如此处name为img-button，zip包名必须为img-button.zip。 |
| title | 组件别名 | 建议简短并能展示组件特性，长度在100字符以内。 | 组件别名，会显示在标准页面开发界面左侧"组件"页签下的扩展组件中，建议简短并能展示组件特性。 |
| description | 组件描述 | 长度在200字符以内。 | 当鼠标悬停时，展示的组件描述信息。 |
| category | 组件分类 | 使用平台提供的组件分类。 | 为了保持界面构建器组件分类一致性，请使用平台提供的组件分类，具体请参考[表3]。 |
| icon | 组件图标 | png格式，包括2个（未选中时和选中时），每个png的大小在16K以内。 | 在页面中展示的图标，自动压缩到40\*40。 |
| 其他 | 包大小 | 编译后的组件包大小，需要在1M以内。 | - |
表3组件分类
| 平台分类 | 说明 |
|:---|:---|
| navigation | 导航组件，例如菜单、工具栏或侧栏。 |
| data | 数据组件，可以查看和/或编辑应用程序中的数据，例如Form、Table或List。 |
| common | 通用组件，例如标签、图片、标题或段落。 |
| container | 容器组件，可以包含其他组件的容器。例如，栅格布局组件Row/Col、流式布局组件、Panel、Tabs、Collapse或WidgetContainer。 |
| input | 显示和编辑实体属性，例如文本框、日期选择器。 |
| file | 文件处理组件。例如，文件上传/下载组件、图片浏览组件或PDF预览组件。 |
| button | 触发动作的按钮，例如保存按钮、页面跳转按钮。 |
| report | 聚合数据并以表格或图表的形式显示，例如图表、透视表。 |
| widget | 业务卡片。 |
| add-on | 扩展组件。 |
#### 开发样例
本示例中的imgButton组件是使用nodejs开发前端的组件。以下若无特殊说明，均基于VSCode工具，按照imgButton组件的功能点来介绍自定义组件的开发过程。
1. 单击[链接](https://obs-for-bj4-gongyouyun-update.obs.cn-north-4.myhuaweicloud.com/obs/deploy/test-project.zip)，下载样例包，将自定义组件样例包解压，将修改文件夹名字为imgButton，如[图5包结构]所示。
图5包结构
2. 修改工程定义文件"package.json"，将"name"和"description"修改成"imgButton"，保存并退出。
```
{
"name": "imgButton",
"version": "1.0.0",
"description": "imgButton",
"scripts": {
"dev": "poi --config poi.dev.js",
"build": "poi build --config poi.build.js",
"report": "poi build --config poi.build.js --bundle-report",
"monitor": "poi build --config poi.build.js --webpackmonitor",
"eslint": "eslint --ext .vue,.js src"
},
```
3. 修改src文件夹下组件描述文件"manifest.json"，将"name"和"components"修改成"imgButton"，保存并退出。
```
{
"name": "imgButton",
"version": "1.0.8",
"type": "uiPackage",
"package": {
"components": [
"components/imgButton/imgButton.json"
]
},
```
4. 修改src文件夹下的"components"文件夹及文件名，将"test-project"改为"imgButton"，如[图6修改前后对比]所示。
图6修改前后对比
5. 替换自定义组件的组件图标，此图标是自定义组件在页面构建器中显示的缩略图。
在src文件夹的"components\\imgButton\\static"路径下，使用您所需要的图标替换示例包原有的"default.png"和"hover.png"，前者为默认状态的图标，后者为鼠标经过时高亮效果的图标。
6. 修改组件定义文件的基本属性。
打开在src文件夹的"\\components\\imgButton"路径下的定义文件"imgButton.json"，将其中的"name"、"title"和"description"修改成"imgButton"，并将"properties"节点改为只包括"height"、"width"和"text"属性，具体代码如下。
```
{
"name": "imgButton",
"title": "imgButton",
"description": "Button with a image",
"category": "add-on",
"icon": {
"default": "./static/default.png",
"hover": "./static/hover.png"
},
"definition": {
"props": {
"type": "object",
"properties": {
"height": {
"category": "common",
"type": "integer",
"title": "图片高度",
"description": "设置图片高度",
"default":16
},
"width": {
"category": "common",
"type": "integer",
"title": "图片宽度",
"description": "设置图片宽度",
"default":16
},
"text": {
"category": "common",
"type": "string",
"title": "framework.label.text",
"description": "按钮文本",
"default":"Button"
}
},
```
7. 修改组件定义文件的暴露方法。将"methods"节点改为只包括"setButtonText"方法，该方法用于设置图片按钮的文本，具体代码如下。
```
"methods": {
"setButtonText": {
"description": "设置按钮文本",
"type": "object",
"params": {
"description": "参数描述",
"type": "array",
"items": [
{
"title": "newText",
"type": "string",
"description": "新文本"
}
]
},
"returnValue": {
"description": "是否设置成功",
"type": "boolean"
}
}
}
```
setButtonText方法接收一个string类型的参数newText，执行后返回boolean。
8. 修改组件定义文件的拖拽行为。将其中的"cname"、"displayName"和"dname"修改成"imgButton"和"imgButtonDesign"。
- cname：在应用引擎中显示的名称。
- dname：在应用开发工具中显示的名称。
- displayName：在页面构建器中显示的文本。
```
"dnd": {
"cname": "imgButton",
"dname": "imgButtonDesign",
"ctype": "Control",
"displayName": "imgButton",
"selectable": true,
"targetable": true,
"draggable": true,
"deletable": true,
"wholeRow": true
}
```
9. 打开组件视图文件"imgButton.vue"，并修改视图文件的布局结构。
打开"src\\components\\imgButton\\"路径下的视图文件"imgButton.vue"，在布局（div标记对）中添加一个"img"和一个"span"，并按示例配置，具体代码如下，如[图7布局结构]所示。
图7布局结构
```
{{ comText }}
```
其中，"img"为imgButton按钮中的图片，"span"为imgButton按钮中的文本。
10. 修改视图文件"imgButton.vue"的属性定义。
修改"cssprefix"为"imgButton"，并添加"height"、"width"和"text"属性，如[图8修改属性定义后]所示。
图8修改属性定义后
```