3.3.1VPA卡片开发规范

VPA卡片开发规范

本节介绍了不同场景下开发VPA卡片时建议遵循的规范。

1.组件定义

组件为一个标准的 React 组件，组件定义支持函数或类式组件。入口必须要默认导出

函数组件

export default function MyCard (props) {
  const { data } = props;
  return (
    <div>
      <h3>{data.text}</h3>
    </div>
  )
}

类组件

import React from 'react';

export default class MyCard extends React.Component {
  render () {
    const { data } = this.props;
    return (
      <div>
        <h3>{data.text}</h3>
      </div>
    )
  }
};

2.svg类型引入

如果使用svg类型的图片作为引入，在确定引入类型为文件时，需要在后方加“?file”

示例代码

import svgFile from './sample.svg?file' // svg以文件的方式被引入

3.参数接收

组件中通过 data 字段来接收参数，data 的值为 JSON 对象，里面的内容为智能中台返回的模型数据，每个模型对应的数据可能完全不一样，例如以下为“签到”卡片接收到的 data 数据：

{
  "stopMicrophone": true,
  "cardClickAction": {
    "param": {
      "appType": "origin",
      "needForget": false,
      "appParams": {
        "actionCode": "opensignin",
        "params": {}
      }
    },
    "action": "applink"
  },
  "modelID": 18,
  "cardAction": {
    "param": {
      "appType": "origin",
      "needForget": false,
      "appParams": {
        "actionCode": "opensignin",
        "params": {}
      }
    },
    "action": "applink"
  },
  "text": "正在为您打开应用",
  "title": {
    "icon": "https://iuap-aiplatform-picdoc.oss-cn-beijing.aliyuncs.com/webrobotresource/img/signIn.png",
    "text": "一键签到"
  },
  "content": {
    "showData": {},
    "modelData": {}
  }
}

组件内接收组件参数示例：

export default function MyCard (props) {
  const { data } = props;
  return (
    <div>
      <h3>{data.text}</h3>
    </div>
  )
}

4.动作事件处理

卡片中有时需要调用友空间原生的功能，例如打开签到应用、点击联系人卡片中的发送消息按钮后，需要通知友空间打开聊天对话窗口等。这些操作通过调用 vpa 对象的 notify 方法来实现。

示例代码

/*
action: 动作名称
data: 此次动作对应的参数
callback: 友空间处理动作后的回调
*/
vpa.notify({
  action: 'opensignin',
  data: {
    'appType': 'origin',
    'needForget': false,
    'appParams': {
      'actionCode': 'opensignin',
      'params': {}
    }
  }
}, (res) => {

})

5.发送消息

卡片有时候会给用户提供选择项，例如“红皮书”卡片会展示一个列表，让用户选择列表中的哪一项，用户选择后会在聊天列表发送一条第几个 这样的消息，发送消息功能在卡片组件中需要调用 vpa 对象的 sendMessage 方法来实现。

示例代码

/*
msg: 消息内容
*/
vpa.sendMessage({
  msg: '第1个'
})

6.CSS规范

使用CSS Modules来管理组件的样式，避免样式冲突和污染。使用驼峰命名法来命名CSS类，以提高可读性和可维护性。

示例代码

/*MoreTip.module.css*/
.list {
    padding: 0;
    margin: 0;
}

// index.tsx
import styles from './MoreTip.module.css';

<div className={styles.list}></div>

模块化 css 中，class 类名推荐使用小驼峰命名方式，不推荐使用中划线“-”。

示例代码

<div className={innerStyle.rangeLabel}></div> // 推荐

<div className={innerStyle['range-label']}></div> // 不推荐

同时还支持 Less、Sass、Scss 等预处理器，使用方法与 CSS 相同。需要使用模块化的方式引入，例如：

import myCss from './my.module.css'

import myLess from './my.module.less'

import myScss from './my.module.scss'

import mySass from './my.module.sass'

详细例子请参考项目中，src/@remote/demos/CardDemo 组件。

7.全局状态管理（Redux）

项目使用react-redux实现全局状态管理，并使用@reduxjs/toolkit 简化redux复杂的配置和使用。Redux相关代码主要存放于src/redux目录下。

src/redux目录下的xxxSlice.ts文件为各个模块的状态管理文件。文件中定义了模块的状态、状态初始值，以及状态更新方法。

src/redux/store.ts文件，整合当前目录下其他的xxxSlice.ts状态管理文件，为redux的store配置文件。导出dispatch 方法，用于在组件中修改全局状态。

组件内使用useSelector和dispatch方法来访问和修改全局状态。

示例代码

import { useSelector } from 'react-redux'
import settingSlice from './settingSlice'
import { dispatch } from './store'
// 访问
const voiceOn = useSelector((state) => state.setting.voiceOn)
// 修改
dispatch(settingSlice.actions.setLongPressToSpeak(true))
是否仍需要帮助？ 请保持联络！
最后更新于 2024/04/24