web-view 网页容器
收藏
我的收藏

基础库 1.0.0 开始支持本组件。

该组件是一个用于承载网页的容器，将 H5 切入到小程序内部，铺满整个页面。使用该组件要进行业务域名配置，仅支持添加开发者可控制(能放置校验文件到域名根目录)的域名。个人类型的小程序暂不支持使用。

属性说明

属性名	类型	默认值	必填	说明	最低支持版本
src	string		是	组件指向网页的链接。网页链接需登录字节小程序开发者平台配置业务域名。只支持 https 和 wss 协议。	1.0.0
progressbar-color	Color	#51a0d8	否	webview 的进度条颜色	1.0.0
type	string	default	否	若使用web-view组件引入第三方客服，必须填写type="im"。业务域名配置流程及注意事项与普通H5页面接入一致	2.72.0
bindmessage	EventHandle		否	当网页通过 `tt.miniProgram.postMessage` 向小程序 postMessage 时，bindmessage 绑定的方法会在小程序的特定时机（小程序后退、组件销毁、分享）触发并收到消息。	1.17.0
bindload	EventHandle		否	当网页加载完成时触发的消息	1.28.0
binderror	EventHandle		否	当网页加载失败时触发的消息	1.0.0

相关 API

<web-view /> 中如果需要使用字节小程序提供的接口能力，需要手动引入字节小程序 JSSDK 文件。提供了以下接口，为您使用：

接口类型	接口名	说明	JS SDK 支持版本
导航	tt.miniProgram.redirectTo	参数与小程序接口 tt.redirectTo 一致	1.0.1
导航	tt.miniProgram.navigateTo	参数与小程序接口 tt.navigateTo 一致	1.0.1
导航	tt.miniProgram.switchTab	参数与小程序接口 tt.switchTab 一致	1.0.1
导航	tt.miniProgram.reLaunch	参数与小程序接口 tt.reLaunch 一致	1.0.1
导航	tt.miniProgram.navigateBack	参数与小程序接口 tt.navigateBack 一致	1.0.1
侧滑	tt.miniProgram.setSwipeBackModeSync	参数与小程序接口 tt.setSwipeBackModeSync 一致	1.0.2
向小程序发送消息	tt.miniProgram.postMessage	此方法用于网页向小程序发送消息，会在特定时机（小程序后退、组件销毁、分享）触发组件的 bindmessage 上绑定的方法，方法的回调参数为网页`postMessage`的信息的数组队列，详细查看下面通信示例。	1.0.1
基础	tt.miniProgram.getEnv	用于获取当前是否是小程序环境。假如是小程序环境，会返回对应小程序 systemInfo （getSystemInfo complete返回值）。依赖基础库版本 2.74.0 及以上。 `tt.miniProgram.getEnv((res)=>{ if(res.miniprogram){ console.log(res.systemInfo); } })`	1.1.0
基础	tt.miniProgram.checkJsApi	用来判断传入当前宿主是否支持传入的Api。依赖基础库版本 2.74.0 及以上。详细查看下面checkJsApi示例	1.1.0
图片	tt.miniProgram.chooseImage	参数与小程序接口tt.chooseImage一致。依赖基础库版本 2.74.0 及以上。	1.1.0
图片	tt.miniProgram.compressImage	参数与小程序接口tt.compressImage一致。依赖基础库版本 2.74.0 及以上。	1.1.0
图片	tt.miniProgram.previewImage	参数与小程序接口tt.previewImage一致。依赖基础库版本 2.74.0 及以上。	1.1.0
文件	tt.miniProgram.uploadFile	参数与小程序接口tt.uploadFile一致。依赖基础库版本 2.74.0 及以上。	1.1.0
网络	tt.miniProgram.getNetworkType	参数与小程序接口tt.getNetworkType一致。依赖基础库版本 2.74.0 及以上。	1.1.0
定位	tt.miniProgram.openLocation	参数与小程序接口tt.openLocation一致。依赖基础库版本 2.74.0 及以上。	1.1.0
定位	tt.miniProgram.getLocation	参数与小程序接口tt.getLocation一致。依赖基础库版本 2.74.0 及以上。	1.1.0

