更新时间:2022-04-26 GMT+08:00
分享

创建自定义标准组件

平台内置了很多标准组件,详情请参见平台标准组件介绍。同时页面经常会有一些通用的交互模块,例如“人员选择”、“部门选择”等,这些页面交互模块可能会在多个页面中用到,逻辑也相对独立。面对这个情况,平台提供了让开发者自己创建组件的特性,称之为“自定义标准组件”。通过这个特性,开发者就能够将这样的交互模块抽象成标准页面组件,使页面的构建更加快速灵活。自定义组件在使用时与标准组件一致。

适用场景

  • 在不同的页面中可重复使用的模块
  • 复杂的页面拆分成多个低耦合的模块,有助于代码维护

使用语言

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框架指南定义Vue组件代码,并参考Vue组件打包指南对Vue组件进行打包,打包后才能使用。

    表1 组件包文件说明

    目录/文件

    是否可选

    描述

    custom-property-editor/index.js

    可选

    自定义属性编辑控件。

    custom-panel/index.js

    可选

    自定义属性面板。

    design-time/index.js

    可选

    组件设计态。

    resources目录

    可选

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

    index.js

    -

    组件运行态。

    my-component.json

    -

    组件定义文件。

  • 组件包样例。

    请单击链接下载样例包。

    图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. 单击链接下载样例包,将自定义组件样例包解压,将修改文件夹名字为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": {
              "descripton": "参数描述",
              "type": "array",
              "items": [
                {
                  "title": "newText",
                  "type": "string",
                  "description": "新文本"
                }
              ]
            },
            "returnValue": {
              "descriptoin": "是否设置成功",
              "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 布局结构
    • img:即imgButton按钮中的图片。
    • span:即imgButton按钮中的文本。
    <img
      src="./static/hover.png"
      :height="comHeight"
      :width="comWidth"
      :class="classes + '-img'">
    <span :class="classes+ '-title'">
      {{ comText }}
    </span>

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

    修改“cssprefix”为“imgButton”,并添加“height”、“width”和“text”属性,如图8修改属性定义后所示。
    图8 修改属性定义后
    <script>
    const cssprefix = "imgButton";
    export default {
      name: 'imgButton',
      props:{
        /*图片高度 */
        height: {
          type: [String, Number],
          default: ""
        },
        /*图片宽度 */
        width: {
          type: [String, Number],
          default: ""
        },
        /*标签文本内容 */
        text: {
          type: String,
          default: "Button"
        }
      },

  11. 修改视图文件“imgButton.vue”的“computed”和“methods”,并按示例配置,如下图所示。

    图9 修改computed和methods后
    • cssprefix:此变量用于构造样式类名,增加灵活性。
    • comText:用于获取按钮文本。
    • comHeight、comWidth:分别用于获取图片的高和宽。
    • classes:用于返回样式类名,也可以直接用字符串替换,这样写只是为了增加灵活性。
    • onclick:在图片按钮被单击时,去触发其单击事件编排的业务逻辑。
    • setButtonText:对外显露的方法,用于修改按钮中的文本。

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

    图10 定义样式类
    .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;
    }

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

    控件定义文件路径:

    • 应用开发工具的文件路径“src\components\imgButton\design-time\index.js”,如下图所示。
      图11 修改后应用开发工具控件定义文件
    • 应用引擎的文件路径“src\components\imgButton\index.js”,如下图所示。
      图12 修改后应用引擎控件定义文件

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

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

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

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

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

上传及使用自定义组件

  1. 上传自定义组件。

    在应用开发页面左侧列表中,选择“标准页面 > 资源管理 > 自定义组件”,如图14选择自定义组件所示。
    图14 选择自定义组件

  2. 单击“新建”,弹出上传自定义组件界面,如图15新建自定义组件所示。

    图15 新建自定义组件

  3. 选择本地已打包好的自定义组件包“imgButton.zip”并上传。
  4. 进入标准页面开发页面,在组件页签的“扩展组件”下,找到3中上传的自定义组件,可以将该自定义组件拖至画布中并设置该组件的属性,如图16所示。

    图16 自定义组件属性

  5. 使用自定义组件。

    本节以在新建对象页面中需要增加两个自定义组件,用来控制搜索框的显示、隐藏为例,效果如下所示。

    单击显示搜索,界面如图17显示搜索所示。

    图17 显示搜索

    单击关闭搜索,效果如图18关闭搜索所示。

    图18 关闭搜索

  6. 在应用目录中新建对象,在添加对象框中输入标签及名称,如图19新建对象所示。

    图19 新建对象

  7. 选择“布局”页签,单击页面布局中的“test Records”,该链接是操作自定义对象的模板页面,如图20选择新建对象模板所示。

    图20 选择新建对象模板
    图21 test Records页面

  8. 拖入分栏组件到页面中,并在分栏组件的“属性 > 样式 > 布局”宽度设置为240像素,如图21调整分栏组件所示。

    关于分栏组件的详细介绍请参见分栏

    图22 调整分栏组件

  9. 将自定义组件“imgButton”拖入到“分栏 > 栏”中,分别拖入到分栏的两个栏中,如图22拖入自定义组件所示。设置组件的属性,分别修改两个组件的文本内容为显示搜索和关闭搜索,如图23设置自定义组件属性所示。

    图23 拖入自定义组件
    图24 设置自定义组件属性
    图25 设置自定义组件属性

  10. 在组件的点击事件上添加动作,选择组件右侧属性面板的事件,单击右侧的按钮,在弹出的编辑动作框中选择“内置动作 > 显示/隐藏控件 > 添加控件”,如图24添加动作所示。

    图26 添加动作

  11. 在弹出的“选择控件”框中,选择要显示或隐藏的控件名称,这里选择“condition: Records_condition [CNAME__test__CST]”,如图27所示。关于控件的名称可以参考每个组件右侧属性面板上方的名称,如图28所示。

    图27 选择控件
    图28 组件名称

  12. 选择控件是否显示或隐藏,内容为显示搜索的imgButton组件设置为显示,如图27显示搜索设置显示所示。内容为关闭搜索的imgButton组件设置为隐藏,如图28关闭搜索设置为隐藏所示。

    图29 显示搜索设置显示
    图30 关闭搜索设置为隐藏

  13. 单击画布上方的保存按钮,然后单击预览按钮,预览效果如下所示。

    • 单击关闭搜索,页面上方的搜索栏会隐藏,如图29关闭搜索效果所示。
      图31 关闭搜索效果
    • 单击显示搜索,页面上方的搜索栏会重新显示,如图30显示搜索效果所示。
      图32 显示搜索效果

分享:

    相关文档

    相关产品

close