更新记录

1.0.0（2026-06-13）下载此版本

cf-uniwebview 接入说明

cf-uniwebview 用来在 App 内打开原生 WebView，并给 H5 提供一层统一 JSBridge。

当前仓库里它分成两部分：

App 侧打开入口：webview-plugin.uts
H5 Bridge 工具：webview-bridge.js

原生实现位置：

iOS：app-ios/index.uts
Android：app-android/CFUniWebViewAndroidPlugin.kt

App 侧用法

打开网页

import { openNativeWebView } from '@/services/native/webview-plugin.uts'

openNativeWebView({
  linkUrl: 'https://example.com',
  platformName: 'xxxxxx',
  platformCode: 'accountbutler',
  customUserAgent: 'your-ua',
  topBarHidden: false,
  openMode: 'present',
  animated: true,
  fullscreen: true
}, (res : any) => {
  console.log('webview callback =', res)
})

参数说明

linkUrl: 打开的地址
platformName: 传给 H5 的平台名
platformCode: 传给 H5 的平台编码
token: 传给 H5 的 token
customUserAgent: 自定义 UA
topBarHidden: 是否隐藏原生导航栏
openMode: 'present' 或 'push'
animated: 是否带动画
fullscreen: 是否全屏模态展示
origin: 原样透传给 H5 的扩展字段

App 回调

H5 关闭并回传：

{
  action: 'plugWebView',
  data: {
    success: true,
    orderId: '123456'
  }
}

H5 持续发消息：

{
  action: 'postMessage',
  data: {
    type: 'stepChange',
    step: 2
  }
}

用户主动关闭：

{
  action: 'dismiss'
}

H5 侧用法

推荐直接使用：

import {
  getPlugData,
  getDeviceInfo,
  getLocation,
  getLoaction,
  openAppSettings,
  openNativeUrl,
  postMessageToApp,
  copyText,
  getImageFromPhotoLibrary,
  takePhoto,
  saveImageToLibrary,
  callPhone,
  plugWebView
} from '@/uni_modules/cf-uniwebview/utssdk/webview-bridge.js'

这些方法同时支持：

Promise 风格
callback 风格

例如：

const info = await getDeviceInfo()

getDeviceInfo((info) => {
  console.log(info)
})

H5 能力清单

获取 App 传参

const plugData = await getPlugData()

通常会返回：

platformName
platformCode
linkUrl
token
topBarHidden
fullscreen
openMode
animated
origin

获取设备信息

const deviceInfo = await getDeviceInfo()

获取定位

const location = await getLocation()

兼容旧拼写：

const location = await getLoaction()

成功示例：

{
  success: true,
  locationSuccess: true,
  errorMsg: '',
  latitude: 31.2304,
  longitude: 121.4737,
  accuracy: 35,
  location: {
    latitude: '31.2304',
    longitude: '121.4737'
  }
}

常见失败值：

location_permission_denied
location_provider_disabled
location_timeout
location_busy

打开系统设置页

await openAppSettings()

打开外部链接

await openNativeUrl({
  url: 'weixin://',
  fallbackUrl: 'https://weixin.qq.com/'
})

支持：

url
fallbackUrl
failOpenUrl
backupUrl

给 App 发消息但不关闭页面

await postMessageToApp({
  type: 'progress',
  value: 50
})

关闭页面并回传

await plugWebView({
  success: true,
  orderId: '123456'
})

复制文本

await copyText('abc123')

从相册选图

const image = await getImageFromPhotoLibrary()

需要 base64：

const image = await getImageFromPhotoLibrary({
  returnBase64: true
})

返回示例：

{
  success: true,
  fileName: 'image.jpg',
  mimeType: 'image/jpeg',
  size: 12345,
  tempFilePath: '/.../cache/xxx-image.jpg',
  base64: 'data:image/jpeg;base64,...'
}

拍照

const photo = await takePhoto()

需要 base64：

const photo = await takePhoto({
  returnBase64: true
})

返回结构和 getImageFromPhotoLibrary() 对齐。

保存图片到相册

await saveImageToLibrary({
  url: 'https://example.com/test.jpg'
})

支持这些输入：

远程图片 URL
data:image/...;base64,...
content://...
file://...
本地绝对路径

成功示例：

{
  success: true,
  savedUri: 'content://...',
  fileName: 'image.jpg',
  mimeType: 'image/jpeg',
  size: 12345
}

