自定义组件

版本范围：付费版本 内测阶段:目前已开放内测申请 ,扫码进入交流群
使用群体：需要具备一定的开发基础，面向开发者/ISV服务商/高级业务专家等

1. 功能简介

1.1 自定义组件简介

自定义组件功能为客户提供创建组件的能力，提升组件与业务需求契合度的同时，减少组件开发及运维的成本并提高了组件的可复用性。

1.2 使用场景

当宜搭普通组件无法满足您应用开发的业务需求时，您可以根据不同行业的业务习惯或需求来自行开发一款贴合业务场景的组件。且同一个组织中的自定义组件是可以进行共享的，这也就为后续您开发同类型应用复用相关组件提供了便利。

2. 操作指南

通过自定义组件实现计数器功能的小案例，体验一下自定义组件开发调试以及安装使用的具体操作。

2.1 案例场景

使用自定义组件功能，对宜搭现有的文本组件及按钮组件，进行低代码改造，实现计数器功能。适用于页面浏览量的统计、点/踩、关注/被关注等社交功能的实现等。

2.2 实现效果

点击左侧「加1」按钮时，数字加一，点击中间「重置」按钮时，数字归零；点击右侧「减1」按钮时，如果当前数字小于等于0，那么数字为0，否则为当前数字减1 的结果。

图2.2-1 计数器效果演示

2.3 操作步骤

2.3.1 步骤一：创建自定义组件

通过对组件名称、类型、标识等属性的配置，低成本、自定义一款更贴合业务需求的组件。

操作步骤：

1. 宜搭应用 >> 应用设置 >> 组件管理 >> 组件中心（操作如图2.3-1 所示）

图2.3-1 进入组件中心

1. 新增组件 >> 填写组件名称、组件类型、组件标识等组件属性 >> 确定（操作如图2.3-2 所示）

图2.3-2 创建自定义组件计数器

2.3.2 步骤二：开发调试自定义组件

对组件进行开发调试，以满足不同的业务需求。本案例中实现组件的计数功能。

操作步骤：

1. 组件中心 >> 我的组件 >> 找到需要调试的组件 >> 开发（操作如图2.3-3 所示）

图2.3-3 自定义组件开发调试入口

1. 添加自定义组件所需的宜搭普通组件到画布中，并进行基本属性的配置。本案例所需组件为一个文本组件及三个按钮组件。文本组件默认值设置为"当前计数结果为0"；按钮组件标题分别设置为"点击加1、点击重置以及点击减1"（操作如图2.3-4 所示）

图2.3-4 自定义组件样式布局

1. 为按钮组件进行动作设置，以实现计数效果。选中按钮 >> 新建动作 >> onClick 点击按钮。（操作如图2.3-5 所示）

图2.3-5 设置按钮动作

1. 在JS面板进行计数逻辑的编写。（如图2.3-6 所示）

图2.3-6 「点击加1」按钮动作代码

上图所示代码如下所示，使用过程中注意组件唯一标识的替换！

//「点击加1」按钮涉及逻辑代码，使用过程中注意组件唯一标识的替换
//初始化变量count为0。
let count = 0;
export function onClick() {
  //点击按钮，count变量进行自增加1。
  count++;
  //将自增加1后的变量count结果赋值给文本组件，实现计数结果在页面的显示。
  // text_k8bnuo08 为文本组件唯一标识，代码使用过程中，请替换为您创建的文本组件的唯一标识！
  this.$("text_k8bnuo08").set('content',"当前计数结果为" + count);
}

1. 重复步骤3及步骤4，为「点击重置」及「点击减1」按钮进行动作设置。（操作如图2.3-7 所示）

图2.3-7 「点击重置」、「点击减1」按钮代码

上图所示代码如下所示，使用过程中注意组件唯一标识的替换！

//「点击重置」按钮涉及代码
export function onClick2() {
  //点击按钮后，将计数结果重置为0；
  count = 0;
  //将重置后的变量count结果赋值给文本组件，实现计数结果在页面的显示。
  // text_k8bnuo08 为文本组件唯一标识，代码使用过程中，请替换为您创建的文本组件的唯一标识！
  this.$("text_k8bnuo08").set('content', "当前计数结果为" + count);
}

//「点击减1」按钮涉及逻辑代码，使用过程中注意组件唯一标识的替换
export function onClick3() {
  //进行判断，当count结果小于等于0时，初始化count变量为0；否则，进行count变量减1计算。
  if (count <= 0) {
    count = 0;
    // text_k8bnuo08 为文本组件唯一标识，代码使用过程中，请替换为您创建的文本组件的唯一标识！
    this.$("text_k8bnuo08").set('content', "当前计数结果为" + count);
  } else {
    //点击按钮实现变量count结果减1。
    count--;
    //将减1后的变量count结果赋值给文本组件，实现计数结果在页面的显示。
    // text_k8bnuo08 为文本组件唯一标识，代码使用过程中，请替换为您创建的文本组件的唯一标识！
    this.$("text_k8bnuo08").set('content', "当前计数结果为" + count);
  }
}

1. 保存>>发布>>填写组件发布的版本号及相关说明>>确定。（操作如图2.3-8 所示）

图2.3-8 组件发布信息填写

1. 发布成功会看到提示。（操作如图2.3-9 所示）

图2.3-9 发布成功提醒

2.3.3 步骤三：安装自定义组件

将开发调试完成的自定义组件，安装到页面内，即可在页面设计的过程中进行使用。组件安装需选择页面类型，选择后才会在对应的页面设计器中看到对应的自定义组件。

操作步骤：

1. 表单设计页 >> 组件库 >> 自定义组件 >> 安装自定义组件。（操作如图2.3-10 所示）

