更新记录

1.0.4(2024-04-01)

  1. 修复跟新版本基座某些模块打包冲突问题

1.0.3(2022-11-09)

增加离线安装内核API

1.0.2(2022-08-22)

  1. 升级X5版本,由44085升级到44216
  2. 增加下载x5内核进度监听、开始/暂停/取消下载、当前是否是X5、版本号获取等等接口API
查看更多

平台兼容性

Android Android CPU类型 iOS
适用版本区间:4.4 - 14.0 armeabi-v7a:未测试,arm64-v8a:未测试,x86:未测试 ×

原生插件通用使用流程:

  1. 购买插件,选择该插件绑定的项目。
  2. 在HBuilderX里找到项目,在manifest的app原生插件配置中勾选模块,如需要填写参数则参考插件作者的文档添加。
  3. 根据插件作者的提供的文档开发代码,在代码中引用插件,调用插件功能。
  4. 打包自定义基座,选择插件,得到自定义基座,然后运行时选择自定义基座,进行log输出测试。
  5. 开发完毕后正式云打包

付费原生插件目前不支持离线打包。
Android 离线打包原生插件另见文档 https://nativesupport.dcloud.net.cn/NativePlugin/offline_package/android
iOS 离线打包原生插件另见文档 https://nativesupport.dcloud.net.cn/NativePlugin/offline_package/ios

注意事项:使用HBuilderX2.7.14以下版本,如果同一插件且同一appid下购买并绑定了多个包名,提交云打包界面提示包名绑定不一致时,需要在HBuilderX项目中manifest.json->“App原生插件配置”->”云端插件“列表中删除该插件重新选择


前言

wrs-x5webview是腾讯X5内核浏览器组件,支持本地、网络url、h5源码富文本,加载进度、加载结果回调,H5 js、nvue通讯传值、文件选择、相机拍照、相机录像、录音、alert、confirm、prompt,打开文件格式,doc、docx、ppt、pptx、xls、xlsx、pdf、txt、epub,调用QQ浏览器可打开:rar(包含加密格式)、zip(包含加密格式)、tar、bz2、gz、7z(包含加密格式)、doc、docx、ppt、pptx、xls、xlsx、txt、pdf、epub、chm、html/htm、xml、mht、url、ini、log、bat、php、js、lrc、jpg、jpeg、png、gif、bmp、tiff 、webp、mp3、m4a、aac、amr、wav、ogg、mid、ra、wma、mpga、ape、flac

为了提供更多API和及时更新X5版本,请不要勾选uniapp提供的“App模块设置” -》 “Android X5 WebView(腾讯TBS)”,否则会有打包报错或API不兼容问题

功能

  • 支持本地、网络url、h5源码富文本, 加载进度、加载结果回调
  • 支持H5 js、nvue通讯互调传值
  • 支持文件选择、相机拍照、相机录屏
  • 支持alert、confirm、prompt
  • 打开文件

wrs-x5webview组件

<wrs-x5webview 
:config="config" 
ref='webview' 
:url="url"
:style="'width:'+width+'px;height:'+height+'px;'" 
@onLoadStart="" 
@onLoadFinish="onLoadFinish" 
@onLoadError="onLoadError" 
@onProgress="" 
@onJSData="onJSData">
</wrs-x5webview>

属性

  • url webview加载地址,可以是本地H5文件地址或远程网络地址
  • config 配置 progressColor 进度条颜色 scrollIndicator 是否显示滚动条
  • onLoadStart 开始加载
  • onLoadFinish 加载完成
  • onLoadError 加载出错
  • onProgress 加载进度
  • onJSData 接收到H5 js发送的数据

方法

X5官网https://x5.tencent.com/docs/index.html 目前开放以下接口,如需更多接口,请联系作者(QQ:252797991)

var x5webviewmgr = uni.requireNativePlugin("wrs-x5webviewmgr");

  • 初始化插件(已弃用,但还支持)

var params = {};
params.downloadWithoutWifi = true; // 没有Wi-Fi时是否自动下载x5内核,微信用的就是x5内核,大部分人都下有微信,会跟微信公用内核,所有一般设置为true
x5webviewmgr.init(params);
  • 为了提高内核占比,在初始化前可配置允许移动网络下载内核(大小 40-50 MB)。默认移动网络不下载

