3.3.3VPA开发共享组件

VPA卡片共享组件

本节介绍了VPA的卡片类型，以及开发者会使用到的提供的共享组件（类似于前端界面的共享组件）。

1. 组件分类

VPA的组件分成三类

  • 共享组件：共享组件可以理解为平台提供的基础单位组件，是一种特殊类型的系统组件，它可以组成系统组件或远程组件的某一部分。举例：simpleText。
  • 系统组件：系统组件是指不同平台、业务在使用时具有公共表达能力的组件，比如天气、通讯录、会议日程等。
  • 远程组件（自定义组件）：远程组件是针对不同平台、业务、领域具有特殊业务场景下表达的组件。

2. 共享组件

介绍

共享组件是一种特殊的系统组件。它不仅用于 VPA 的内部功能实现，也通过接口暴露给外包，使得组件开发者也可以按照相关规则快速使用系统组件，让自定义组件的行为和交互等更加统一。

使用

在使用共享组件的时候，需要使用下面的方式进行引用：

import { SimpleText } from '@cards' // 推荐，有类型提示
// const { SimpleText } = vpa.__shared.cards （等价）

export default function ({ data }) {
  return (<div>
    <p>自定义组件内容</p>
    <SimpleText {...data} />
  </div>)
}

组件列表

以下是所有已经被共享可用的组件列表：

CommonCard

通用卡片组件，封装了卡片的基本样式(包含卡片头部)。只需要传入卡片头部的颜色、文字、图标（可选）就可以展示出带有头部的卡片。

如果是列表类型（type字段值为list、checkbox或radio）的数据，可以传入列表数据并配置相关参数，会自动展示列表数据。（具体可参考#MoreTip 组件和#Selector组件代码）

如果是选择器类型（type字段值为checkbox或radio）的数据，可以选择传入选择框选中和未选中状态的图片，不传则使用默认图片。

具体参数如下：

参数名 类型 默认值 描述
type list,default,checkbox,radio default 卡片类型：list为列表模式；checkbox、radio继承list，分别对应多选和单选模式
expendWhen number 6 类型为list时，数据超过多少条时，显示点击查看更多
listData array [] 类型为list时，需要展示的列表数据
listItemClick function - 类型为list时，点击某个列表项触发的事件
listName string name 类型为list时，列表渲染时展示的数据字段名，如果指定listBody，则该参数无效
textHighLight boolean false 类型为list时，列表项是否高亮，如果指定listBody，则该参数无效
listBody (item: any, index: number) => React.ReactNode undefined 类型为list时，用于自定义列表项的内容
listLeft (item: any, index: number) => React.ReactNode undefined 类型为list时，用于自定义列表项的左侧
listRight (item: any, index: number) => React.ReactNode undefined 类型为list时，用于自定义列表项的右侧
rightArrow boolean false 类型为list时，列表项是否显示右箭头，如果指定listRight，则该参数无效
modelID number - -
iconSelect any - 类型为checkbox、radio时，被选中状态的图片
iconUnSelect any - 类型为checkbox、radio时，未被选中状态的图片
icon any - 卡片头部的小图标
bgIcon any - 卡片头部右侧图标
text string - 卡片头部文字
color gray,pink,orange,green,purple gray 卡片头部颜色主题
SAData any - 智能动作处理器,内置了SmartAction卡片

1）卡片头部配置

卡片头部内置了 CardHeaderBG 组件，可以通过传入 text,icon,color和bgIcon 展示示卡片头部的文字、图标、主题颜色和背景图标。具体使用如下图所示：

2）列表配置

列表模式需要根据需求指定 type 字段

type 字段值的含义如下：

  • default：无默认配置。
  • list：列表模式。
  • checkbox：多选模式。继承自list。
  • radio：单选模式。继承自list。

具体配置如下图所示

简单配置模式

body1.png

代码示例

commonCardDemo1.png

自定义模式

body2.png

代码示例

commonCardDemo2.png

注：以上两种模式可以同时出现。

3）智能动作配置

智能动作处理器，内置了 SmartAction 组件，可以通过传入 SAData 展示示卡片底部的动作按钮。

SimpleText

简单文本组件，用于展示的基础的文本信息，支持语音播报

CardHeaderBG