图2.3-10 自定义组件安装入口

1. 组件管理页面 >> 组件列表 >> 选择需要安装的自定义组件 >> 安装。（操作如图2.3-11 所示）

图2.3-11 选取需要安装的组件

1. 选择安装版本及安装范围 >> 安装。（操作如图2.3-12 所示）

图2.3-12 组件安装

注意：

1. 为保证线上使用自定义组件的稳定性，在组件版本选择时，请务必安装 1.x.x 发布后的正式版本。
2. 为保证自定义组件可以在页面设计器中使用，在选择安装范围时，只有选择了对应的页面类型后，才会在对应的页面设计器中则会看到对应安装的组件。

2.3.4 步骤四：使用自定义组件

通过上述步骤，自定义组件已经被安装至页面组件库的自定义组件类目中，通过下述步骤即可使用。

操作步骤：

1. 表单设计页 >> 组件库 >> 自定义组件 >> 选择需要的组件 >> 拖拽至画布即可。（操作如图2.3-13 所示）

图2.3-13 使用自定义组件

2.3.5 步骤五：查看/修改组件信息

在组件使用的过程中，如需对组件的缩略图、组件的说明文档地址、组件的描述信息进行修改，可以通过以下路径进行操作。

操作步骤

1. 应用设置 >> 组件管理 >> 组件中心（操作如图2.3-14 所示）

图2.3-14 进入组件中心

1. 选择需要查看/修改详情的组件 >> 详情（操作如图2.3-15 所示）

图2.3-15 查看组件详情

说明：组件详情页面分为基本信息、发布信息及管理员三个模块（如图2.3-16 所示），其中:

1. 基本信息：点击「编辑」可以对自定义组件的缩略图、帮助文档地址、组件描述进行修改，其余配置为组件创建之初进行配置且不可修改的。
2. 发布信息：可以查看自定义组件的迭代记录，包括组件版本及对应的发布说明。

1. 管理员（拥有对自定义组件进行开发调试权限，默认为组件创建者）：可以对管理员进行添加或删除操作，用于权限的管理。

图2.3-16 组件详情页

3. 自定义组件属性

自定义组件在支持对宜搭现有组件进行改造的同时，也支持对生成的自定义组件进行属性( propTypes )的自定义操作。使自定义组件更加贴合开发者的日常工作场景、符合开发者日常工作习惯的同时，使自定义组件拥有更高的灵活性及可定制性。

3.1 自定义组件属性配置入口

路径：低代码组件设计器 >> 选中画布中「低代码业务组件」>> 右侧属性（路径如图3.1-1 所示）

图3.1-1 自定义组件属性配置入口

3.2 自定义组件属性配置说明

自定义组件属性分为双端搭建、属性定义（ propTypes）、生命周期及唯一标识四个模块。其中，

• 双端搭建：双端搭建为配置开关，开启即可进行PC端及移动端同时进行自定义组件的开发调试工作，以满足双端适配的业务需求。
• 属性定义（ propTypes ）：可对自定义组件的标题、名称、类型（即数据格式）、默认值等基本属性进行自定义，也可对组件是否隐藏（组件隐藏与否的状态）、当变化时（组件显示值的不同）进行事件绑定，以满足多种多样的业务需求。详细介绍请参见，https://www.yuque.com/yida/support/zyrrlb。

• 生命周期：自定义组件的生命周期分为组件渲染完成（componentDidMount）、组件更新完成（componentDidUpdate）、组件捕捉错误（componentDidCatch）、组件销毁前（componentWillUnmount）四个阶段，在不同的生命周期中进行不同的逻辑编写，以满足复杂的业务需求。
• 唯一标识：同宜搭普通组件一样，自定义组件也拥有唯一标识属性，作为组件的唯一识别码，由系统自动生成，一般不需要更改。用于宜搭后台存储数据，代码绑定等。

特别注意：

• 组件的唯一标识（ fiedId ）是宜搭指向该组件的唯一标识码，更改标识可能会影响到该组件上所使用的公式、数据存储（数据也可能会出现丢失），JS函数侧的指向等。我们强烈不建议你去修改组件的唯一标识属性！
• 如果你坚持要修改该标识（目前只能通过 schema 导入的方式，如果你选择使用此方法来修改组件唯一标识，那么表示你已经明确这么做的后果以及表明自己会独自承担这个后果，宜搭有权不对该后果负任何责任，感谢你的理解和支持。

4. 附录

4.1 组件类型

宜搭自定义组件类型分 「普通组件」和「表单组件」两种，核心区别是：

1. 普通组件一般用来做展示型的功能，没有数据存储的能力。类似现有的「图文展示」「分组」组件。
2. 表单组件可以用来做数据提交，表单组件在开发上相对普通组件会更复杂些，需要额外定义元数据的配置。

1. 表单组件暂未开放，敬请期待。

4.2 组件安装类型

宜搭的页面类型有 普通表单页面、流程表单页面、报表页面、DataV大屏、自定义页面、外部链接。

宜搭的自定义组件目前支持其中的普通表单页面、流程表单页面、自定义页面这三种。

安装时选择了对应的页面类型后，在对应的页面设计器中则会看到对应安装的组件。

4.3 组件版本说明

宜搭的自定义组件版本在语义化版本的基础上做了额外的约定需要特别注意。

1. 0.1.0 默认为开发版本，开发版可和组件设计器保持实时同步，用来调试组件。
2. 1.x.x 为发布后的正式版本，会固定当前版本的功能，保证线上使用该组件的稳定性。所以线上的正式应用请务必安装 1.x.x 发布后的正式版本。