# 自定义标准页面组件操作步骤
#### 步骤一：获取自定义组件模板包
为了增强标准页面组件的丰富性，华为云Astro轻应用为您提供了一个自定义组件模板workCards.zip，您可以基于该模板包自定义标准页面组件。开发标准页面组件前，请先了解自定义组件模板包的结构及定义规范，便于快速上手。
1. 单击[链接](https://obs-for-bj4-gongyouyun-update.obs.cn-north-4.myhuaweicloud.com/obs/deploy/workCards.zip)，获取华为云Astro轻应用自定义组件模板workCards.zip。
2. 解压获取的workCards.zip包，了解自定义组件模板包的结构及定义规范。
图1workCards.zip模板包结构
表1workCards.zip模板包目录及文件说明
| 目录及文件 | 说明 |
|:---|:---|
| build | 用于存放组件的打包脚本。 |
| dist | 组件打包文件目录，文件打包后生成于此目录下。 |
| preview | 组件预览文件夹。 |
| src | 组件的主文件夹，组件的内容位于此文件夹中。 本实践中，自定义组件仅涉及修改"src\\components\\workCards"目录下的内容，详细介绍请参见[表2]。 |
| .gitignore | Git的忽略文件。 |
| .npmrc | 设置package.json中依赖包的安装源。 |
| package.json | 项目的依赖文件。 |
| package-lock.json | 用于锁定依赖文件的安装版本号。 |
| README.md | 项目提示文件，用于编写对该组件的描述。 |
| vite.config.js | Vite的配置文件。 |
图2src\\components\\workCards目录结构
表2src\\components\\workCards目录结构说明
| 目录及文件 | 说明 |
|:---|:---|
| design-time | 开发态组件文件目录。 |
| static | 静态文件目录。 |
| cube.svg/workCards.svg | 业务中使用的图标。 |
| index.js | 组件主入口文件。 |
| workCards.json | 组件的描述文件，用于自定义组件配置面板的规格，即校验和辅助编写自定义组件配置面板的JSON文件。workCards.json文件的编写需遵循JSON Schema规范，以便与主流的编辑器（如vscode、atom、sublime text、webstorm）集成。 workCards.json可以在插件包开发时修改，也可以在插件包编译后修改，编译前workCards.json文件存放在"src\\components\\workCards"目录下（如[图3]），编译后"dist\\components\\workCards"目录下（如[表3]）。 |
| workCards.vue | 组件的主文件。 |
图3编译前workCards.json文件所在位置
图4编译后workCards.json文件所在位置
表3workCards.json参数说明
| 参数 | 说明 |
|:---|:---|
| name | 组件的名称，此处配置的名称主要用于后台元数据的存储和解析等。 - 长度不能超过64个字符，必须以英文字母开头，只能由英文字母、数字和特殊字符（_和-）组成。建议由厂商名_组件名_版本号组成，例如aaa_img-button_1.1.1。 - 组件的名称会存放在界面元数据的type中，如type: "my-component1"。 - zip包的名称应该和此处name的取值保持一致，例如name设置为imgbutton，zip包名必须为imgbutton.zip。 |
| title | 组件别名会显示在标准页面开发界面左侧"组件"页签下的扩展组件中，建议简短并能展示组件特性。 取值范围：1\~100个字符。 |
| description | 组件的描述信息，即当鼠标悬停在组件上时，展示的组件描述信息。 取值范围：1\~200个字符。 |
| category | 组件的分类，为了保持界面构建器组件分类的一致性，请使用华为云Astro轻应用提供的组件分类，具体分类如[表4]所示。 |
| icon | 组件的图标，分为**未选中时** 和**选中时**两个，必须为png格式，且每个png的大小不能超过16KB。 |
| 其他 | 用于定义包大小，编译后的组件包大小不能超过1MB。 |
表4华为云Astro轻应用组件分类
| 分类 | 说明 |
|:---|:---|
| navigation | 导航组件，如菜单、工具栏或侧边栏。 |
| data | 数据组件，可以查看和编辑应用程序中的数据，例如Form、Table或List。 |
| common | 通用组件，如标签、图片、标题或段落。 |
| container | 容器组件，即包含其他组件的容器。例如，栅格布局组件Row/Col、流式布局组件、Panel、Tabs、Collapse或WidgetContainer。 |
| input | 显示和编辑实体属性，如文本框、日期选择器。 |
| file | 文件处理组件，例如文件上传下载组件、图片浏览组件或PDF预览组件。 |
| button | 触发动作的按钮，如保存按钮、页面跳转按钮。 |
| report | 聚合数据并以表格或图表的形式显示，如图表、透视表。 |
| widget | 业务卡片。 |
| add-on | 扩展组件。 |
#### 步骤二：自定义标准页面组件imgButton
本实践中，imgButton组件是采用Node.js开发的前端组件。如果没有特殊说明，本实践均基于VSCode工具，按照imgButton组件的功能点介绍自定义组件的开发过程。
1. 将[步骤一：获取自定义组件模板包]中获取的模板包进行解压，并将解压后的文件夹名称修改为"imgButton"。
2. 修改组件描述文件"package.json"，将"name"修改成"imgButton"，保存并退出。
```
{
"name": "imgButton",
"private": true,
"version": "1.0.2",
"type": "module",
"scripts": {
"dev": "vite",
"build": "node ./build/build.mjs",
"format": "prettier --write src/",
"preview": "vite preview"
},
"dependencies": {
"element-plus": "^2.4.2",
"vue": "^3.3.4"
},
"devDependencies": {
"@vitejs/plugin-vue": "^4.6.2",
"jszip": "^3.10.1",
"kolorist": "^1.8.0",
"sass": "^1.69.5",
"unplugin-element-plus": "^0.8.0",
"unplugin-vue-components": "^0.25.1",
"vite": "^4.4.5",
"vue-style-loader": "^4.1.3"
}
}
```
3. 修改"src"文件夹下"manifest.json"文件，将"name"和"components"的参数值修改成"imgButton"，保存并退出。
```
{
"name": "imgButton",
"version": "1.0.2",
"type": "uiPackage",
"package": {
"components": [
"components/imgButton/imgButton.json"
]
},
"images": {
"default": "./static/package-default.png",
"previews": [
"./static/package-preview1.png",
"./static/package-preview2.png"
]
},
"publisher": "l84182839",
"license": "MIT",
"keywords": [
"UI Component"
],
"categories": [
"ui:components"
],
"bugs:url": "",
"repository:url": "",
"dependencies": []
}
```
4. 将"src\\components"文件夹和文件夹下的文件名由"workCards"修改为"imgButton"。
图5修改文件夹名称
图6修改文件夹中的文件名
5. 替换自定义组件的组件图标，此图标是自定义组件在页面构建器中显示的缩略图。
替换"src\\components\\imgButton\\static"路径下的"default.png"和"hover.png"图标，"default.png"为默认状态的图标，"hover.png"为鼠标经过时高亮效果的图标。
6. 修改"src\\components\\imgButton"路径下的定义文件"imgButton.json"。
- 修改组件定义文件的基本属性。 将"imgButton.json"文件中的"name"、"title"和"description"修改成"imgButton"，并将"properties"节点改为只包括"height"、"width"和"text"属性，具体代码如下：
```
{
"name": "imgButton",
"title": "imgButton",
"description": "imgButton",
"category": "add-on",
"icon": {
"default": "./static/default.png",
"hover": "./static/hover.png"
},
"definition": {
"props": {
"type": "object",
"properties": {
"height": {
"category": "common", //属性所属的标签，包括common（公共）、general（基础）和style（style）样式等
"type": "integer", //该属性的数值类型，integer（数字输入框）、date（时间选择框）、string（输入框）、select（下拉框）和switch（开关）
"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"
}
}
},
"main": "./index.js",
"mainDesignTime": "./design-time/index.js",
"dnd": {
"cname": "workCards",
"dname": "workCards-design",
"ctype": "Control",
"displayName": "workCards",
"selectable": true,
"targetable": true,
"draggable": true,
"deletable": true,
"wholeRow": true
}
}
```
修改上述配置后，在华为云Astro轻应用标准页面中，显示的组件属性配置如[图7]所示。
图7组件属性显示效果
- 修改组件定义文件的事件，将事件名修改为"click"。
```
"on": {
"type": "object",
"properties": {
"click": { // 代码中触发的事件名，在组件中用emit触发
"title": "点击", //事件名称
"description": "点击时执行的动作", //事件描述
"type": "object"
}
}
},
```
- 修改组件定义文件的拖拽行为，将"cname"、"displayName"和"dname"修改成"imgButton"和"imgButtonDesign"。
```
"dnd": {
"cname": "imgButton",
"dname": "imgButtonDesign",
"ctype": "Control",
"displayName": "imgButton",
"selectable": true,
"targetable": true,
"draggable": true,
"deletable": true,
"wholeRow": true
}
```
其中，"cname"为组件在应用引擎中显示的名称，"dname"为组件在应用开发工具中显示的名称，"displayName"为组件在页面构建器中显示的文本。
执行上述操作后，完整的"imgButton.json"文件配置示例如下：
```
{
"name": "imgButton",
"title": "imgButton",
"description": "imgButton",
"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"
}
}
},
"on": {
"type": "object",
"properties": {
"click": {
"title": "点击",
"description": "点击时执行的动作",
"type": "object"
}
}
},
"methods": {
}
},
"main": "./index.js",
"mainDesignTime": "./design-time/index.js",
"dnd": {
"cname": "imgButton",
"dname": "imgButton",
"ctype": "Control",
"displayName": "imgButton",
"selectable": true,
"targetable": true,
"draggable": true,
"deletable": true,
"wholeRow": true
}
}
```
7. 修改"src\\components\\imgButton"路径下的视图文件"imgButton.vue"。
- 修改视图文件的布局结构。 在布局（div标记对）中添加一个"img"和一个"span"，并按示例配置，代码示例如下：
```
{{ currentText }}
```
其中，"img"为imgButton按钮中的图片，"span"为imgButton按钮中的文本。
- 修改视图文件"imgButton.vue"的属性定义，修改"cssprefix"为"imgButton"，并添加"height"、"width"和"text"属性。
```
```
表5"computed"、"watch"和"methods"参数说明
| 参数 | 说明 |
|:---|:---|
| cssprefix | 此变量用于构造样式类名，增加灵活性。 |
| currentText | 用于显示按钮文本。 |
| comHeight | 用于获取图片的高度。 |
| comWidth | 用于获取图片的宽度。 |
| classes | 用于返回样式类名，也可以直接用字符串替换，这样写只是为了增加灵活性。 |
| onclick | 在图片按钮被单击时，去触发其单击事件的业务逻辑。 |
| setButtonText | 对外显露的方法，用于修改按钮中的文本。所有定义在method中的方法，都可在事件中直接调用，调用的方式如[图8]所示。 |
图8在事件中调用method中的方法
- 修改视图文件"imgButton.vue"中的"style"，定义图片按钮的样式类，包括**图片按钮外框** 、**图片** 和**文本** 三个样式类。
```
.imgButton {
display: inline-block;
background-color: #8cdcdb;
border: blue1 px solid;
cursor: pointer;
}
.imgButton-img {
margin-top: 5px;
margin-left: 5px;
}
.imgButton-title {
padding-bottom: 10px;
padding-right: 10px;
font-size: 16px;
cursor: pointer;
}
```
8. 修改"src\\components\\imgButton\\index.js"路径下的应用开发工具和应用引擎的控件定义文件"index.js"，将控件定义文件中的"workCards"修改为imgButton。
```
import imgButton from './imgButton.vue'
export default imgButton
```
9. 完成自定义组件的开发后，执行如下操作，生成自定义组件包。
1. 在本地的PC机上，快捷键**Windows+R** ，输入**cmd**进入命令提示符系统。
2. 进入imgButton所在的根目录，执行如下命令，生成自定义组件包"dist\\imgButton-\*\*\*.zip"。
执行yarn命令时，如果提示找不到，请先执行"npm install -g yarn"命令安装。
```
yarn install
yarn run build
```
图9生成自定义组件包
至此，您已顺利完成组件包的自定义与打包。本实践为您提供了[imgButton.zip](https://obs-for-bj4-gongyouyun-update.obs.cn-north-4.myhuaweicloud.com/obs/deploy/imgButton.zip)自定义组件样例包，供您与上述生成的自定义组件包进行参考对比。
#### 步骤三：上传自定义组件包
自定义组件包开发完成后，需要将其上传到华为云Astro轻应用中。上传后，该组件即可在标准页面中使用。
1. 参考[授权用户使用华为云Astro轻应用并购买实例](https://support.huaweicloud.com/usermanual-astrozero/astrozero_05_9046.html)中操作，申请华为云Astro轻应用免费试用或购买商业实例。
2. 实例购买后，在华为云Astro轻应用服务控制台的"主页"中，单击"进入首页"，进入应用开发页面。
图10应用开发页面
3. 单击页面左上角的，选择"环境管理 \> 环境配置"，进入环境配置页面。
4. 在环境配置页面的顶部菜单栏中，选择"维护"。
图11选择维护
5. 在左侧导航栏中，选择"全局元素 \> 页面资产管理 \> 自定义组件"。
图12选择自定义组件
6. 在"标准页面自定义组件"页面中，单击"新建"，选择[自定义标准页面组件操作步骤](https://support.huaweicloud.com/bestpractice-astrozero/astrozero_bestpractice_0043.html)中的自定义组件imgButton.zip，完成组件的上传。
上传成功后，自动返回标准页面自定义组件页面，在组件列表中可查看到已上传的自定义组件imgButton。
图13查看已上传的自定义组件
#### 步骤四：验证自定义组件是否符合预期
创建一个标准页面，将自定义组件拖拽到该页面中，确保组件能够正常显示。为自定义组件添加显示和隐藏事件，验证效果是否达到预期。
1. 创建一个低代码应用。
1. 在华为云Astro轻应用服务控制台的"主页"中，单击"进入首页"，进入应用开发页面。
2. 在"应用"中，单击"新建低代码应用"或单击，进入新建低代码应用页面。
3. 在新建低代码应用页面，应用类型选择"标准应用"，单击"确定"。
4. 输入应用的标签和名称，单击"新建"，即可进入应用设计器。
图14创建一个空白应用
表6新建空白应用参数说明
| 参数 | 说明 | 示例 |
|:---|:---|:---|
| 标签 | 新建应用的标签，长度不能超过80个字符。标签是应用在系统中的唯一标识，创建后不支持修改。 | 我的第一个应用 |
| 名称 | 新建应用的名称，输入标签值后单击该参数的输入框，系统会自动生成应用的名称，同时自动在名称前，添加***命名空间***__。命名要求如下： - 长度不能超过31个字符，包括前缀命名空间的长度。 名称前的内容为命名空间，在华为云Astro轻应用中为了避免不同租户间数据的重名，租户在首次创建应用时需要先定义一个命名空间。一个租户只能创建一个命名空间，创建后不支持修改。 - 必须以英文字母开头，只能由英文字母、数字或单下划线组成，且不允许以下划线结尾。 | A |
2. 在应用设计器中，选择"界面"，单击页面后的"+"，新建一个标准页面。
3. 从"基本组件"中，拖拽一个**输入框** 组件和一个**分栏** 组件到画布中，布局如[图15]。
图15拖入输入框和分栏组件
4. 选中分栏组件，在"属性 \> 样式 \> 布局"中，将"宽"设置为"360"px。
图16调整组件的宽度
5. 在"扩展组件"中，拖拽自定义组件imgButton到分栏组件的两个栏中。
图17拖拽imgButton组件到分栏中
6. 选中自定义组件，在"属性 \> 公共"中修改组件的"文本内容"为"显示"和"隐藏"。
图18修改组件的文本内容
7. 选中**显示** 组件，在"事件"页签中，单击"点击"后的"+"。
图19新建事件
8. 在"内置动作 \> 显示/隐藏控件"中，单击"添加控件"。
图20单击添加控件
9. 选择"输入框"组件，将"显示"按钮的"可见性"设置"显示"，单击"创建"。
图21选中输入框组件
图22设置显示按钮的可见性为"显示"
10. 同样，按照上述操作，将**隐藏** 按钮的"可见性"设置为"隐藏"。
图23设置隐藏按钮的可见性为"隐藏"
11. 验证效果是否符合预期。
单击标准页面上方的保存设置，保存成功后单击，进入预览页面。在预览页面单击"隐藏"，输入框组件会隐藏，单击"显示"，输入框组件会再次显示。
图24预览效果
1. 单击标准页面上方的保存设置，保存成功后单击，进入预览页面。
图25标准页面预览页面
2. 单击"隐藏"，输入框组件将会自动隐藏。
图26输入框组件已隐藏
3. 单击**显示** 按钮，输入框组件会再次显示。
图27输入框组件再次显示
#### 其他操作：更新自定义组件包
当开发的自定义组件功能有变动，即组件代码发生了变动时，支持对已上传的自定义组件进行更新。组件内容更新后，需要将"src/manifest.json"中的"version"版本号进行修改，假设当前版本号1.0.2，请将其修改为1.0.3，再重新执行**yarn run build**命令打包。打包完成后，在"dist"文件夹下会生成一个imgButton-1.0.3.zip的自定义组件包。
1. 在华为云Astro轻应用服务控制台的"主页"中，单击"进入首页"，进入应用开发页面。
2. 单击页面左上角的，选择"环境管理 \> 环境配置"，进入环境配置页面。
3. 在环境配置页面的顶部菜单栏中，选择"维护"。
4. 在左侧导航栏中，选择"全局元素 \> 页面资产管理 \> 自定义组件"，进入标准页面自定义组件页面。
在自定义组件列表中，可查看到当前的组件版本为"1.0.2"。
图28组件版本为1.0.2
5. 单击"新建"，选择"imgButton-1.0.3.zip"自定义组件包，单击"打开"。
组件更新后，在标准页面自定义组件列表中，可查看到组件的版本已更新为"1.0.3"。进入使用自定义组件的标准页面，会发现组件内容已随之更新。
图29组件版本为1.0.3