卡片头部组件，用于展示卡片头部信息。通过传入 text,icon,color和bgIcon 展示示卡片头部的文字、图标、主题颜色和背景图标。

OpenApp

打开应用组件，用于自动打开/点击打开应用

组件根据传入的data中是否含有cardAction字段来判断是否需要自动打开应用，如果有则自动打开应用；如果有operation 字段，说明是需要展示按钮的，通过卡片点击事件触发

SmartAction

智能动作处理器。

3. 系统组件

介绍

系统组件是标准的 VPA 都会具备的组件，通常通过mudulID进行判别。包括但不限于：问候语、推荐意图、天气、通讯录、知识图谱、会议日程、视频音频播放器、图片查看器、选择器、打开应用等。

它们是构成 VPA 功能的基石，也是 VPA 的核心功能。本文档面向于 VPA 底包开发者，介绍了系统组件的信息。组件开发者可以忽略，无需关注。

为了让组件开发者能快速复用系统组件的能力，部分系统组件也提供了共享暴露机制，成为了共享组件。。

组件列表

系统组件名 说明
Contract/ContractItem 通讯录个人页，展示个人信息，包括头像、姓名、职位、部门、电话、邮箱等。支持给联系人打电话、发邮件、发信息。
Contract/ContractList 通讯录列表，展示匹配到的联系人列表。
Hello/Hi 问候语组件，位于VPA首页顶部，用于展示问候语和小友头像
Hello/Tips 推荐意图，位于VPA首页问候语组件下方，用于展示推荐意图列表
ImageViewer 图片查看器，用于展示图片，点击图片可放大查看
ISay 用于展示用户键盘输入/语音录入的信息
KGraph 知识图谱组件，用于展示知识图谱，支持拖拽节点和点击跳转
Loading 加载组件，用于展示加载中的状态，一般用于等待响应时展示
Media/VideoPlayer 视频组件，可用于播放视频
Media/AudioPlayer 音频组件，可用于播放音频
MeetingAndSchedule 会议和日程组件，用于预定和展示会议和日程
MeetingAndSchedule/List 日程和会议列表组件，用于查看日程和会议列表
<a id="moretip">MoreTip</a> “您可以这样问”组件，用于展示意图推荐列表，点击可以直接发送意图。组件内调用了CommonCard组件，并指定type字段为list,同时传入了listData、listName和listItemClick字段，用于展示列表数据、指定展示的字段名和点击列表项触发的事件，以及传入color、text、icon用来指定卡片头部的颜色、文字和图标，最终还有指定文字颜色高亮的字段textHighLight的值为true。
MoreTip/MoreRecommend "猜你想问"组件，用于展示意图推荐列表，点击可以隐式发送推荐意图的id,组件内调用了CommonCard组件，并指定type字段为list,同时传入了listData、listName和listItemClick字段，用于展示列表数据、指定展示的字段名和点击列表项触发的事件，以及传入color、text、icon用来指定卡片头部的颜色、文字和图标。
<a id="selector">Selector</a> 选择器组件，用于展示选择器，如选择文档、选择会议时间等。基于CommonCard组件开发,组件内调用了CommonCard组件，并指定type字段为list,同时传入了listData和listItemClick字段，用于展示列表数据和点击列表项触发的事件,以及根据不同的意图返回结果指定卡片头部的颜色、文字和图标，文字颜色是否高亮和列表项右箭头显隐.
Selector/BookMeeting 会议预定场景下的选择器组件，用于展示选择器（多选），如选择参会人员、会议时间等。基于CommonCard组件开发，组件内调用了CommonCard组件，并指定type字段为checkbox,同时传入了listData和listItemClick字段，用于展示列表数据和点击列表项触发的事件,以及根据不同的意图返回结果指定卡片头部的颜色、文字和图标。最后通过props.children在卡片底部插入了确认按钮。
Weather 天气组件，用于展示天气信息

4. 远程组件

介绍

远程组件是针对不同平台、业务、领域具有特殊业务场景下表达的组件。通常通过VPAUIResourceID进行判别。

使用

远程组件通常由对应领域场景下的开发人员在本平台进行开发，组件的代码和资源通常放在业务人员本地，由业务对应人员进行后台的配置。

开发人员重点关注的是通过本平台提供的能力进行对远程组件的开发。

是否仍需要帮助？ 请保持联络！
最后更新于 2025/09/15