文档首页 > > 用户指南> 开发前端UI层> 开发标准页面>

开发扩展组件(自定义组件)

开发扩展组件(自定义组件)

分享
更新时间:2021/02/23 GMT+08:00

AppCube支持自定义UI组件,可引入第三方Vue组件,并在开发标准页面时进行引用。

背景信息

首先,需要了解Vue的概念。Vue是一套用于构建用户界面的渐进式框架。与其它大型框架不同的是,您可以自底向上逐层应用Vue。Vue易于上手,也便于与系统进行整合。

自定义的UI组件包由以下文件组成。

// 1包1组件目录结构
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             // 组件定义文件
|       ├── my-component.nls.json        // 组件定义文件的国际化语言(可选)
|       └── my-component.nls.zh-cn.json   // 组件定义文件的中文配置(可选)
├── manifest.json                     // 组件清单文件
└── README.md                         // 组件包说明文件

组件zip包的目录以及文件的名称不能是中文,且编译后的组件包大小应在1M以内。

组件名遵循Vue组件命名,并且要在当前应用中唯一。您可参考Vue框架指南定义Vue组件代码,并参考Vue组件打包指南对Vue组件进行打包,打包后才能使用。

表1 组件包文件说明

目录/文件

是否可选

描述

custom-property-editor/index.js

可选

自定义属性编辑控件。

custom-panel/index.js

可选

自定义属性面板。

design-time/index.js

可选

组件设计态。

resources目录

可选

组件相关静态资源,如组件图片。

index.js

-

组件运行态。

my-component.json

-

组件定义文件。

my-component.nls.json

可选

组件定义文件的国际化语言。

my-component.nls.zh-cn.json

可选

组件定义文件的中文配置。

组件包样例

请单击链接下载样例包。

图1 目录格式

组件描述文件

组件描述文件是自定义组件配置面板的规格文件,用于校验和辅助编写自定义组件配置面板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”组件,打包后将该组件上传到平台的自定义组件中,然后在设计标准页面时进行引用。

“imgButton”组件在标准页面中显示效果为一个图片和一个文本的按钮,并对外暴露一个方法“setButtonText”(此方法用于当用户勾选了需要删掉的记录后,将已勾选的条目值更新显示在按钮文本中),效果如下图所示。

图5 自定义图片按钮组件效果图

前提条件

自定义组件需要开发组件包,您需要了解JS和Vue相关知识,有JS和Vue开发经验。

开发imgButton组件

