开发
API

web-view

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

小程序的一个特点是无法外跳 H5 页面,目前针对这种情况,我们提供了<web-view /> 组件,该组件是一个用于承载网页的容器,将 H5 切入到小程序内部,铺满整个页面;该组件的使用组要进行业务域名配置,个人类型的小程序暂不支持使用。

属性说明

属性名类型默认值必填说明最低支持版本
srcstringN/A<web-view />组件指向网页的链接。网页链接需登录字节小程序开发者平台配置业务域名。只支持 httpswss 协议。1.0.0
bindmessageEventHandlerN/A当网页通过tt.miniProgram.postMessage向小程序 postMessage 时,bindmessage 绑定的方法会在小程序的特定时机(小程序后退、组件销毁、分享)触发并收到消息。1.17.0
bindloadEventHandlerN/A当网页加载完成时触发的消息1.28.0
binderrorEventHandlerN/A当网页加载失败时触发的消息1.0.0
progressbar-colorstring#51a0d8webview 的进度条颜色1.0.0

相关 API

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

接口类型接口名说明
导航栏tt.miniProgram.redirectTo参数与小程序接口tt.redirectTo一致
导航栏tt.miniProgram.navigateTo参数与小程序接口tt.navigateTo一致
导航栏tt.miniProgram.switchTab参数与小程序接口tt.switchTab一致
导航栏tt.miniProgram.reLaunch参数与小程序接口tt.reLaunch一致
导航栏tt.miniProgram.navigateBack参数与小程序接口tt.navigateBack一致
向小程序发送消息tt.miniProgram.postMessage此方法用于网页向小程序发送消息,会在特定时机(小程序后退、组件销毁、分享)触发组件的 bindmessage 上绑定的方法,方法的回调参数为网页postMessage的信息的数组队列,详细查看下面【代码示例 2】

redirectTonavigateTo 等页面跳转的 api 只支持 url 为 / 开始的绝对路径。

效果示例

扫码体验

请使用字节宿主APP扫码

代码示例

开发者工具中预览

【代码示例 1】:简单示例

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

【代码示例 2】:H5 和小程序的消息通信

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://s3.pstatp.com/toutiao/tmajssdk/jssdk-1.0.1.js"></script>
  </head>
  <body>
    <div>H5的内容</div>
  </body>
  <script type="text/javascript">
    (function () {
      // 发送postMessage1
      tt.miniProgram.postMessage({
        data: {
          mes: "postMessage1",
        },
        success(res) {
          console.log("网页消息");
        },
        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页传过来的参数
  onMessage(options) {
    /**
     * 网页的消息发出顺序为postMessage1、postMessage2、postMessage3
     * options.detail.data的详细内容为:
     * [{ mes: "postMessage1" }, { mes: "postMessage2" }, { mes: "postMessage3" }]
     * tt.miniProgram.postMessage中的方法会被过滤,此处的callback的方法被过滤无法接收
     */
    console.log("onmessage:", options.detail.data);
  },
  webviewOnLoad() {
    console.log("webview 加载成功");
  },
  webviewOnError(e) {
    console.log("webview 加载失败", e);
  },
});

【代码示例 3】:判断 H5 页面是否在小程序 web-view 打开

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

【代码示例 4】:用户分享时可获取当前 web-view 的 URL,即在 onShareAppMessage 回调中返回 webViewUrl 参数

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

【代码示例 5】:完整的 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://s3.pstatp.com/toutiao/tmajssdk/jssdk-1.0.1.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>

【代码示例 6】:web-view 组件中不支持调用 h5 中的支付,请跳转到小程序里支付,支付完成再返回 web-view 页面,逻辑如下:

  1. web-view 网页中调用 tt.miniProgram.navigateTott.miniProgram.redirectTo 跳转至小程序支付页面,小程序支付 API: tt.pay
  2. 完成支付后再跳转至 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
    });
  },
});

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

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

Bug & Tip

  • Tip:网页内 iframe 的域名也需要配置到域名白名单。
  • Tip:只能引入一次字节小程序 JSSDK,多次引入会导致小程序 API 无法调用。
  • Tip:一个页面只能有一个<web-view />,会自动铺满整个页面,并覆盖其他组件。
  • Tip:<web-view /> 网页与小程序之间不支持除 JSSDK 提供的接口之外的通信。
  • Tip:<web-view /> 组件的 userAgent 的特征值是 ToutiaoMicroApp,可以通过 navigator.userAgent.toLowerCase().includes('toutiaomicroapp') 来判断页面环境是否为字节小程序。
  • Tip:<web-view /> 组件的 bindmessage 绑定的方法的触发时机是特定的,仅为小程序后退、组件销毁、分享时,方法内的回调参数是数组,小程序运行时会把tt.miniProgram.postMessage中发送的数据过滤掉方法后,保存在一个队列里,一次性通过bindmessage上的方法通知到小程序中。
  • Tip:不支持调起 H5 的支付。
  • Tip:<web-view /> 网页内的跳转链接,是需要配置域名白名单的,以支持二跳的时候可以正常的跳转。
  • Tip:src 属性仅支持 httpswss 协议,不支持的协议会返回:页面打开失败。
点击纠错
评价此篇文档