非wifi下下载tbs设置接口,默认为false不可下载,设置为true 应用层必须提示用户 流量资费


var params = {};
params.downloadWithoutWifi = true;
x5webviewmgr.setDownloadWithoutWifi(params);
  • 设置开启优化方案,在调用TBS初始化、创建WebView之前进行如下配置

var params = {};
params.use_speedy_classloader = true;
params.use_dexloader_service = true;
x5webviewmgr.initTbsSettings(params);
  • 初始化SDK环境,在App启动后尽可能早地调用初始化接口,进行内核预加载

异步初始化X5 webview所需环境 此过程包括X5内核的下载、预初始化,接入方不需要接管处理x5的初始化流程,希望无感接入


x5webviewmgr.initX5Environment((resp)=>{
    var opt = resp.opt;
    if(opt == "onViewInitFinished") {
        //x5內核初始化完成的回调,为true表示x5内核加载成功,否则表示x5内核加载失败,会自动切换到系统内核。
        // 预初始化结束
        // 由于X5内核体积较大,需要依赖wifi网络下发,所以当内核不存在的时候,默认会回调false,此时将会使用系统内核代替
        // 内核下发请求发起有24小时间隔,卸载重装、调整系统时间24小时后都可重置
        // 调试阶段建议通过 WebView 访问 debugtbs.qq.com -> 安装线上内核 解决
        var isX5 = resp.isX5;

    } else if(opt == "onCoreInitFinished") {
        // 内核初始化完成,可能为系统内核,也可能为系统内核
    }
});
  • 内核下载/安装过程中的回调 TbsCommonCode 错误码参考官网

x5webviewmgr.setTbsListener((resp)=>{
    var opt = resp.opt;
    if(opt == "onDownloadFinish") {
        //下载结束时的状态,下载成功时errorCode为100,其他均为失败,外部不需要关注具体的失败原因
        var errCode = resp.errCode;

    } else if(opt == "onInstallFinish") {
         // 安装结束时的状态,安装成功时errorCode为200,其他均为失败,外部不需要关注具体的失败原因
        var errCode = resp.errCode;
    }
});
  • 当前进程内,SDK是否使用的X5内核,不触发加载、只关注当前状态

var resp = x5webviewmgr.isX5Core();
if(isString(resp)) {
    resp = JSON.parse(resp);
}
if(resp.flag) { // 是x5

}
  • 开始下载X5内核

x5webviewmgr.startDownload();
  • 暂停下载X5内核

x5webviewmgr.pauseDownload();
  • 停止下载X5内核

x5webviewmgr.stopDownload();
  • 允许终端设置最低版本的x5内核,默认为 -1 即不限制 参考202112最低版本

x5webviewmgr.setCoreMinVersion({
    minVersion: 45912
});
  • 清除重置整个TBS状态,包括SDK、内核,每次进程最多调用1次

x5webviewmgr.reset();
  • 强制使用系统内核,一般针对存在bug的内核版本或机型才使用 【提醒】调用此接口后,进程内所有WebView不能再恢复为X5内核

x5webviewmgr.forceSysWebView();
  • 获取Tbs sdk的版本号,用于统计及定位问题,每次sdk有修改时会提升版本号

var resp = x5webviewmgr.getTbsSdkVersion();
if(isString(resp)) {
    resp = JSON.parse(resp);
}
var version = resp.tbsSdkVersion;

x5webviewmgr.installLocalTbsCore({
    coreVersion: 46011, // 内核版本
    path: "/xxx/aa.apk"  // 内核路径
});

按照他人资料用法如下:


// 先判断当前不是x5内核,如果不是x5内核则重置后安装离线内核
var resp = x5webviewmgr.isX5Core();
if(isString(resp)) {
    resp = JSON.parse(resp)
}
var flag = resp.flag;
if(!flag) {
    x5webviewmgr.reset();
    x5webviewmgr.installLocalTbsCore({
        coreVersion: 46011, // 内核版本
        path: "/xxx/aa.apk"  // 内核路径
    });
}
  • 获取Tbs内核版本号,用于统计及定位问题

var resp = x5webviewmgr.getTbsVersion();
if(isString(resp)) {
    resp = JSON.parse(resp);
}
var version = resp.tbsVersion;
  • 获取当前X5加载不起来 or X5 不可用的帮助信息 SDK 44199

