web-view

展示全部

# web-view

组件类型：UniWebViewElement

承载网页的容器

# 兼容性

Web	微信小程序	Android	iOS
4.0	4.41	3.9	4.11

# 属性

名称类型默认值兼容性描述

src

string(string.HTMLURIString)

webview 指向网页的链接

allow

string

用于为 iframe 指定其特征策略

sandbox

string

该属性对呈现在 iframe 框架中的内容启用一些额外的限制条件。

fullscreen

boolean

是否铺满整个页面，默认值：true。

webview-styles

WebViewStyles

{"progress":{"color":"#00FF00"}}

webview 网络地址页面加载进度条样式

名称	类型	必备	默认值	兼容性	描述
progress	WebViewProgressStyles \| boolean	是	false	-	网络地址页面加载进度条样式，设置为 false 时表示不显示加载进度条。

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 }

@loading

(event: UniWebViewLoadingEvent) => void

网页加载中触发。e.detail = { url, src }

@download

(event: UniWebViewDownloadEvent) => void

点击网页中可下载链接时触发。e.detail = { url, userAgent, contentDisposition, mimetype, contentLength }

~~@loaded~~

(event: UniWebViewLoadEvent) => void

网页加载完成后触发。e.detail = { url, src }。已废弃，请改用load

# 事件

# UniWebViewMessageEvent

# UniWebViewMessageEvent 的属性值

名称	类型	必填	默认值	兼容性	描述
type	string	是	-	-	事件类型，固定值message

# UniWebViewMessageEventDetail

# UniWebViewMessageEventDetail 的属性值

名称	类型	必填	默认值	兼容性	描述
data	UTSJSONObject[]	是	-	-	消息包含的数据，4.13版本之前类型为Map<string, any \| null> \| null，4.13版本（含）之后类型为Array<UTSJSONObject>

# UniWebViewErrorEvent

# UniWebViewErrorEvent 的属性值

名称	类型	必填	默认值	兼容性	描述
type	string	是	-	-	事件类型，固定值error

# UniWebViewErrorEventDetail

# UniWebViewErrorEventDetail 的属性值

名称

类型

必填

默认值

兼容性

描述

errSubject

string

是

统一错误主题（模块）名称，固定值uni-web-view

errCode

number

是

统一错误码
100001 ssl error
100002 page error
100003 http error

合法值	兼容性	描述
100001	-	-
100002	-	-
100003	-	-

errMsg

string

是

统一错误描述信息

url

string

是

加载错误的网页链接，非完整链接，仅包含scheme://authority部分，4.13版本起支持

fullUrl

string

是

加载错误的网页链接，完整链接，4.13版本起支持

src

string

是

加载错误的网页链接，完整链接，4.13版本起支持

# UniWebViewLoadEvent

# UniWebViewLoadEvent 的属性值

名称	类型	必填	默认值	兼容性	描述
type	string	是	-	-	事件类型，固定值load

# UniWebViewLoadEventDetail

# UniWebViewLoadEventDetail 的属性值

名称	类型	必填	默认值	兼容性	描述
~~url~~	string	是	-	-	加载完成的网页链接
src	string	是	-	-	加载完成的网页链接，4.13版本起支持

# UniWebViewLoadingEvent

# UniWebViewLoadingEvent 的属性值

名称	类型	必填	默认值	兼容性	描述
type	string	是	-	-	事件类型，固定值loading

# UniWebViewLoadingEventDetail

# UniWebViewLoadingEventDetail 的属性值

名称	类型	必填	默认值	兼容性	描述
~~url~~	string	是	-	-	加载中的网页链接
src	string	是	-	-	加载中的网页链接，4.13版本起支持

# UniWebViewDownloadEvent

# UniWebViewDownloadEvent 的属性值

名称	类型	必填	默认值	兼容性	描述
type	string	是	-	-	事件类型，固定值download

# UniWebViewDownloadEventDetail

# UniWebViewDownloadEventDetail 的属性值

名称	类型	必填	默认值	兼容性	描述
url	string	是	-	-	下载链接
userAgent	string	是	-	-	用户代理
contentDisposition	string	是	-	-	指示回复的内容该以何种形式展示，是以内联的形式（即网页或者页面的一部分），还是以附件的形式下载并保存到本地
mimetype	string	是	-	-	媒体类型
contentLength	number	是	-	-	文件大小

# 获取原生WebView对象

为增强uni-app x组件的开放性，从 HBuilderX 4.25 起，UniElement对象提供了 getAndroidView 和 getIOSView 方法。

