开发
API

web-view

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

该组件是一个用于承载网页的容器,将 H5 切入到小程序内部,铺满整个页面。使用该组件要进行业务域名配置个人类型的小程序暂不支持使用。

属性说明

属性名类型默认值必填说明最低支持版本
srcstring组件指向网页的链接。网页链接需登录字节小程序开发者平台配置业务域名。只支持 httpswss 协议。1.0.0
progressbar-colorColor#51a0d8webview 的进度条颜色1.0.0
bindmessageEventHandle当网页通过 tt.miniProgram.postMessage 向小程序 postMessage 时,bindmessage 绑定的方法会在小程序的特定时机(小程序后退、组件销毁、分享)触发并收到消息。1.17.0
bindloadEventHandle当网页加载完成时触发的消息1.28.0
binderrorEventHandle当网页加载失败时触发的消息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.setSwipeBackModeSync参数与小程序接口tt.setSwipeBackModeSync一致
向小程序发送消息tt.miniProgram.postMessage此方法用于网页向小程序发送消息,会在特定时机(小程序后退、组件销毁、分享)触发组件的 bindmessage 上绑定的方法,方法的回调参数为网页postMessage的信息的数组队列,详细查看下面【代码示例 2】

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

setSwipeBackModeSync api 依赖基础库的能力,而基础库从 2.17.0 版本开始支持此能力,所以如果强依赖此能力,建议通过 getSystemInfoSync api 中的参数 SDKVersion 作为判断依据。注意:即使是在低于 2.17.0 的基础库上使用此能力也不会报错,但是预期的功能不会生效。

效果示例

扫码体验

请使用字节宿主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://lf1-cdn-tos.bytegoofy.com/goofy/developer/jssdk/jssdk-1.0.3.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://lf1-cdn-tos.bytegoofy.com/goofy/developer/jssdk/jssdk-1.0.3.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
    });
  },
});

【代码示例 7】:期望在 h5 的二级页面侧滑返回上级 h5 页面,而不是返回到小程序页面。

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

使用 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:一个页面只能有一个<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 协议,不支持的协议会返回:页面打开失败。
点击纠错
评价此篇文档