webview capability

简介

目的是为不同webview下的h5页面提供统一标准的js api容器能力，建议移动端项目使用此组件。

原理目前是根据user agent实现的，后续可以考虑调整为js api响应结果

设计思路是使用适配器实现接口，实现不同容器的相关能力，后续就算要跑在其它的容器内也能直接兼容

说明

主要特性

1. 支持多种容器：目前已实现普通浏览器和专有钉/浙政钉；
2. 开发友好：当我们开发集成在某个专用app的h5页面时，通常使用chrome devtools进行模拟，如果页面中使用了专用的api则会导致调试困难，此组件很好地解决了这个问题；
3. 支持回落机制：当专有的webview提供的js api接口抛出异常，则回落到普通浏览器的能力，保障功能可以正常使用；
4. 使用简单：wvc.event、wvc.debug、wvc.ui、wvc.device、wvc.file、wvc.page、wvc.userAgent；
5. 通过e2e测试：使用cypress验证相关接口，使用更加安全；
6. 提供扩展能力：直接继承Browser的相关Adapter，可以快速支持各种app的webview提供的js api。
7. 灵活覆盖：你可以在调用侧覆盖部分wvc的能力，让开发更加灵活

webview适配情况

1. [x] 普通浏览器
2. [x] 专有钉/浙政钉
3. [ ] 钉钉
4. [ ] 微信
5. [ ] 浙里办

快速安装

目前内部使用：

# yarn 
yarn add webview-capability
# npm
npm install webview-capability

使用说明

方式一

使用已实例化的wvc对象

import { wvc } from 'webview-capability'

wvc.ui.alert('hello world')

await wvc.file.preview({
    fileId: '123',
    fileName: 'xxxx.pdf',
    fileUrl: 'https://xxx/xxx.pdf'
})

方式二

自行实例化

const webviewCapability = new WebviewCapability()

await webviewCapability.device.setStorageItem('hello', 'world')

webviewCapability.page.open('http://localhost:8080/your_page')

测试说明

由于本项目依赖容器能力，故而测试框架使用了cypress，适配了window对象，即项目中的BrowserWebview。

后续也可以将针对其它容器的能力，考虑添加一些mock函数，让开发者开发起来更加灵活方便，不再需要手机调试。

常用接口说明

容器特有能力

js api鉴权

const { data: result } = await axios.get('/YOUR_JSTICKET_API_POINT')
const { jsTicket } = result.data
wvc.webview.config({
    ticket: jsTicket
})

免登code获取

const res = await wvc.webview.requestAuthCode()
code = res?.auth_code || res.code
const { data: result } = await this.$api.post('/YOUR_SSO_API_POINT', { code })

调试

1、启动和关闭vConsole

wvc.debug.enable = true
wvc.debug.enable = false

文件

1、文件预览

• 浏览器：相当于window.open
• 专有钉：使用专有钉内置文件预览（需要鉴权）

await wvc.file.preview({
    fileId: '123',
    fileName: 'xxxx.pdf',
    fileUrl: 'https://xxx/xxx.pdf'
})

2、文件下载

• 浏览器：相当于window.open
• 专有钉：使用专有钉内置文件下载能力

await wvc.file.download({
    id: '123',
    name: 'xxxx.pdf',
    url: 'https://xxx/xxx.pdf'
})

3、文件分享

• 浏览器：相当于window.open
• 专有钉：使用专有钉内置文件分享到IM的能力

await wvc.file.shareToMessage({
    content: '我要分享给你',
    title: '提示',
    url: 'https://xxx/xxx.pdf'
})

页面路由

1、页面hash模式跳转

• 浏览器：相当于window.location.hash
• 专有钉：打开一个新的webview，页面跳转到该hash路由下。

const locate = router.resolve({
    path: '/flow/detail',
    query: {
        id: '123'
    }
})
wvc.page.hash(locate.href)

2、页面返回上一页

• 浏览器：相当于window.history.back()
• 专有钉：关闭当前webview

wvc.page.back()

用户界面

1、提示

wvc.ui.alert({
    message: '你好啊！'
})

2、设置页面标题

• 浏览器：相当于window.document.title
• 专有钉：设置titleBar的中间位置的文本

await wvc.ui.setTitle({
    title: '你好啊！'
})

3、显示和隐藏titleBar右上角的按钮

• 浏览器：无效果
• 专有钉：隐藏titleBar右上角的按钮

wvc.ui.hideOptionMenu()
wvc.ui.showOptionMenu()

4、设置导航右上角区域内容

• 浏览器：无效果
• 专有钉：设置标题栏右边的按钮属性。 此接口仅负责设置，需要额外调用 showOptionMenu 保证该按钮的显示。

// 设置单个按钮
await wvc.ui.setOptionMenu({
    title: '新增',
    icontype: 'add'
})
// 设置多个按钮
await wvc.ui.setOptionMenu({
    menus: [{
        title: '保存',
        icontype: 'add'
    },{
        title: '操作',
        icontype: 'settings'
    }]
})

设备

• 浏览器：相当于window.localStorage
• 专有钉：跨webview存储到设备中

1、获取免登录code

// 获取免登录code
await wvc.device.getAuthCode({corpId: ''})

2、获取当前用户信息

// 获取当前用户信息
await wvc.device.getLoginUser()

3、存储信息

const key = 'hello'
const value = 'world'

// 设置存储信息
await wvc.device.setStorageItem(key, value)

// 获取存储信息
let storageValue = await wvc.device.getStorageItem(key)

// 删除存储信息
await wvc.device.removeStorageItem(key)

4、打电话

// 打电话
await wvc.device.callPhone({phoneNum: '10086'})

事件

1、注册和解除事件

const callback = () => {}
// 注册事件
wvc.event.on('resume', callback)

// 解除事件
wvc.event.off('resume', callback)

// 手动执行事件
wvc.event.dispatch('resume', 'YOUR_RESULT')

其他

1、关闭回落模式

回落模式允许专有容器能力调用失败回落到普通浏览器的默认能力实现上。组件export出的wvc默认开启，如果不想开启可以自行配置关闭

const wvc = new WebviewCapability({ enableFallback: false })
export { wvc }

2、自实现免登录code

允许用户自己实现免登相关逻辑

const wv = new WebviewCapability({
    getAuthCode: (args) => {
        // 模拟异步操作，返回一个 Promise
        return new Promise((resolve) => {
            // 模拟异步获取 authCode
            setTimeout(() => {
                resolve({
                    expireTime: 1000,
                    code: '111'
                })
            }, 1000)
        })
    }
})

const { code: res } = await wv.device.getAuthCode({})