uni-app
uni-app x
uniCloud
HBuilder
uni 小程序 sdk
uni-app x
uni-app
uni-app x
uniCloud
HBuilder
uni 小程序 sdk
简体中文
组件
web-view
web-view 兼容性
属性
事件
UniWebViewMessageEvent
UniWebViewErrorEvent
UniWebViewLoadEvent
UniWebViewLoadingEvent
UniWebViewDownloadEvent
UniWebViewElement
展示全部

# web-view

组件类型：UniWebViewElement

承载网页的容器

# web-view 兼容性

Android iOS web
3.9 4.11 4.0

# 属性

名称 类型 默认值 描述
src string(string.URIString) - webview 指向网页的链接
webview-styles WebViewStyles {"progress":{"color":"#00FF00"}} webview 网络地址页面加载进度条样式
名称 类型 必备 默认值 描述
progress WebViewProgressStyles | boolean 是 false 网络地址页面加载进度条样式，设置为 false 时表示不显示加载进度条。
名称 类型 必备 默认值 描述
color string.ColorString 是 - 网页加载进度条颜色，默认值为 #00FF00 。
horizontalScrollBarAccess boolean true 设置是否显示横向滚动条
verticalScrollBarAccess boolean true 设置是否显示纵向滚动条
@message (event: UniWebViewMessageEvent) => void - 网页向应用 postMessage 时触发。e.detail = { data }
@error (event: UniWebViewErrorEvent) => void - 网页加载错误时触发。e.detail = { errSubject, errCode, errMsg, url, fullUrl, src }
@load (event: UniWebViewLoadEvent) => void - 网页加载完成后触发。e.detail = { url, src }
@loaded (event: UniWebViewLoadEvent) => void - 网页加载完成后触发。e.detail = { url, src }。已废弃，请改用load
@loading (event: UniWebViewLoadingEvent) => void - 网页加载中触发。e.detail = { url, src }
@download (event: UniWebViewDownloadEvent) => void - 点击网页中可下载链接时触发。e.detail = { url, userAgent, contentDisposition, mimetype, contentLength }

# 事件

# UniWebViewMessageEvent

# UniWebViewMessageEvent 的属性值
名称 类型 必填 默认值 描述
type string 是 - 事件类型，固定值message
detail UniWebViewMessageEventDetail 是 - -
名称 类型 必备 默认值 描述
data Array<UTSJSONObject> 是 - 消息包含的数据，4.13版本之前类型为Map<string, any | null> | null，4.13版本（含）之后类型为Array<UTSJSONObject>
bubbles boolean 是 - 是否冒泡
cancelable boolean 是 - 是否可以取消
target UniElement | null 否 - UVUE DOM 元素对象，描述了 UVUE DOM 元素所普通具有的属性和方法。
currentTarget UniElement | null 否 - UVUE DOM 元素对象，描述了 UVUE DOM 元素所普通具有的属性和方法。
timeStamp number 是 - 事件发生时的时间戳
# UniWebViewMessageEvent 的方法
名称 类型 必填 默认值 描述
stopPropagation () => void 是 - 阻止当前事件的进一步传播
preventDefault () => void 是 - 阻止当前事件的默认行为

# UniWebViewErrorEvent

# UniWebViewErrorEvent 的属性值
名称 类型 必填 默认值 描述
type string 是 - 事件类型，固定值error
detail UniWebViewErrorEventDetail 是 - -
名称 类型 必备 默认值 描述
errSubject string 是 - 统一错误主题（模块）名称，固定值uni-web-view
errCode 100001 | 100002 | 100003 是 - 统一错误码
100001 ssl error
100002 page error
100003 http error
errMsg string 是 - 统一错误描述信息
url string 是 - 加载错误的网页链接，非完整链接，仅包含scheme://authority部分，4.13版本起支持
fullUrl string 是 - 加载错误的网页链接，完整链接，4.13版本起支持
src string 是 - 加载错误的网页链接，完整链接，4.13版本起支持
bubbles boolean 是 - 是否冒泡
cancelable boolean 是 - 是否可以取消
target UniElement | null 否 - UVUE DOM 元素对象，描述了 UVUE DOM 元素所普通具有的属性和方法。
currentTarget UniElement | null 否 - UVUE DOM 元素对象，描述了 UVUE DOM 元素所普通具有的属性和方法。
timeStamp number 是 - 事件发生时的时间戳
# UniWebViewErrorEvent 的方法
名称 类型 必填 默认值 描述
stopPropagation () => void 是 - 阻止当前事件的进一步传播
preventDefault () => void 是 - 阻止当前事件的默认行为