拨打电话

await callPhone({
  phoneNumber: '***'
})

也支持：

await callPhone('***')
await callPhone({ mobile: '***' })
await callPhone({ tel: '***' })
await callPhone({ phone: '***' })

直接使用 JSBridge

如果不想引入 webview-bridge.js，也可以直接调用：

window.WebViewJavascriptBridge.callHandler('getPlugData', null, cb)
window.WebViewJavascriptBridge.callHandler('getDeviceInfo', null, cb)
window.WebViewJavascriptBridge.callHandler('getLocation', null, cb)
window.WebViewJavascriptBridge.callHandler('openAppSettings', null, cb)
window.WebViewJavascriptBridge.callHandler('openUrl', { url: 'weixin://' }, cb)
window.WebViewJavascriptBridge.callHandler('postMessageToApp', { type: 'x' }, cb)
window.WebViewJavascriptBridge.callHandler('copyText', { text: 'abc123' }, cb)
window.WebViewJavascriptBridge.callHandler('getImageFromPhotoLibrary', { returnBase64: true }, cb)
window.WebViewJavascriptBridge.callHandler('takePhoto', { returnBase64: true }, cb)
window.WebViewJavascriptBridge.callHandler('saveImageToLibrary', { url: 'https://example.com/test.jpg' }, cb)
window.WebViewJavascriptBridge.callHandler('callPhone', { phoneNumber: '***' }, cb)
window.WebViewJavascriptBridge.callHandler('plugWebView', { success: true }, cb)

平台说明

Android

使用 WebView URL 拦截形式实现桥接
getLocation() 已接通，并带权限申请
getImageFromPhotoLibrary() 已接通
takePhoto() 已接通
saveImageToLibrary() 已接通
callPhone() 已接通
内嵌 H5 的 uni.chooseImage() 已做原生兜底

iOS

使用注入脚本 + 轮询信号形式实现桥接
openNativeUrl({ url: 'tel://' }) 可用于拨号
callPhone() 内部也是复用 openNativeUrl 打开 tel://
图片、定位、保存图片等能力已接通

常见错误码

通用

bridge_unavailable: 当前不在原生 WebView 环境，或桥尚未注入完成
invalid_url: 传入的链接无效
activity_unavailable: 当前原生页面或宿主上下文不可用

定位

location_permission_denied: 定位权限被拒绝
location_provider_disabled: 系统定位服务未开启
location_timeout: 定位超时
location_busy: 已有一个定位请求正在进行
location_unavailable: 当前设备无法提供定位能力

相册 / 图片

picker_busy: 已有一个选图流程正在进行
picker_unavailable: 当前设备无法拉起系统选图
invalid_image: 图片读取失败或返回内容无效
image_permission_denied: 图片读取兜底权限被拒绝
cancel: 用户取消了选图

拍照

camera_permission_denied: 相机权限被拒绝
camera_unavailable: 当前设备无法拉起系统相机
camera_busy: 已有一个拍照流程正在进行

保存图片

invalid_image_url: 图片地址为空或格式不支持
save_permission_denied: 保存图片权限被拒绝
save_failed: 保存到系统相册失败
save_busy: 已有一个保存流程正在进行

拨号

invalid_phone_number: 手机号为空或格式无效
call_permission_denied: 电话权限被拒绝
call_unavailable: 当前设备无法发起拨号
call_busy: 已有一个拨号流程正在进行

权限说明

Android Manifest

当前插件会用到这些权限：

android.permission.INTERNET
android.permission.CALL_PHONE
android.permission.CAMERA
android.permission.ACCESS_FINE_LOCATION
android.permission.ACCESS_COARSE_LOCATION
android.permission.READ_MEDIA_IMAGES
android.permission.READ_EXTERNAL_STORAGE
android.permission.WRITE_EXTERNAL_STORAGE maxSdkVersion="28"

新增权限后，需要重新打自定义基座或重新打安装包，纯热更新不会生效。

iOS

图片、相机、定位、电话能力都依赖系统本身的权限或能力状态，请同步检查宿主工程的权限说明文案。

平台兼容性

uni-app x(4.21)

Chrome	Safari	Android	iOS	鸿蒙	微信小程序
×	×	7.0	13	-	×

UniWebView webView，交互