自定义组件

能力	免费版	轻享版	专业版	专属版
自定义组件	不支持	不支持	支持	支持

适用群体：需要具备一定的开发基础，面向开发者/ISV服务商/高级业务专家等

1. 功能简介

1.1 自定义组件简介

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

1.2 使用场景

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

1.3 组件的构成

组件由视图和属性构成，在组件的消费侧可以通过改变组件的属性让组件展示出不同的视图。

视图再细分可以分为设计视图和运行时视图，一般情况下设计视图和运行时视图可以复用。

在组件的生产侧，我们要分别构建组件的视图和属性。

2. 操作指南

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

2.1 案例场景

使用自定义组件功能，对宜搭现有的文本组件进行低代码改造，实现文本复制功能。用于文本内容复制到剪切板，便于用户进行重复字段的填写。

2.2 实现效果

图2.2-1 复制文本效果演示

2.3 操作步骤

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

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

操作步骤：

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

图2.3-1 进入组件中心

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

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

注意：

1. 普通组件一般适用于做展示型的业务功能，无数据存储能力。因此不支持数据提交行为，组件设计时请务必确认真实业务使用场景，如存在文本输入框等组件元素，用户提交的数据将不会生效。

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

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

操作步骤：

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

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

2. 前面有说到组件由视图和属性构建，当开发一个组件时需要先抽象出这个组件所需要的属性，我先来构建组件的属性，该组件只需要一个文本内容的属性，属性配置 >> 属性定义，添加一个文本内容的属性，名称为 content，属性类型选文本，设置器选 textSetter。

3. 组件属性构建完成后，来构建组件的视图，添加所需的宜搭普通组件到画布中（本案例所需组件为两个文本组件。分别命名为「文本」及「复制」），并进行基本属性的配置，将文本组件的内容进行变量绑定，绑定为刚才构建的属性 props.content, 这样就可以在运行时显示传过来的属性值。（操作如图2.3-4 所示）

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

4. 为按钮组件进行动作设置，以文本复制效果。选中「复制」文本 >> 新建动作 >> onCopyText 点击。（操作如图2.3-5 所示）

图2.3-5 设置按钮动作

5. 在JS面板进行复制逻辑的编写。（如图2.3-6 所示）

图2.3-6 「复制」按钮动作代码

export function onCopyText() {
  const input = document.createElement('input');
  input.setAttribute('readonly', 'readonly');
  // 通过 this.props.xxx 获取属性
  input.setAttribute('value', this.props.content);
  document.body.appendChild(input);
  input.select();
  input.setSelectionRange(0, 9999);
  document.execCommand('copy');
  document.body.removeChild(input);
  this.utils.toast('已成功复制到剪贴板');
}

6. 保存 >> 预览组件

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

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

8. 发布成功会看到提示。（操作如图2.3-8 所示）在实际的组件开发中，保存后即可安装组件的开发版(0.1.0)进行实时调试，当组件完成了开发后才需要发布正式版本。

图2.3-8 发布成功提醒

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

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

操作步骤：

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

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

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

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

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

图2.3-11 组件安装

注意：

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

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

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

操作步骤：

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

图2.3-12 使用自定义组件

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

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

操作步骤

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

图2.3-13 进入组件中心

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

图2.3-14 查看组件详情

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

1. 基本信息：点击「编辑」可以对自定义组件的缩略图、帮助文档地址、组件描述进行修改，其余配置为组件创建之初进行配置且不可修改的。
2. 发布信息：可以查看自定义组件的迭代记录，包括组件版本及对应的发布说明。
3. 管理员（拥有对自定义组件进行开发调试权限，默认为组件创建者）：可以对管理员进行添加或删除操作，用于权限的管理。
4. 安装信息：可查看该组件的历史安装信息（安装应用、安装版本、安装范围、安装人、安装时间）

图2.3-15 组件详情页

3. 自定义组件属性

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

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

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

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

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

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

• 双端搭建：双端搭建为配置开关，开启即可进行PC端及移动端完全分离，分别设计，以满足双端适配的个性业务需求。
• 属性定义（ propTypes ）：可对自定义组件的标题、名称、类型（即数据格式）、默认值等基本属性进行自定义，也可对组件是否隐藏（组件隐藏与否的状态）、当变化时（组件显示值的不同）进行事件绑定，以满足多种多样的业务需求。详细介绍请参见，组件属性配置。
• 生命周期：自定义组件的生命周期分为组件渲染完成（componentDidMount）、组件更新完成（componentDidUpdate）、组件捕捉错误（componentDidCatch）、组件销毁前（componentWillUnmount）四个阶段，在不同的生命周期中进行不同的逻辑编写，以满足复杂的业务需求。
• 唯一标识：同宜搭普通组件一样，自定义组件也拥有唯一标识属性，作为组件的唯一识别码，由系统自动生成，一般不需要更改。用于宜搭后台存储数据，代码绑定等。

特别注意：

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

4. 附录

4.1 组件类型

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

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

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

3. 门户组件一般用来做展示型的功能，没有数据存储的能力。适用于门户页面内使用。

4.2 组件安装类型

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

宜搭的自定义组件（普通组件类型）目前支持安装到自定义页面、普通表单&流程表单。

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

4.3 组件版本说明

宜搭的自定义组件版本分 开发版和正式版。

我们在语义化版本的基础上做了额外的约定。

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