# UniWebViewLoadEvent

# UniWebViewLoadEvent 的属性值
名称 类型 必填 默认值 描述
type string 是 - 事件类型，固定值load
detail UniWebViewLoadEventDetail 是 - -
名称 类型 必备 默认值 描述
url string 是 - 加载完成的网页链接 4.13版本起废弃，请改用src
src string 是 - 加载完成的网页链接，4.13版本起支持
bubbles boolean 是 - 是否冒泡
cancelable boolean 是 - 是否可以取消
target UniElement | null 否 - UVUE DOM 元素对象，描述了 UVUE DOM 元素所普通具有的属性和方法。
currentTarget UniElement | null 否 - UVUE DOM 元素对象，描述了 UVUE DOM 元素所普通具有的属性和方法。
timeStamp number 是 - 事件发生时的时间戳
# UniWebViewLoadEvent 的方法
名称 类型 必填 默认值 描述
stopPropagation () => void 是 - 阻止当前事件的进一步传播
preventDefault () => void 是 - 阻止当前事件的默认行为

# UniWebViewLoadingEvent

# UniWebViewLoadingEvent 的属性值
名称 类型 必填 默认值 描述
type string 是 - 事件类型，固定值loading
detail UniWebViewLoadingEventDetail 是 - -
名称 类型 必备 默认值 描述
url string 是 - 加载中的网页链接 4.13版本起废弃，请改用src
src string 是 - 加载中的网页链接，4.13版本起支持
bubbles boolean 是 - 是否冒泡
cancelable boolean 是 - 是否可以取消
target UniElement | null 否 - UVUE DOM 元素对象，描述了 UVUE DOM 元素所普通具有的属性和方法。
currentTarget UniElement | null 否 - UVUE DOM 元素对象，描述了 UVUE DOM 元素所普通具有的属性和方法。
timeStamp number 是 - 事件发生时的时间戳
# UniWebViewLoadingEvent 的方法
名称 类型 必填 默认值 描述
stopPropagation () => void 是 - 阻止当前事件的进一步传播
preventDefault () => void 是 - 阻止当前事件的默认行为

# UniWebViewDownloadEvent

# UniWebViewDownloadEvent 的属性值
名称 类型 必填 默认值 描述
type string 是 - 事件类型，固定值download
detail UniWebViewDownloadEventDetail 是 - -
名称 类型 必备 默认值 描述
url string 是 - 下载链接
userAgent string 是 - 用户代理
contentDisposition string 是 - 指示回复的内容该以何种形式展示，是以内联的形式（即网页或者页面的一部分），还是以附件的形式下载并保存到本地
mimetype string 是 - 媒体类型
contentLength number 是 - 文件大小
bubbles boolean 是 - 是否冒泡
cancelable boolean 是 - 是否可以取消
target UniElement | null 否 - UVUE DOM 元素对象，描述了 UVUE DOM 元素所普通具有的属性和方法。
currentTarget UniElement | null 否 - UVUE DOM 元素对象，描述了 UVUE DOM 元素所普通具有的属性和方法。
timeStamp number 是 - 事件发生时的时间戳
# UniWebViewDownloadEvent 的方法
名称 类型 必填 默认值 描述
stopPropagation () => void 是 - 阻止当前事件的进一步传播
preventDefault () => void 是 - 阻止当前事件的默认行为

# UniWebViewElement

web-view元素对象

# UniWebViewElement 的方法

# back()

后退

# forward()

前进

# reload()

重新加载

# stop()

停止加载

# evalJS(js)

原生和WebView通信（执行JS脚本）

# 参数
名称 类型 必填 默认值 描述
js string 是 - -

# web-view 属性兼容性

Android iOS web
src 3.9 4.11 4.0
webview-styles 3.9 4.11 x
horizontalScrollBarAccess 4.11 4.13 x
verticalScrollBarAccess 4.11 4.13 x
@message 3.9 4.11 x
@error 3.9 4.11 x
@load 4.0 4.11 x
@loading 3.9 4.11 x
@download 3.9 4.11 x
  • web平台web-view组件底层使用iframe实现，会有浏览器安全策略限制。一般不推荐在web平台使用web-view组件，如确需使用，且需要通信，请自行根据iframe的浏览器规范进行通信。
  • web和小程序平台上，web-view是全屏的，即页面只能显示一个铺满的web-view。
  • app/web平台的web-view组件可以自由调整大小和位置。在uni-app x 4.0以前，默认宽、高为0px，页面中使用时需设置相应的 css 属性控制组件宽高才能正常显示。从4.0起改为默认宽高100%。