redirectTo、navigateTo 等页面跳转的 api 只支持 url 为 / 开始的绝对路径。
setSwipeBackModeSync api 依赖基础库的能力，而基础库从 2.17.0 版本开始支持此能力，所以如果强依赖此能力，建议通过 getSystemInfoSync api 中的参数 SDKVersion 作为判断依据。注意：即使是在低于 2.17.0 的基础库上使用此能力也不会报错，但是预期的功能不会生效。
chooseImage、compressImage、previewImage、uploadFile、getNetwork、openLocation、getLocation 等在 JSSDK 1.1.0 新增的接口，依赖基础库版本 2.74.0。其次建议开发者在实际调用前通过 checkJsApi 进行 API 检测，确定支持后再进行实际调用。

效果示例

扫码体验

代码示例

开发者工具中预览

简单示例

<web-view src="https://some-domain/some/path"></web-view>

通信示例

H5 的网页内容，并且假设网页上线后的链接为https://some-domain/some/path/index.html:

<!-- https://some-domain/some/path/index.html -->
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>call phone</title>
    <!-- 需要主动引入JSSDK -->
    <script src="https://lf1-cdn-tos.bytegoofy.com/goofy/developer/jssdk/jssdk-1.1.0.js"></script>
  </head>
  <body>
    <div>H5的内容</div>
  </body>
  <script type="text/javascript">
    (function () {
      // 发送postMessage1
      tt.miniProgram.postMessage({
        data: {
          mes: "postMessage1",
        },
        // success 回调表示把 data 数据存储成功。
        // 存储成功的数据会在小程序后退、组件销毁、页面分享时，通过 bindmessage 发送给用户
        success(res) {
          console.log("网页消息");
        },
        // fail 回调表示没有把 data 数据存储成功
        fail(err) {
          console.log(err);
        },
      });
      // 发送postMessage2
      tt.miniProgram.postMessage({
        data: {
          mes: "postMessage2",
        },
      });
      // 发送postMessage3
      tt.miniProgram.postMessage({
        data: {
          mes: "postMessage3",
        },
      });
    })();
  </script>
</html>

<!-- https://some-domain/some/path/index.html为上面H5的线上地址 -->
<web-view
  src="https://some-domain/some/path/index.html"
  bindload="webviewOnLoad"
  binderror="webviewOnError"
  bindmessage="onMessage"
></web-view>

Page({
  /**
   * 小程序后退、组件销毁、页面分享时且当前 H5 页面调用过 tt.miniProgram.postMessage，则触发此函数
   * 其中 options.detail.data 就是 H5 页面通过 tt.miniProgram.postMessage 传入的 data 信息；
   */
  onMessage(options) {
    /**
     * 网页的消息发出顺序为 postMessage1、postMessage2、postMessage3
     * options.detail.data 的详细内容分别为:
     * [{ mes: "postMessage1" }, { mes: "postMessage2" }, { mes: "postMessage3" }]
     */
    console.log("onmessage：", options.detail.data);
  },
  webviewOnLoad() {
    console.log("webview 加载成功");
  },
  webviewOnError(e) {
    console.log("webview 加载失败", e);
  },
});

环境判断示例

判断 H5 页面是否在小程序 web-view 打开

// isTTWebView 若为 true，则是在头条小程序的 web-view 中打开
const isTTWebView = navigator.userAgent
  .toLowerCase()
  .includes("toutiaomicroapp");

分享示例

用户分享时可获取当前 web-view 的 URL，即在 onShareAppMessage 回调中返回 webViewUrl 参数

Page({
  onShareAppMessage(options) {
    console.log(options.webViewUrl); // 当前 web-view 的URL
  },
});

完整的 h5 示例

<!-- https://some-domain/some/path/index.html -->
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>call phone</title>
    <script src="https://lf1-cdn-tos.bytegoofy.com/goofy/developer/jssdk/jssdk-1.1.0.js"></script>
  </head>
  <body>
    <button onclick="navigateBack()">navigateBack</button>
  </body>
  <script type="text/javascript">
    function navigateBack() {
      tt.miniProgram.navigateBack({
        delta: 1,
      });
    }
  </script>
</html>

<!-- 将生成的 h5 站点地址放入小程序 web-view 的 src 即可 -->
<web-view src="https://some-domain/some/path/index.html"></web-view>

web-view 组件支付示例

web-view 组件中不支持调用 h5 中的支付，请跳转到小程序里支付，支付完成再返回 web-view 页面，逻辑如下：

web-view 网页中调用 tt.miniProgram.navigateTo 或 tt.miniProgram.redirectTo 跳转至小程序支付页面，小程序支付 API: tt.pay。

完成支付后再跳转至 web-view 页面。