var resp = x5webviewmgr.getX5CoreLoadHelp();
if(isString(resp)) {
    resp = JSON.parse(resp);
}
var help = resp.help;
  • this.$refs.webview.sendDataToJS() 调用H5 JS的函数,并获取函数返回值

如:调用login函数,函数参数是‘123456’字符串

var params = {};
params.js = "login('123456')";
this.$refs.webview.sendDataToJS(params);
//
function login(account) {
    alert('登录,账号:' + account);
}

如果函数参数是个Object对象,则

var params = {};
params.account = '123456';
var options = {};
options.js = "register("+JSON.stringify(params)+")";
this.$refs.webview.sendDataToJS(options);
//
function register(params) {
    alert('注册,账号:' + params.account);
}

如果js函数有返回值,则

var params = {};
params.a = 1;
params.b = 2;
var options = {};
options.js = "add("+JSON.stringify(params)+")";
this.$refs.webview.sendDataToJS(options, (resp) => {
    console.log("a + b = " + resp.result);
});
//
function add(params) {
    return {
        result: params.a + params.b
    };
}
  • webview的H5 JS发送数据给nvue,会回调 @onJSData事件
var params = {};
params.msg = "你好,我是JS";
if(IOS) {
    window.webkit.messageHandlers.bridge.postMessage(params);
} else if (ANDROID) {
    var jsonStr = JSON.stringify(params);
    window.messageHandlers.bridge(jsonStr);
}

如果参数为空时,iOS需要传个空对象,防止出错,如:

if(IOS) {
    window.webkit.messageHandlers.bridge.postMessage({});
} else if (ANDROID) {
    window.messageHandlers.bridge();
}
  • this.$refs.webview.goBack() 返回上一个历史
  • this.$refs.webview.goForward() 前往下一个历史
  • this.$refs.webview.reload() 重新加载刷新
  • this.$refs.webview.stopLoading() 停止加载刷新
  • this.$refs.webview.backForwardList(callback) 获取当前历史
                this.$refs.webview.backForwardList((resp) => {
                    if(isString(resp)) {
                        console.log("listory is String");
                    } else {
                         console.log("listory is not String" );
                        resp = JSON.stringify(resp);
                    }
                     console.log("listory:" + resp );
                });
  • 获取网页title

                this.$refs.webview.getTitle((resp) => {
                    var title = resp.title;
                    this.title = title;
                    this.showMsg("title:" +title);
                });
  • 打开本地文件

文件格式,doc、docx、ppt、pptx、xls、xlsx、pdf、txt、epub,调用QQ浏览器可打开:rar(包含加密格式)、zip(包含加密格式)、tar、bz2、gz、7z(包含加密格式)、doc、docx、ppt、pptx、xls、xlsx、txt、pdf、epub、chm、html/htm、xml、mht、url、ini、log、bat、php、js、lrc、jpg、jpeg、png、gif、bmp、tiff 、webp、mp3、m4a、aac、amr、wav、ogg、mid、ra、wma、mpga、ape、flac

                var absPath = plus.io.convertLocalFileSystemURL('_www');
                // Android获取的absPath以/结尾,iOS获取的absPath不是/结尾
                if (absPath.endWith('/')) {
                    absPath = absPath.substring(0, absPath.length - 1);
                }
                var localUrl = absPath + "/static/test.docx"
                var params = {};
                params.filePath = localUrl,
                // params.extraParams = {};
                x5webviewmgr.openFileReader(params, (resp) => {
                    this.showMsg("openFileReader resp:" + resp.receiveValue);
                });
  • this.$refs.webview.goBackOrForward(params) 前进后退统一接口
var params = {};
params.index = -1; // index为-1表示后退,index为1表示前进
this.$refs.webview.goBackOrForward(params);
  • 保存网页
var params = {};
params.fileName = "/sdcard/xxxx/aa.png"; 
this.$refs.webview.saveWebArchive(params);
  • 快速向下,滚到底部
var params = {};
params.bottom = true; 
this.$refs.webview.pageDown(params);
  • 快速向上,滚到顶部
var params = {};
params.top = true; 
this.$refs.webview.pageUp(params);
  • 启用或禁用水平滚动条