该方法可以获取到 web-view 组件对应的原生 WebView 对象，从而可以调用原生 API 以扩展当前 web-view 组件和上下文对象未提供的能力。

比如：Android 平台和 iOS 平台的原生 WebView 都提供了 canGoBack 和 canGoForward 两个 API，用来判断当前网页是否可以回退和前进。但 uni-app x 的 web-view 组件上下文对象没有封装上述 API。

下面则举例说明在 Android 平台如何通过获取原生 WebView 对象来实现上述能力（iOS 平台写法类似）。

import WebView from 'android.webkit.WebView';

function canGoBack() : boolean {
	// 第一步获取web-view组件的UniElement对象
	const element = uni.getElementById(elementId); //elementId为页面上web-view组件的id。不过一般建议从uvue页面给uts插件传入指定的UniElement对象，而不是在uts插件中直接获取页面组件的id。
	// 第二步通过UniElement的getAndroidView方法，通过泛型指定的方式，获取Android原生的WebView对象。泛型参数即为原生对象的类型名称
  const webview = element?.getAndroidView<WebView>();
	// 然后就可以调用原生WebView的各种方法，比如 canGoBack 方法
  return webview == null ? false : webview.canGoBack();
}

function canGoForward() : boolean {
  const element = uni.getElementById(elementId); //elementId为页面上web-view组件的id
  const webview = element?.getAndroidView<WebView>();
  return webview == null ? false : webview.canGoForward();
}

详细的示例源码，在 hello uni-app x 的组件 -> web-view 示例中，获取原生WebView对象，然后进一步使用了可否前进后退的方法，封装代码如下：

Android
iOS

# 组件宽高说明

web和小程序平台上，web-view是全屏的，即页面只能显示一个铺满的web-view。
app/web平台的web-view组件可以自由调整大小和位置。在uni-app x 4.0以前，默认宽、高为0px，页面中使用时需设置相应的 css 属性控制组件宽高才能正常显示。从4.0起改为默认宽高100%。

# src路径支持说明

本地路径/static方式
由于uni-app/uni-app x编译时，只把/static目录下的静态资源copy到app中，所以src均需指向/static目录下。
其他目录的html文件由于不会被打包进去，所以无法访问。
app平台文件路径会存在大小写敏感问题，为了有更好的兼容性，建议统一按大小写敏感原则处理详情
支持网络路径
支持http、https。
app平台使用系统Webview组件，由系统Webview管理缓存。

# 子组件

不可以嵌套组件

# 示例

hello uni-app x

Template

Script

<template>
  <scroll-view class="uni-flex-item">
    <web-view id="web-view" class="uni-flex-item" :style="{ 'pointer-events': pointerEvents }" :src="src"
      :webview-styles="webview_styles" :horizontalScrollBarAccess="horizontalScrollBarAccess"
      :verticalScrollBarAccess="verticalScrollBarAccess" @message="message" @error="error" @loading="loading"
      @load="load" @download="download" @touchstart="touchstart" @tap="tap">
    </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" :disabled="!canGoBack" @click="back">后退</button>
        <button class="margin-left-5 uni-flex-item" type="primary" :disabled="!canGoForward"
          @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 -->
      <!-- #ifdef APP-IOS -->
      <view class="uni-row uni-btn-v" v-if="isProd() === false">
        <view class="uni-row uni-flex-item align-items-center">
          <text>前进、后退功能在Windows端需要打自定义基座，MAC端需要配置Xcode环境后进行真机运行或者打自定义基座</text>
        </view>
      </view>
      <!-- #endif -->
    </view>
    <!-- #endif -->
  </scroll-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平台web-view组件底层使用iframe实现，会有浏览器安全策略限制。一般不推荐在web平台使用web-view组件，如确需使用，且需要通信，请自行根据iframe的浏览器规范进行通信。

# 注意

app平台web-view组件为系统Webview组件，内核版本号不由uni-app x框架控制。
app-android平台，web-view版本不一定是手机默认浏览器的版本。在部分手机上系统web-view的升级需要升级rom，部分手机则可以单独升级Android System Webview包。如需x5等三方webview，需使用uts插件，见插件市场。使用三方webview可减少系统webview的碎片化问题。
iOS上，web-view的版本与iOS的版本绑定，也即是手机Safari浏览器的版本。WKWebview的限制比Android要多一些，比如无法使用跨域cookie，具体见Apple开发者文档。
页面中的web-view组件数量不宜太多，每个web-view都会占用不少内存。