# 子组件

不可以嵌套组件

# 示例

hello uni-app x

Template

Script

<template>
  <view class="uni-flex-item">
    <web-view id="web-view" class="uni-flex-item" :src="src" :webview-styles="webview_styles"
      :horizontalScrollBarAccess="horizontalScrollBarAccess" :verticalScrollBarAccess="verticalScrollBarAccess"
      @message="message" @error="error" @loading="loading" @load="load" @download="download">
    </web-view>
    <!-- #ifdef APP -->
    <view class="uni-padding-wrap uni-common-mt">
      <view class="uni-btn-v">
        <input class="uni-input" confirmType="go" placeholder="输入网址跳转" @confirm="confirm" maxlength="-1"/>
      </view>
      <view class="uni-row uni-btn-v">
        <button class="uni-flex-item" type="primary" @click="back">后退</button>
        <button class="margin-left-5 uni-flex-item" type="primary" @click="forward">前进</button>
      </view>
      <view class="uni-row uni-btn-v">
        <button class="uni-flex-item" type="primary" @click="reload">重新加载</button>
        <button class="margin-left-5 uni-flex-item" type="primary" @click="stop">停止加载</button>
      </view>
      <view class="uni-btn-v">
        <button type="primary" @click="nativeToWeb">原生和Web通信</button>
      </view>
      <!-- #ifdef APP-ANDROID -->
      <view class="uni-row uni-btn-v">
        <view class="uni-row uni-flex-item align-items-center">
          <text>显示横向滚动条</text>
          <switch :checked="true" @change="changeHorizontalScrollBarAccess"></switch>
        </view>
        <view class="uni-row uni-flex-item align-items-center">
          <text>显示竖向滚动条</text>
          <switch :checked="true" @change="changeVerticalScrollBarAccess"></switch>
        </view>
      </view>
      <!-- #endif -->
    </view>
    <!-- #endif -->
  </view>
</template>



<style>
  .margin-left-5 {
    margin-left: 5px;
  }

  .align-items-center {
    align-items: center;
  }
</style>

# 参见

# 上下文对象API

web-view的操作api为uni.createWebviewContext()。

给web-view组件设一个id属性，将id的值传入uni.createWebviewContext()，即可得到web-view组件的上下文对象，进一步可使用.evalJS()、.reload()等方法。

# web-view组件的内外通信

  • uts向web-view的网页发消息

    使用evalJS()方法，详见上方示例代码

  • web-view里的网页向uts发消息

    在网页中引入uni.webview.1.5.5.js。即可在网页中调用一批uni的api，包括：

方法名 说明 平台差异说明
uni.webView.navigateTo navigateTo Web平台暂不支持
uni.webView.redirectTo redirectTo Web平台暂不支持
uni.webView.reLaunch reLaunch Web平台暂不支持
uni.webView.switchTab switchTab Web平台暂不支持
uni.webView.navigateBack navigateBack Web平台暂不支持
uni.webView.postMessage 向应用发送消息 Web平台暂不支持

在网页中使用uni.postMessage()即可向uts发送消息。

uts端在 <web-view> 组件的 message 事件回调 event.detail.data 中接收消息。

示例代码详见hello-uni-app-x/hybrid/html/local.html

Tips

  • 传递的消息信息，必须写在 data 对象中。
  • event.detail.data 中的数据，以数组的形式接收每次 post 的消息。（注：支付宝小程序除外，支付宝小程序中以对象形式接受）

# 注意

  • web-view组件为系统web-view，内核版本号不由uni-app x框架控制。
  • Android上，web-view版本不是手机默认浏览器的版本。在部分手机上系统web-view的升级需要升级rom，部分手机则可以单独升级Android System Webview包。如需x5等三方webview，需使用uts插件，见插件市场。使用三方webview可减少系统webview的碎片化问题。
  • iOS上，web-view的版本与iOS的版本绑定，也即是手机Safari浏览器的版本。
  • 一个页面的web-view组件数量不宜太多，每个web-view都会占用不少内存
本页导读
web-view
web-view 兼容性
属性
事件
UniWebViewMessageEvent
UniWebViewErrorEvent
UniWebViewLoadEvent
UniWebViewLoadingEvent
UniWebViewDownloadEvent
UniWebViewElement
UniWebViewElement 的方法
web-view 属性兼容性
子组件
示例
参见
上下文对象API
web-view组件的内外通信
注意