var params = {};
params.enabled = true; 
this.$refs.webview.setHorizontalScrollBarEnabled(params);
  • 启用或禁用竖直滚动条
var params = {};
params.enabled = true; 
this.$refs.webview.setVerticalScrollBarEnabled(params);
  • 判断水平滚动条是否启动
var result = this.$refs.webview.isHorizontalScrollBarEnabled();
  • 判断垂直滚动条是否启动
var result = this.$refs.webview.isVerticalScrollBarEnabled();
  • 设置滚动条渐隐消失的时间段
var params = {};
params.duration = 1; 
this.$refs.webview.setScrollBarFadeDuration(params);
  • 设置滚动条多久开始渐隐消失
var params = {};
params.delay = 1; 
this.$refs.webview.setScrollBarDefaultDelayBeforeFade(params);
  • 清除cookie
this.$refs.webview.removeAllCookies((resp)=>{});
  • 清除storage相关缓存
this.$refs.webview.deleteAllData();
  • 清除用户密码信息
this.$refs.webview.clearUsernamePassword();
  • 清除httpauth信息
this.$refs.webview.clearHttpAuthUsernamePassword();
  • 清除表单数据
this.$refs.webview.clearFormData();
  • 清除页面icon图标信息
this.$refs.webview.removeAllIcons();
  • 删除地理位置授权,也可以删除某个域名的授权(参考接口类)
this.$refs.webview.clearAll();
  • 一次性删除所有缓存
this.$refs.webview.clearAllWebViewCache({isClearCookie: true});
  • 在非用户操作情况下利用window.open打开窗口被称为自动弹窗,该功能默认关闭,如果开启可以使用如下接口
var params = {};
params.open = true; 
this.$refs.webview.setJavaScriptCanOpenWindowsAutomatically(params);
  • 缩放比例记录与恢复是基于域名的,首先要开启对应开关功能
var params = {};
params.open = true; 
this.$refs.webview.setAutoRecoredAndRestoreScaleEnabled(params);
  • 设置文字大小
var params = {};
params.textZoom = 12; 
this.$refs.webview.setTextZoom(params);
  • 获取文字大小
var result = this.$refs.webview.textZoom();
  • 设置设置UA
var params = {};
params.ua = "ss"; 
this.$refs.webview.setUserAgentString(params);
  • 获取UA
var result = this.$refs.webview.getUserAgentString();
  • 夜间模式
var params = {};
params.enable = true; 
this.$refs.webview.setDayOrNight(params);
  • form保存及自动填充
var params = {};
params.enable = true; 
this.$refs.webview.setSaveFormData(params);
  • 在网页未设置背景色的情况下设置网页默认背景色
var params = {};
params.color = "#ff1100"; 
this.$refs.webview.setBackgroundColor(params);
  • 无痕模式
var params = {};
params.enable = true; 
this.$refs.webview.setShouldTrackVisitedLinks(params);
  • 刘海屏适配,对于刘海屏机器如果webview被遮挡会自动padding
var params = {};
params.enable = true; 
this.$refs.webview.setDisplayCutoutEnable(params);

支持定制,联系方式 QQ:252797991

如果觉得可以就点个👍吧,欢迎粉丝收藏,土豪打赏,您的关注就是我们创作的动力!

隐私、权限声明

1. 本插件需要申请的系统权限列表:

Android: <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> <uses-permission android:name="android.permission.INTERNET" /> <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" /> <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" /> <uses-permission android:name="android.permission.READ_PHONE_STATE" /> <uses-permission android:name="android.permission.READ_SETTINGS" /> <uses-permission android:name="android.permission.WRITE_SETTINGS" /> <!-- 硬件加速对X5视频播放非常重要,建议开启 --> <uses-permission android:name="android.permission.GET_TASKS" /> <uses-feature android:name="android.hardware.camera" /> <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" /> <uses-permission android:name="android.permission.MOUNT_UNMOUNT_FILESYSTEMS" /> <uses-permission android:name="android.permission.CAMERA" /> <uses-feature android:name="android.hardware.camera" /> <uses-feature android:name="android.hardware.camera.autofocus" />

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

插件使用的 腾讯X5 腾讯浏览服务 SDK会采集数据,详情可参考:https://x5.tencent.com

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

使用中有什么不明白的地方,就向插件作者提问吧~ 我要提问