3.3.4VPA接口
VPA接口
1. 介绍
在 VPA 和 VPA 卡片开发过程中，我们提供了一些接口，方便开发者进行开发。这些接口主要分为三个部分：
以 vpa 开头的接口
这些接口是 VPA 业务逻辑中比较常用的，和业务相关的接口。例如 vpa.notify 接口，用于和宿主环境通信和交互。
主要是面向卡片开发者的接口，旨在提供一个快捷的、黑盒的简便方法，去实现复杂的业务逻辑。
这些接口的过程，依赖于本文章第二部分和第三部分的接口来实现，卡片开发者无需过度关心。具体的接口文档请参考。
以 xiaoyouLight 开头的接口
这些接口最先是出现在移动端的模块中，也是智友和后端交互的核心模块。
在友空间 APP 端是调用原生模块进行发起请求和处理响应。
在非移动端环境下，例如在开发模式下和 PC 端友空间模式下，通过 axios 模块进行模拟请求和响应，完全 1：1
复刻出一个 xiaoyouLight 模块，在入参和回调方面，是和原生模块保持一致的。
以 api 开头的接口
这些接口是多端环境中，能够自动适配和调用的接口，用于处理基础的、通用的业务逻辑。
例如获取界面的风格样式，以及基础的 toast 和 alert 等，具体的实现，是由宿主环境来实现的。
例如在友空间 APP 端，则是调用友空间 APP 的相关 bridge 。
具体的接口文档请参考 api 文档。
以 mtl 开头的接口
这些接口是多端环境中，能够自动适配和调用的接口，用于处理基础的、通用的业务逻辑。
例如获取当前的位置信息，具体的实现，是由宿主环境来实现的。
例如在友空间 APP 端，则是调用友空间 APP 的相关 bridge 。
具体的接口文档请参考 mtl 文档。
2.VPA
属性
platform
表示当前 VPA 运行的平台，可选值参考 PlatformType。常常和 process.env.NODE_ENV 配合使用，用于区分不同平台的逻辑。
type PlatformType =
'YZ_APP' // 友空间APP
| 'YZ_PC' // 友空间PC端
| 'APP' // APPLoader[vpa.tsx](..%2F..%2F..%2Fsrc%2Ffn%2Fvpa.tsx)
| 'WEB' // 普通浏览器
if (vpa.platform === 'YZ_APP') {
// 友空间APP
} else if (vpa.platform === 'YZ_PC') {
// 友空间PC端
} else if (vpa.platform === 'APP') {
// APPLoader
} else if (vpa.platform === 'WEB') {
// 普通浏览器
}
方法
ui
ui属性目前封装了react-vant组件库中的部分组件，包括：Popup、Dialog、ImagePreview、Notify和Toast，可以直接使用，具体使用方法参考https://react-vant.3lang.dev/components
vpa.ui.Toast.loading({
message: '加载中...',
forbidClick: true,
})
sendMessage
封装了将消息添加到消息列表，并向后端发送消息的方法。
- option
voiceInput:是否开启语音输入，默认为false。extendAttribute:扩展属性。customCollectData:自定义采集数据。askForContextId:请求上下文ID。askForCanvasNodeId:请求画布节点ID。msg：要发送的消息内容。clear：是否清空输入框，默认为false。display：是否显示发送，默认为true。（为false时不显示发送的内容）
vpa.sendMessage({ msg: '明天天气怎么样' })
notify
向友空间发送通知，用于打开应用、打开web页面等操作
- option
action：通知的动作名称。data：通知的数据。id：通知的 ID。- callback：回调函数。
vpa.notify(vpa.getYzAction(btn))
getYzAction
将后端接口的数据解析成友空间的 action 数据
- option：后端接口的数据。
param：动作参数。appType：应用类型。appParams：应用参数。actionCode：动作代码。params：参数。action：动作名称。id：动作 ID。
vpa.getYzAction(option)
useCardAction
将后端返回的cardAction解析，并向友空间发送通知
- data: 后端返回的cardAction数据
cardAction：卡片动作。- callback: 回调函数
vpa.useCardAction({ cardAction })
handleCardClickAction
处理后端发挥的卡片点击动作，向友空间发送通知
- data: 后端返回的cardAction数据
cardClickAction：卡片点击动作。- callback: 回调函数
vpa.handleCardClickAction({ cardClickAction })
useTranslation
封装了react-i18next的useTranslation方法用于国际化，接受一个 TranslationObject 类型的参数，返回一个包含 t 和 i18n
属性的对象。
function Demo () {
const { t } = vpa.useTranslation({
en: {
p1: 'No satisfactory answer? I will helps you',
p2: 'leave a message',
p3: 'to HR'
},
zhs: {
p1: '没有满意答案？智友帮你向HR',
p2: '留言',
p3: ''
},
zht: {
p1: '沒有滿意答案？智友幫你向HR',
p2: '留言',
p3: ''
}
})
// 在组件的`jsx`中使用 `t` 方法调用翻译内容:
return <div>
{t('p1')}
<span>{t('p2')}</span>
{t('p3')}
</div>
}
Link
链接组件，用于应用页面间的跳转
import { Link } from './vpa'
<Link to = "/help"
singleInstance = { false } >
<div>
</div>
< /Link>
openPage
// openPage 方法的参数选项
interface OpenPageOptions {
url: string // 网址 必填
hideNavBar?: boolean // 是否隐藏导航栏 可选（默认为 false)
withkey?: 0 | 1 // 是否带上 key 可选（默认为 0)
}
const option: OpenPageOptions = {
url: 'https://baidu.com'
}
vpa.openPage(option)
封装了notify方法，用于通知友空间打开web页面
setInputMode
用于设置输入框的输入模式：键盘输入/语音输入
mode: 输入模式，text：键盘输入，voice：语音输入
vpa.setInputMode('voice')
getVpaDomain
获取域名
vpa.getDomain().then(host => {
console.log(host)
})
getDomain
获取域名
vpa.getDomain().then(host => {
console.log(host)
})
previewImage
预览图片
option: 预览图片的参数current: 当前显示图片的链接urls: 需要预览的图片链接列表showmenu: 是否显示菜单按钮success: 成功回调fail: 失败回调complete: 结束回调
vpa.previewImage({
current: '',
urls: []
});
request
封装了api.ajax方法，用于向后端发送请求
- option: 与
api.ajax方法的参数一致 - dataCenter: 数据中心
vpa.request({
url: '',
method: 'post',
data: {},
dataType: 'json',
headers: {},
returnAll: false,
timeout: 30,
cache: false,
traditional: false
})
openContactsCard
打开通讯录个人页
- option:
- yhtUserId: 友空间用户id
- memberId: 成员id
- callback: 回调函数
vpa.openContactsCard({
yhtUserId: '',
memberId: ''
})
keepNext
设置下一次的会话控制权。
/**
* 保持下一次的会话控制权
* @param data 传递给下一次的会话的数据
* @param rid 下次会话的资源ID，不传则默认为当前会话的资源ID
*/
vpa.keepNext(data, rid)
disposeNext
释放下一次的会话控制权。
vpa.disposeNext()
addEvent
添加事件监听
eventName: 事件名称callback: 回调函数
export default function CardDemo ({ step }) {
useEffect(() => {
const fn = () => {
console.log('卡片的 viewappear 事件触发了')
}
vpa.addEvent('viewappear', fn)
return () => {
vpa.removeEvent('viewappear', fn)
}
})
}
removeEvent
移除事件监听
eventName: 事件名称callback: 回调函数
vpa.removeEvent('event', () => {
console.log('event')
})
execEvent
执行事件监听
eventName: 事件名称data: 传递给回调函数的数据
vpa.execEvent('event', { name: 'event' })
refreshLocation
刷新定位信息
vpa.refreshLocation().then(info => {
console.log('load location end', info)
}).catch(err => {
console.log('load location err', err)
})
```[api.ts](..%2F..%2F..%2Fsrc%2Ffn%2Fapi.ts)
#### getLocation
从缓存中读取定位信息
ts vpa.getLocation() // {location: {lat: "32.101010", lng: "113.324520", city: "北京市"}, expire: 1690443193763} // 若没有缓存信息，则返回 {location: {},empty: true,expire: 0}
#### getEvn
获取当前环境，取值范围：`prod`、`pre`、`daily`、`test`
```ts
vpa.getEvn() // 'prod' | 'pre' | 'daily' | 'test'
setExtendAttribute
设置发送中的共享数据，同步web端的 window.xiaoyouRobot.setConfig
key: stringvalue: any
vpa.setExtendAttribute(key, value)
util.*
util属性内的方法为项目中会用到的一些工具方法，比如防抖、节流、生成唯一ID等；还会有一些常量，比如事件名等；
该属性内的方法常用于项目底包的逻辑适配，不建议卡片开发者使用。但是在部分特殊的业务场景下，为了更好的和底包逻辑适配，减少轮子和冗余代码，特此向卡片开发者开放。
getGUID()
生成唯一ID，用于对话ID、消息ID等
vpa.util.getGUID() // 生成的ID类似于：'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'
setData()
存储数据到 localStorage。
key: 存储的键名。data: 存储的数据。
vpa.util.setData('key', 'data')
getData()
从 localStorage 中获取数据。
key: 获取的键名。
vpa.util.getData('key')
createUrl()
创建一个 URL。App环境中或者非开发环境中会自动拼接域名；开发环境中不会拼接域名。
host: 域名或IP。path: 路径。
vpa.util.createUrl(host, `/iuap-aip-vpa/apiregister/apppro/${robotVersion}/`)
getInitConfigFromNet()
通过网络请求获取初始化配置。
// 返回数据如下
// {
// appcode: 'diwork',
// deviceid: '...',
// domain: 'https://bip-test.yyuap.com/iuap-aip-vpa/apiregister',
// domainid: 'diwork',
// enterpriseid: '5417',
// isDialog: false,
// isShowHelpBox: true,
// isShowInputBox: true,
// robotVersion: 'v2',
// tenantid: '...',
// token: '...',
// uid: '...',
// userid: '...',
// yhtAccessToken: '...'
// }
processCallbackData()
checkPermission()
封装了权限校验的方法，可以根据传入的权限编码，判断当前用户是否有该权限。
getQueryParamValue()
获取URL中的参数值。
const initString = vpa.util.getQueryParamValue('init') || ''
resolveHtmlAndText()
处理消息中的html和text，将html转换为text，将text中的换行符转换为br标签；将链接转换为a标签等等。
data = vpa.util.resolveHtmlAndText(data)
throttle()
节流函数，用于控制函数的执行频率，比如滚动事件、resize事件等。
fn: 需要节流的函数。delay: 延迟时间。skipFirst: 是否跳过第一次执行。
const throttledSetVolume = vpa.util.throttle((volume) => {
setVolume(volume)
}, 300, true)
throttledSetVolume(volume)
debounce()
防抖函数，用于控制函数的执行频率，比如输入框输入事件、搜索框输入事件、键盘弹起事件等。
fn: 需要防抖的函数。delay: 延迟时间。
const setKBD = vpa.util.debounce(setKbHeight, 25)
setKBD(keyboardHeight)
VpaEventName
枚举属性，枚举了应用中常用的事件名称
enum VpaEventName {
'LONG_PRESS_TO_SPEAK' = 'LONG_PRESS_TO_SPEAK',
'SET_THEME' = 'SET_THEME',
'ON_LINE' = 'online',
'OFF_LINE' = 'offline',
'KEYBOARD_SHOW' = 'keyboardshow',
'KEYBOARD_HIDE' = 'keyboardhide',
}
sendEvent()
封装了api.sendEvent方法，用于发送事件。
name: 事件名称。data: 事件参数。
import { VpaEventName } from './util'
vpa.util.sendEvent(VpaEventName.SET_THEME, theme)
addEventListener()
封装了api.addEventListener方法，用于事件监听。
name: 事件名称。callback: 事件回调。
import { VpaEventName } from './util'
vpa.util.addEventListener(VpaEventName.SET_THEME, theme => {
console.log(theme)
})
getAvatar()
获取用户头像地址
scrollToBottom()
平滑滚动到底部
- delay: 延迟时间
vpa.util.scrollToBottom(100) // 延时100ms后滚动到底部
isRemoteCard()
判断是否是远程卡片
loadCSS()
动态加载css文件
serverAPI()
apiName: 接口名称option: 接口参数 封装了axios请求方法，用于向/serverAPI?${apiName}接口发送请求，模拟返回script目录下的js文件
vpa.util.serverAPI('getH5Zip', option).then(callback)