本示例中的imgButton组件是使用nodejs开发前端的组件。以下如无特殊说明,均基于VSCode工具,按照imgButton组件的功能点,来介绍自定义组件的开发过程。

  1. 单击链接下载样例包,将自定义组件样例包解压,将修改文件夹名字为imgButton。

    图6 图片按钮组件工程目录

  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”。

    图7 修改“components”文件夹及文件名

  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": {
              "descripton": "参数描述",
              "type": "array",
              "items": [
                {
                  "title": "newText",
                  "type": "string",
                  "description": "新文本"
                }
              ]
            },
            "returnValue": {
              "descriptoin": "是否设置成功",
              "type": "boolean"
            }
          }
        }

    setButtonText方法接收一个string类型的参数newText,执行后返回boolean。

  8. 修改组件定义文件的拖拽行为。将其中的“cname”、“displayName”和“dname”修改成“imgButton”和“imgButtonDesign”。

    "dnd": {
        "cname": "imgButton",
        "dname": "imgButtonDesign",
        "ctype": "Control",
        "displayName": "imgButton",
        "selectable": true,
        "targetable": true,
        "draggable": true,
        "deletable": true,
        "wholeRow": true
      }
    图8 修改组件拖拽行为
    • cname:在应用引擎中显示的名称。
    • dname:在应用开发工具中显示的名称。
    • displayName:在页面构建器中显示的文本。

  9. 打开组件视图文件“imgButton.vue”,并修改视图文件的布局结构。

    打开“src\components\imgButton\”路径下的视图文件“imgButton.vue”,在布局(div标记对)中添加一个“img”和一个“span”,并按示例配置,具体代码如下。
    <img
      src="./static/hover.png"
      :height="comHeight"
      :width="comWidth"
      :class="classes + '-img'">
    <span :class="classes+ '-title'">
      {{ comText }}
    </span>
    图9 布局结构
    • img:即imgButton按钮中的图片。
    • span:即imgButton按钮中的文本。

  10. 修改视图文件“imgButton.vue”的属性定义。

    修改“cssprefix”为“imgButton”,并添加“height”、“width”和“text”属性,具体代码如下。

    <script>
    const cssprefix = "imgButton";
    export default {
      name: 'imgButton',
      props:{
        /** 图片高度 */
        height: {
          type: [String, Number],
          default: ""
        },
        /** 图片宽度 */
        width: {
          type: [String, Number],
          default: ""
        },
        /** 标签文本内容 */
        text: {
          type: String,
          default: "Button"
        }
      },
    图10 修改属性定义后

  11. 在视图文件“imgButton.vue”中添加“computed”和“methods”,添加示例配置,具体代码如下。

    computed: {
      comText() {
        return this.text;
        },
      classes() {
        return cssprefix;
        },
      comHeight() {
        return this.height == "" ? "16" : this.height;
        },
      comWidth() {
        return this.width == "" ? "16" : this.width;
        }
      },
    methods:{    
       onclick(e) {
         this.$emit("click", e);
         },
       setButtonText(newText){
         console.log("setButtonText params:" , newText);
         if(!newText)
         {
            return false;
         }
         this.text=newText;
         return true;
       }
      },
    图11 修改computed和methods后
    • cssprefix:此变量用于构造样式类名,增加灵活性。
    • comText:用于获取按钮文本。
    • comHeight、comWidth:分别用于获取图片的高和宽。
    • classes:用于返回样式类名,也可以直接用字符串替换,这样写只是为了增加灵活性。
    • onclick:在图片按钮被单击时,去触发其单击事件编排的业务逻辑。
    • setButtonText:对外显露的方法,用于修改按钮中的文本。

  12. 修改视图文件“imgButton.vue”中的“style scoped”,定义图片按钮的样式类。包括图片按钮外框、图片、文本三个样式类,具体代码如下。

    .imgButton {
    display: inline-block;
    background-color: #8CDCDB;
    border: blue1pxsolid;
    cursor: pointer;
    }
    .imgButton-img {
    margin-top: 5px;
    margin-left: 5px;
    }
    .imgButton-title {
    padding-bottom: 10px;
    padding-right: 10px;
    font-size: 16px;
    cursor: pointer;
    }
    图12 定义样式类

  13. 修改应用开发工具和应用引擎的控件定义文件,将控件定义文件中的“testProject”修改为imgButton,修改后效果如下图所示。

    控件定义文件路径:

    • 应用开发工具的文件路径“src\components\imgButton\design-time\index.js”。
      图13 修改后应用开发工具控件定义文件
    • 应用引擎的文件路径“src\components\imgButton\index.js”。
      图14 修改后应用引擎控件定义文件

  14. 在命令窗口进入imgButton所在文件夹,依次执行“yarn install”、“yarn upgrade”和“yarn run build”这三个命令,将会生成自定义组件包“dist\imgButton.zip”,如图15所示。

    至此,已从样例包成功生成自定义组件包。

    图15 自定义组件包构建完成

    如果执行yarn命令时提示找不到,请先使用“npm install -g yarn”安装。

  15. 这里提供正确的imgButton组件包的下载链接,供您与上一步生成的自定义组件包“dist\imgButton.zip”进行参考对照。请解压后对比检查上一步生成的自定义组件包是否配置正确。

上传及应用imgButton组件

  1. 在App开发界面左侧列表单击,选择“标准页面 > 资源管理 > 自定义组件”。
  2. 单击“新建”,打开上传自定义组件弹窗。
  3. 在本地电脑上,选择已经打包好的自定义组件包“imgButton.zip”。

    图16 已上传自定义组件

  4. 进入标准页面开发界面,在组件页签的“扩展组件”下,找到在上一步骤中,上传的自定义组件,将该自定义组件拖至设计区,并设置该组件的属性。

    图17 拖入组件
    图18 配置组件属性

  5. 单击页面上方保存按钮,再单击页面上方预览按钮,即可看到页面上显示图片按钮组件。
分享:

    相关文档

    相关产品

文档是否有解决您的问题?

提交成功!非常感谢您的反馈,我们会继续努力做到更好!
反馈提交失败,请稍后再试!

*必选

请至少选择或填写一项反馈信息

字符长度不能超过200

提交反馈 取消

如您有其它疑问,您也可以通过华为云社区问答频道来与我们联系探讨

智能客服提问云社区提问
{{site}}{{lan}}
{{site}}{{language}}