3.3.4VPA接口

VPA接口

1. 介绍

在 VPA 和 VPA 卡片开发过程中,我们提供了一些接口,方便开发者进行开发。这些接口主要分为三个部分:

vpa 开头的接口

这些接口是 VPA 业务逻辑中比较常用的,和业务相关的接口。例如 vpa.notify 接口,用于和宿主环境通信和交互。

主要是面向卡片开发者的接口,旨在提供一个快捷的、黑盒的简便方法,去实现复杂的业务逻辑。

这些接口的过程,依赖于本文章第二部分和第三部分的接口来实现,卡片开发者无需过度关心。具体的接口文档请参考。

xiaoyouLight 开头的接口

这些接口最先是出现在移动端的模块中,也是智友和后端交互的核心模块。

在友空间 APP 端是调用原生模块进行发起请求和处理响应。

在非移动端环境下,例如在开发模式下和 PC 端友空间模式下,通过 axios 模块进行模拟请求和响应,完全 1:1 复刻出一个 xiaoyouLight 模块,在入参和回调方面,是和原生模块保持一致的。

api 开头的接口

这些接口是多端环境中,能够自动适配和调用的接口,用于处理基础的、通用的业务逻辑。

例如获取界面的风格样式,以及基础的 toastalert 等,具体的实现,是由宿主环境来实现的。

例如在友空间 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 类型的参数,返回一个包含 ti18n 属性的对象。

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>

}

链接组件,用于应用页面间的跳转

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: string
  • value: 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)
是否仍需要帮助? 请保持联络!
最后更新于 2024/05/20