// webview.html(web-view 组件承载的网页地址) 中的跳转逻辑
tt.miniProgram.navigateTo({
  url: "/pages/pay/index",
  success(res) {
    console.log("跳转成功", res);
  },
  fail(err) {
    console.log("navigateTo调用失败", err);
  },
});

// pages/pay/index
Page({
  pay() {
    // 支付逻辑
    ...
    // 支付完成
    tt.navigateTo({
      url: '/pages/webview/index', // 指定页面的 url
    });
  },
});

二级页面侧滑返回示例

期望在 h5 的二级页面侧滑返回上级 h5 页面，而不是返回到小程序页面。

// 比如 A 是 webview 组件的首页，跳转到二级页面 B，期望在 B 中侧滑能够返回到 A 页面，而不是退出到小程序页面。可以使用如下方式
// B.html
tt.miniProgram.setSwipeBackModeSync(0);

checkJsApi 使用示例

使用 checkJsApi 判断当前宿主是否支持某些 api。

function checkJsApi(cb) {
  tt.miniProgram.checkJsApi({
    jsApiList: ["chooseImage", "previewImage", "compressImage", "uploadFile"],
    success(res) {
      console.log("checkJsApi success:", res);
      cb(res);
    },
    fail(res) {
      console.log("checkJsApi fail:", res);
    },
  });
}

图片相关示例

在 H5 中进行图片选取及上传。

tt.miniProgram.chooseImage({
     count:1,
     sourceType:'album',
     success(res){
        console.log('chooseImage success:', res);
        tt.miniProgram.uploadFile({
          url: 'https://some-domain/upload',
          filePath: res.tempFilePaths[0]
          name: 'data',
          success(res){
            console.log('uploadFile success:', res);
          },
          fail(res){
            console.log('uploadFile fail:', res);
          }
        })
     },
     fail(res){
        console.log('chooseImage fail:', res);
     }
})

使用 web-view 打开限定域名内的网页

访问小程序开发者平台，进入对应的小程序管理后台，点击 开发设置 -> webview 域名，即可下载、配置校验文件并配置 webview 域名。

Bug & Tip

•

Tip：jssdk 从 1.0.3 开始在非字节小程序环境下被引用，不会覆盖其他 jssdk 的 webkit 对象。

•

Tip：网页内 iframe 的域名也需要配置到域名白名单。

•

Tip：只能引入一次字节小程序 JSSDK，多次引入会导致小程序 API 无法调用。注意本次 jssdk 从 1.0.1 升级到 1.0.2，主要考虑到 1.0.1 对应的域名会逐步废弃掉，其次从 1.0.2 版本开始支持 setSwipeBackModeSync 能力。

•

Tip：一个页面只能有一个，会自动铺满整个页面，并覆盖其他组件。

•

Tip：网页与小程序之间不支持除 JSSDK 提供的接口之外的通信。

•

Tip：组件的 userAgent 的特征值是 ToutiaoMicroApp，可以通过 navigator.userAgent.toLowerCase().includes('toutiaomicroapp') 来判断页面环境是否为字节小程序。

•

Tip：组件的 bindmessage 绑定的方法的触发时机是特定的，仅为小程序后退、组件销毁、分享时，方法内的回调参数是数组，小程序运行时会把tt.miniProgram.postMessage中发送的数据过滤掉方法后，保存在一个队列里，一次性通过bindmessage上的方法通知到小程序中。

•

Tip：不支持调起 H5 的支付。

•

Tip：网页内的跳转链接，是需要配置域名白名单的，以支持二跳的时候可以正常的跳转。

•

Tip：src 属性仅支持 https 和 wss 协议，不支持的协议会返回：页面打开失败。

•

Tip：可以配置端口，如 https://server.com:8080，但是配置后只能向 https://server.com:8080 发起请求。如果向 https://server.com、https://server.com:9091等 URL 请求则会失败。

•

TIp：如果不配置端口。如 https://server.com，那么请求的 URL 中也不能包含端口，甚至是默认的 443 端口也不可以。如果向 https://server.com:443 请求则会失败。

web-view 网页容器收藏我的收藏

​属性说明​

​相关 API​

​效果示例​

​扫码体验​

​代码示例​

​简单示例​

​通信示例​

​环境判断示例​

​分享示例​

​完整的 h5 示例​

​web-view 组件支付示例​

​二级页面侧滑返回示例​

​checkJsApi 使用示例​

​图片相关示例​

​使用 web-view 打开限定域名内的网页​

​Bug & Tip​