HarmonyOS API：基础组件

joytrian

发布于 2023-3-24 14:51

浏览

0收藏

版本：v3.1 Beta

Web

更新时间: 2023-02-17 09:19

提供具有网页显示能力的Web组件。

说明

该组件从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
示例效果请以真机运行为准，当前IDE预览器不支持。

需要权限

访问在线网页时需添加网络权限：ohos.permission.INTERNET，具体申请方式请参考权限申请声明。

子组件

无

接口

Web(options: { src: ResourceStr, controller: WebController | WebviewController})

说明

不支持转场动画。

参数：

参数名	参数类型	必填	参数描述
src	ResourceStr	是	网页资源地址。
controller	WebController \| WebviewController⁹⁺	是	控制器。

示例：

加载在线网页

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
    }
  }
}

// xxx.ets
import web_webview from '@ohos.web.webview'

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
    }
  }
}

加载本地网页

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()
  build() {
    Column() {
      Web({ src: $rawfile("index.html"), controller: this.controller })
    }
  }
}

<!-- index.html -->
<!DOCTYPE html>
<html>
    <body>
        <p>Hello World</p>
    </body>
</html><!-- index.html -->
<!DOCTYPE html>
<html>
    <body>
        <p>Hello World</p>
    </body>
</html>

属性

通用属性仅支持width、height、padding、margin、border。

domStorageAccess

domStorageAccess(domStorageAccess: boolean)

设置是否开启文档对象模型存储接口（DOM Storage API）权限，默认未开启。

参数：

参数名	参数类型	必填	默认值	参数描述
domStorageAccess	boolean	是	false	设置是否开启文档对象模型存储接口（DOM Storage API）权限。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .domStorageAccess(true)
    }
  }
}

fileAccess

fileAccess(fileAccess: boolean)

设置是否开启应用中文件系统的访问，默认启用。$rawfile(filepath/filename)中rawfile路径的文件不受该属性影响而限制访问。

参数：

参数名	参数类型	必填	默认值	参数描述
fileAccess	boolean	是	true	设置是否开启应用中文件系统的访问，默认启用。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .fileAccess(true)
    }
  }
}

imageAccess

imageAccess(imageAccess: boolean)

设置是否允许自动加载图片资源，默认允许。

参数：

参数名	参数类型	必填	默认值	参数描述
imageAccess	boolean	是	true	设置是否允许自动加载图片资源。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .imageAccess(true)
    }
  }
}

javaScriptProxy

javaScriptProxy(javaScriptProxy: { object: object, name: string, methodList: Array<string>,

controller: WebController | WebviewController})

注入JavaScript对象到window对象中，并在window对象中调用该对象的方法。所有参数不支持更新。

参数：

参数名	参数类型	必填	默认值	参数描述
object	object	是	-	参与注册的对象。只能声明方法，不能声明属性。
name	string	是	-	注册对象的名称，与window中调用的对象名一致。
methodList	Array<string>	是	-	参与注册的应用侧JavaScript对象的方法。
controller	WebController 或 WebviewController	是	-	控制器。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()
  testObj = {
    test: (data1, data2, data3) => {
      console.log("data1:" + data1)
      console.log("data2:" + data2)
      console.log("data3:" + data3)
      return "AceString"
    },
    toString: () => {
      console.log('toString' + "interface instead.")
    }
  }
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .javaScriptAccess(true)
        .javaScriptProxy({
          object: this.testObj,
          name: "objName",
          methodList: ["test", "toString"],
          controller: this.controller,
      })
    }
  }
}

// xxx.ets
import web_webview from '@ohos.web.webview'

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  testObj = {
    test: (data1, data2, data3) => {
      console.log("data1:" + data1)
      console.log("data2:" + data2)
      console.log("data3:" + data3)
      return "AceString"
    },
    toString: () => {
      console.log('toString' + "interface instead.")
    }
  }
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .javaScriptAccess(true)
        .javaScriptProxy({
          object: this.testObj,
          name: "objName",
          methodList: ["test", "toString"],
          controller: this.controller,
      })
    }
  }
}

javaScriptAccess

javaScriptAccess(javaScriptAccess: boolean)

设置是否允许执行JavaScript脚本，默认允许执行。

参数：

参数名	参数类型	必填	默认值	参数描述
javaScriptAccess	boolean	是	true	是否允许执行JavaScript脚本。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .javaScriptAccess(true)
    }
  }
}

mixedMode

mixedMode(mixedMode: MixedMode)

设置是否允许加载超文本传输协议（HTTP）和超文本传输安全协议（HTTPS）混合内容，默认不允许加载HTTP和HTTPS混合内容。

参数：

参数名	参数类型	必填	默认值	参数描述
mixedMode	MixedMode	是	MixedMode.None	要设置的混合内容。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()
  @State mode: MixedMode = MixedMode.All
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .mixedMode(this.mode)
    }
  }
}

onlineImageAccess

onlineImageAccess(onlineImageAccess: boolean)

设置是否允许从网络加载图片资源（通过HTTP和HTTPS访问的资源），默认允许访问。

参数：

参数名	参数类型	必填	默认值	参数描述
onlineImageAccess	boolean	是	true	设置是否允许从网络加载图片资源。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .onlineImageAccess(true)
    }
  }
}

zoomAccess

zoomAccess(zoomAccess: boolean)

设置是否支持手势进行缩放，默认允许执行缩放。

参数：

参数名	参数类型	必填	默认值	参数描述
zoomAccess	boolean	是	true	设置是否支持手势进行缩放。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .zoomAccess(true)
    }
  }
}

overviewModeAccess

overviewModeAccess(overviewModeAccess: boolean)

设置是否使用概览模式加载网页，默认使用该方式。

参数：

参数名	参数类型	必填	默认值	参数描述
overviewModeAccess	boolean	是	true	设置是否使用概览模式加载网页。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .overviewModeAccess(true)
    }
  }
}

databaseAccess

databaseAccess(databaseAccess: boolean)

设置是否开启数据库存储API权限，默认不开启。

参数：

参数名	参数类型	必填	默认值	参数描述
databaseAccess	boolean	是	false	设置是否开启数据库存储API权限。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .databaseAccess(true)
    }
  }
}

geolocationAccess

geolocationAccess(geolocationAccess: boolean)

设置是否开启获取地理位置权限，默认开启。

参数：

参数名	参数类型	必填	默认值	参数描述
geolocationAccess	boolean	是	true	设置是否开启获取地理位置权限。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .geolocationAccess(true)
    }
  }
}

mediaPlayGestureAccess

mediaPlayGestureAccess(access: boolean)

设置视频播放是否需要用户手动点击。

参数：

参数名	参数类型	必填	默认值	参数描述
access	boolean	是	true	设置视频播放是否需要用户手动点击。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()
  @State access: boolean = true
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .mediaPlayGestureAccess(this.access)
    }
  }
}

multiWindowAccess⁹⁺

multiWindowAccess(multiWindow: boolean)

设置是否开启多窗口权限，默认不开启。

参数：

参数名	参数类型	必填	默认值	参数描述
multiWindow	boolean	是	false	设置是否开启多窗口权限。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
      .multiWindowAccess(true)
    }
  }
}

cacheMode

cacheMode(cacheMode: CacheMode)

设置缓存模式。

参数：

参数名	参数类型	必填	默认值	参数描述
cacheMode	CacheMode	是	CacheMode.Default	要设置的缓存模式。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()
  @State mode: CacheMode = CacheMode.None
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .cacheMode(this.mode)
    }
  }
}

textZoomRatio⁹⁺

textZoomRatio(textZoomRatio: number)

设置页面的文本缩放百分比，默认为100%。

参数：

参数名	参数类型	必填	默认值	参数描述
textZoomRatio	number	是	100	要设置的页面的文本缩放百分比。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()
  @State atio: number = 150
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .textZoomRatio(this.atio)
    }
  }
}

initialScale⁹⁺

initialScale(percent: number)

设置整体页面的缩放百分比，默认为100%。

参数：

参数名	参数类型	必填	默认值	参数描述
percent	number	是	100	要设置的整体页面的缩放百分比。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()
  @State percent: number = 100
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .initialScale(this.percent)
    }
  }
}

userAgent

userAgent(userAgent: string)

设置用户代理。

参数：

参数名	参数类型	必填	默认值	参数描述
userAgent	string	是	-	要设置的用户代理。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()
  @State userAgent:string = 'Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/39.0.2171.71 Safari/537.36'
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .userAgent(this.userAgent)
    }
  }
}

webDebuggingAccess⁹⁺

webDebuggingAccess(webDebuggingAccess: boolean)

设置是否启用网页调试功能。

参数：

参数名	参数类型	必填	默认值	参数描述
webDebuggingAccess	boolean	是	false	设置是否启用网页调试功能。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()
  @State webDebuggingAccess: boolean = true
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .webDebuggingAccess(this.webDebuggingAccess)
    }
  }
}

事件

不支持通用事件。

onAlert

onAlert(callback: (event?: { url: string; message: string; result: JsResult }) => boolean)

网页触发alert()告警弹窗时触发回调。

参数：

参数名	参数类型	参数描述
url	string	当前显示弹窗所在网页的URL。
message	string	弹窗中显示的信息。
result	JsResult	通知Web组件用户操作行为。

返回值：

类型	说明
boolean	当回调返回false时，触发默认弹窗。当回调返回true时，系统应用可以调用系统弹窗能力（包括确认和取消），并且需要根据用户的确认或取消操作调用JsResult通知Web组件最终是否离开当前页面。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .onAlert((event) => {
          AlertDialog.show({
            title: 'onAlert',
            message: 'text',
            primaryButton: {
              value: 'cancel',
              action: () => {
                event.result.handleCancel()
              }
            },
            secondaryButton: {
              value: 'ok',
              action: () => {
                event.result.handleConfirm()
              }
            },
            cancel: () => {
              event.result.handleCancel()
            }
          })
          return true
        })
    }
  }
}

onBeforeUnload

onBeforeUnload(callback: (event?: { url: string; message: string; result: JsResult }) => boolean)

刷新或关闭场景下，在即将离开当前页面时触发此回调。刷新或关闭当前页面应先通过点击等方式获取焦点，才会触发此回调。

参数：

参数名	参数类型	参数描述
url	string	当前显示弹窗所在网页的URL。
message	string	弹窗中显示的信息。
result	JsResult	通知Web组件用户操作行为。

返回值：

类型	说明
boolean	当回调返回false时，触发默认弹窗。当回调返回true时，系统应用可以调用系统弹窗能力（包括确认和取消），并且需要根据用户的确认或取消操作调用JsResult通知Web组件最终是否离开当前页面。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()

  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .onBeforeUnload((event) => {
          console.log("event.url:" + event.url)
          console.log("event.message:" + event.message)
          AlertDialog.show({
            title: 'onBeforeUnload',
            message: 'text',
            primaryButton: {
              value: 'cancel',
              action: () => {
                event.result.handleCancel()
              }
            },
            secondaryButton: {
              value: 'ok',
              action: () => {
                event.result.handleConfirm()
              }
            },
            cancel: () => {
              event.result.handleCancel()
            }
          })
          return true
        })
    }
  }
}

onConfirm

onConfirm(callback: (event?: { url: string; message: string; result: JsResult }) => boolean)

网页调用confirm()告警时触发此回调。

参数：

参数名	参数类型	参数描述
url	string	当前显示弹窗所在网页的URL。
message	string	弹窗中显示的信息。
result	JsResult	通知Web组件用户操作行为。

返回值：

类型	说明
boolean	当回调返回false时，触发默认弹窗。当回调返回true时，系统应用可以调用系统弹窗能力（包括确认和取消），并且需要根据用户的确认或取消操作调用JsResult通知Web组件。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()

  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .onConfirm((event) => {
          console.log("event.url:" + event.url)
          console.log("event.message:" + event.message)
          console.log("event.result:" + event.result)
          AlertDialog.show({
            title: 'onConfirm',
            message: 'text',
            primaryButton: {
              value: 'cancel',
              action: () => {
                event.result.handleCancel()
              }
            },
            secondaryButton: {
              value: 'ok',
              action: () => {
                event.result.handleConfirm()
              }
            },
            cancel: () => {
              event.result.handleCancel()
            }
          })
          return true
        })
    }
  }
}

onPrompt⁹⁺

onPrompt(callback: (event?: { url: string; message: string; value: string; result: JsResult }) => boolean)

参数：

参数名	参数类型	参数描述
url	string	当前显示弹窗所在网页的URL。
message	string	弹窗中显示的信息。
result	JsResult	通知Web组件用户操作行为。

返回值：

类型	说明
boolean	当回调返回false时，触发默认弹窗。当回调返回true时，系统应用可以调用系统弹窗能力（包括确认和取消），并且需要根据用户的确认或取消操作调用JsResult通知Web组件。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()

  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .onPrompt((event) => {
          console.log("url:" + event.url)
          console.log("message:" + event.message)
          console.log("value:" + event.value)
          AlertDialog.show({
            title: 'onPrompt',
            message: 'text',
            primaryButton: {
              value: 'cancel',
              action: () => {
                event.result.handleCancel()
              }
            },
            secondaryButton: {
              value: 'ok',
              action: () => {
                event.result.handleConfirm()
              }
            },
            cancel: () => {
              event.result.handleCancel()
            }
          })
          return true
        })
    }
  }
}

onConsole

onConsole(callback: (event?: { message: ConsoleMessage }) => boolean)

通知宿主应用JavaScript console消息。

参数：

参数名	参数类型	参数描述
message	ConsoleMessage	触发的控制台信息。

返回值：

类型	说明
boolean	当返回true时，该条消息将不会再打印至控制台，反之仍会打印至控制台。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()

  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .onConsole((event) => {
          console.log('getMessage:' + event.message.getMessage())
          console.log('getSourceId:' + event.message.getSourceId())
          console.log('getLineNumber:' + event.message.getLineNumber())
          console.log('getMessageLevel:' + event.message.getMessageLevel())
          return false
        })
    }
  }
}

onDownloadStart

onDownloadStart(callback: (event?: { url: string, userAgent: string, contentDisposition: string, mimetype: string, contentLength: number }) => void)

参数：

参数名	参数类型	参数描述
url	string	文件下载的URL。
contentDisposition	string	服务器返回的 Content-Disposition响应头，可能为空。
mimetype	string	服务器返回内容媒体类型（MIME）信息。
contentLength	contentLength	服务器返回文件的长度。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()

  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .onDownloadStart((event) => {
          console.log('url:' + event.url)
          console.log('userAgent:' + event.userAgent)
          console.log('contentDisposition:' + event.contentDisposition)
          console.log('contentLength:' + event.contentLength)
          console.log('mimetype:' + event.mimetype)
        })
    }
  }
}

onErrorReceive

onErrorReceive(callback: (event?: { request: WebResourceRequest, error: WebResourceError }) => void)

网页加载遇到错误时触发该回调。出于性能考虑，建议此回调中尽量执行简单逻辑。

参数：

参数名	参数类型	参数描述
request	WebResourceRequest	网页请求的封装信息。
error	WebResourceError	网页加载资源错误的封装信息。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()

  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .onErrorReceive((event) => {
          console.log('getErrorInfo:' + event.error.getErrorInfo())
          console.log('getErrorCode:' + event.error.getErrorCode())
          console.log('url:' + event.request.getRequestUrl())
          console.log('isMainFrame:' + event.request.isMainFrame())
          console.log('isRedirect:' + event.request.isRedirect())
          console.log('isRequestGesture:' + event.request.isRequestGesture())
          console.log('getRequestHeader_headerKey:' + event.request.getRequestHeader().toString())
          let result = event.request.getRequestHeader()
          console.log('The request header result size is ' + result.length)
          for (let i of result) {
            console.log('The request header key is : ' + i.headerKey + ', value is : ' + i.headerValue)
          }
        })
    }
  }
}

onHttpErrorReceive

onHttpErrorReceive(callback: (event?: { request: WebResourceRequest, response: WebResourceResponse }) => void)

网页加载资源遇到的HTTP错误（响应码>=400)时触发该回调。

参数：

参数名	参数类型	参数描述
request	WebResourceRequest	网页请求的封装信息。
response	WebResourceResponse	资源响应的封装信息。

示例：

// xxx.ets@Entry@Componentstruct WebComponent {  controller: WebController = new WebController()
build()Column()      Web({ src: 'www.example.com', controller: this.controller })(event) =>          console.log('url:' + event.request.getRequestUrl())          console.log('isMainFrame:' + event.request.isMainFrame())          console.log('isRedirect:' + event.request.isRedirect())          console.log('isRequestGesture:' + event.request.isRequestGesture())          console.log('getResponseData:' + event.response.getResponseData())          console.log('getResponseEncoding:' + event.response.getResponseEncoding())          console.log('getResponseMimeType:' + event.response.getResponseMimeType())          console.log('getResponseCode:' + event.response.getResponseCode())          console.log('getReasonMessage:' + event.response.getReasonMessage())          let result = event.request.getRequestHeader()          console.log('The request header result size is ' + result.length)          for (let i of result) {            console.log('The request header key is : ' + i.headerKey + ' , value is : ' + i.headerValue)          }          let resph = event.response.getResponseHeader()          console.log('The response header result size is ' + resph.length)          for (let i of resph) {            console.log('The response header key is : ' + i.headerKey + ' , value is : ' + i.headerValue)          }        })    }  }}

onPageBegin

onPageBegin(callback: (event?: { url: string }) => void)

网页开始加载时触发该回调，且只在主frame触发，iframe或者frameset的内容加载时不会触发此回调。

参数：

参数名	参数类型	参数描述
url	string	页面的URL地址。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()

  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .onPageBegin((event) => {
          console.log('url:' + event.url)
        })
    }
  }
}

onPageEnd

onPageEnd(callback: (event?: { url: string }) => void)

网页加载完成时触发该回调，且只在主frame触发。

参数：

参数名	参数类型	参数描述
url	string	页面的URL地址。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()

  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .onPageEnd((event) => {
          console.log('url:' + event.url)
        })
    }
  }
}

onProgressChange

onProgressChange(callback: (event?: { newProgress: number }) => void)

网页加载进度变化时触发该回调。

参数：

参数名	参数类型	参数描述
newProgress	number	新的加载进度，取值范围为0到100的整数。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()

  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .onProgressChange((event) => {
          console.log('newProgress:' + event.newProgress)
        })
    }
  }
}

onTitleReceive

onTitleReceive(callback: (event?: { title: string }) => void)

网页document标题更改时触发该回调。

参数：

参数名	参数类型	参数描述
title	string	document标题内容。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()

  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .onTitleReceive((event) => {
          console.log('title:' + event.title)
        })
    }
  }
}

onRefreshAccessedHistory

onRefreshAccessedHistory(callback: (event?: { url: string, isRefreshed: boolean }) => void)

加载网页页面完成时触发该回调，用于应用更新其访问的历史链接。

参数：

参数名	参数类型	参数描述
url	string	访问的url。
isRefreshed	boolean	true表示该页面是被重新加载的（调用refresh接口），false表示该页面是新加载的。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()

  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .onRefreshAccessedHistory((event) => {
          console.log('url:' + event.url + ' isReload:' + event.isRefreshed)
        })
    }
  }
}

onRenderExited⁹⁺

onRenderExited(callback: (event?: { renderExitReason: RenderExitReason }) => void)

应用渲染进程异常退出时触发该回调。

参数：

参数名	参数类型	参数描述
renderExitReason	RenderExitReason	渲染进程进程异常退出的具体原因。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()

  build() {
    Column() {
      Web({ src: 'chrome://crash/', controller: this.controller })
        .onRenderExited((event) => {
          console.log('reason:' + event.renderExitReason)
        })
    }
  }
}

onRenderExited

onRenderExited(callback: (event?: { detail: object }) => boolean)

应用渲染进程异常退出时触发该回调。

从API version 9开始废弃，建议使用onRenderExited9+代替。

参数：

参数名	参数类型	参数描述
detail	object	渲染进程进程异常退出的具体原因。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()

  build() {
    Column() {
      Web({ src: 'chrome://crash/', controller: this.controller })
        .onRenderExited((event) => {
          console.log('reason:' + event.renderExitReason)
        })
    }
  }
}

onShowFileSelector⁹⁺

onShowFileSelector(callback: (event?: { result: FileSelectorResult, fileSelector: FileSelectorParam }) => boolean)

调用此函数以处理具有“文件”输入类型的HTML表单，以响应用户按下的“选择文件”按钮。

参数：

参数名	参数类型	参数描述
result	FileSelectorResult	用于通知Web组件文件选择的结果。
fileSelector	FileSelectorParam	文件选择器的相关信息。

返回值：

类型	说明
boolean	当返回值为true时，用户可以调用系统提供的弹窗能力。当返回值为false时，触发Web默认弹窗。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()

  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .onShowFileSelector((event) => {
          AlertDialog.show({
            title: event.fileSelector.getTitle(),
            message: 'isCapture:' + event.fileSelector.isCapture() + " mode:" + event.fileSelector.getMode() + 'acceptType:' + event.fileSelector.getAcceptType(),
            confirm: {
              value: 'upload',
              action: () => {
                let fileList: Array<string> = [
                  '/data/storage/el2/base/test',
                ]
                event.result.handleFileList(fileList)
              }
            },
            cancel: () => {
              let fileList: Array<string> = []
              event.result.handleFileList(fileList)
            }
          })
          return true
        })
    }
  }
}

onResourceLoad⁹⁺

onResourceLoad(callback: (event: {url: string}) => void)

通知Web组件所加载的资源文件url信息。

参数：

参数名	参数类型	参数描述
url	string	所加载的资源文件url信息。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()

  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .onResourceLoad((event) => {
          console.log('onResourceLoad: ' + event.url)
        })
    }
  }
}

onScaleChange⁹⁺

onScaleChange(callback: (event: {oldScale: number, newScale: number}) => void)

当前页面显示比例的变化时触发该回调。

参数：

参数名	参数类型	参数描述
oldScale	number	变化前的显示比例百分比。
newScale	number	变化后的显示比例百分比。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()

  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .onScaleChange((event) => {
          console.log('onScaleChange changed from ' + event.oldScale + ' to ' + event.newScale)
        })
    }
  }
}

onUrlLoadIntercept

onUrlLoadIntercept(callback: (event?: { data:string | WebResourceRequest }) => boolean)

当Web组件加载url之前触发该回调，用于是否阻止此次访问。

参数：

参数名	参数类型	参数描述
data	string / WebResourceRequest	url的相关信息。

返回值：

类型	说明
boolean	返回true表示阻止此次加载，否则允许此次加载。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()

  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .onUrlLoadIntercept((event) => {
          console.log('onUrlLoadIntercept ' + event.data.toString())
          return true
        })
    }
  }
}

onInterceptRequest⁹⁺

onInterceptRequest(callback: (event?: { request: WebResourceRequest}) => WebResourceResponse)

当Web组件加载url之前触发该回调，用于拦截url并返回响应数据。

参数：

参数名	参数类型	参数描述
request	WebResourceRequest	url请求的相关信息。

返回值：

类型	说明
WebResourceResponse	返回响应数据则按照响应数据加载，无响应数据则返回null表示按照原来的方式加载。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()
  responseweb: WebResourceResponse = new WebResourceResponse()
  heads:Header[] = new Array()
  @State webdata: string = "<!DOCTYPE html>\n" +
  "<html>\n"+
  "<head>\n"+
  "<title>intercept test</title>\n"+
  "</head>\n"+
  "<body>\n"+
  "<h1>intercept test</h1>\n"+
  "</body>\n"+
  "</html>"
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .onInterceptRequest((event) => {
          console.log('url:' + event.request.getRequestUrl())
          var head1:Header = {
            headerKey:"Connection",
            headerValue:"keep-alive"
          }
          var head2:Header = {
            headerKey:"Cache-Control",
            headerValue:"no-cache"
          }
          var length = this.heads.push(head1)
          length = this.heads.push(head2)
          this.responseweb.setResponseHeader(this.heads)
          this.responseweb.setResponseData(this.webdata)
          this.responseweb.setResponseEncoding('utf-8')
          this.responseweb.setResponseMimeType('text/html')
          this.responseweb.setResponseCode(200)
          this.responseweb.setReasonMessage('OK')
          return this.responseweb
        })
    }
  }
}

onHttpAuthRequest⁹⁺

onHttpAuthRequest(callback: (event?: { handler: HttpAuthHandler, host: string, realm: string}) => boolean)

通知收到http auth认证请求。

参数：

参数名	参数类型	参数描述
handler	HttpAuthHandler	通知Web组件用户操作行为。
host	string	HTTP身份验证凭据应用的主机。
realm	string	HTTP身份验证凭据应用的域。

返回值：

类型	说明
boolean	返回false表示此次认证失败，否则成功。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()
  httpAuth: boolean = false

  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .onHttpAuthRequest((event) => {
          AlertDialog.show({
            title: 'onHttpAuthRequest',
            message: 'text',
            primaryButton: {
              value: 'cancel',
              action: () => {
                event.handler.cancel()
              }
            },
            secondaryButton: {
              value: 'ok',
              action: () => {
                this.httpAuth = event.handler.isHttpAuthInfoSaved()
                if (this.httpAuth == false) {
                  web_webview.WebDataBase.saveHttpAuthCredentials(
                    event.host,
                    event.realm,
                    "2222",
                    "2222"
                  )
                  event.handler.cancel()
                }
              }
            },
            cancel: () => {
              event.handler.cancel()
            }
          })
          return true
        })
    }
  }
}

onSslErrorEventReceive⁹⁺

onSslErrorEventReceive(callback: (event: { handler: SslErrorHandler, error: SslError }) => void)

通知用户加载资源时发生SSL错误。

参数：

参数名	参数类型	参数描述
handler	SslErrorHandler	通知Web组件用户操作行为。
error	SslError	错误码。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()

  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .onSslErrorEventReceive((event) => {
          AlertDialog.show({
            title: 'onSslErrorEventReceive',
            message: 'text',
            primaryButton: {
              value: 'confirm',
              action: () => {
                event.handler.handleConfirm()
              }
            },
            secondaryButton: {
              value: 'cancel',
              action: () => {
                event.handler.handleCancel()
              }
            },
            cancel: () => {
              event.handler.handleCancel()
            }
          })
          return true
        })
    }
  }
}

onClientAuthenticationRequest⁹⁺

onClientAuthenticationRequest(callback: (event: {handler : ClientAuthenticationHandler, host : string, port : number, keyTypes : Array, issuers : Array}) => void)

通知用户收到SSL客户端证书请求事件。

参数：

参数名	参数类型	参数描述
handler	ClientAuthenticationHandler	通知Web组件用户操作行为。
host	string	请求证书服务器的主机名。
port	number	请求证书服务器的端口号。
keyTypes	Array	可接受的非对称秘钥类型。
issuers	Array	与私钥匹配的证书可接受颁发者。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()

  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .onClientAuthenticationRequest((event) => {
          AlertDialog.show({
            title: 'onClientAuthenticationRequest',
            message: 'text',
            primaryButton: {
              value: 'confirm',
              action: () => {
                event.handler.confirm("/system/etc/user.pk8", "/system/etc/chain-user.pem")
              }
            },
            secondaryButton: {
              value: 'cancel',
              action: () => {
                event.handler.cancel()
              }
            },
            cancel: () => {
              event.handler.ignore()
            }
          })
          return true
        })
    }
  }
}

onPermissionRequest⁹⁺

onPermissionRequest(callback: (event?: { request: PermissionRequest }) => void)

通知收到获取权限请求。

参数：

参数名	参数类型	参数描述
request	PermissionRequest	通知Web组件用户操作行为。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .onPermissionRequest((event) => {
          AlertDialog.show({
            title: 'title',
            message: 'text',
            primaryButton: {
              value: 'deny',
              action: () => {
                event.request.deny()
              }
            },
            secondaryButton: {
              value: 'onConfirm',
              action: () => {
                event.request.grant(event.request.getAccessibleResource())
              }
            },
            cancel: () => {
              event.request.deny()
            }
          })
        })
    }
  }
}

onContextMenuShow⁹⁺

onContextMenuShow(callback: (event?: { param: WebContextMenuParam, result: WebContextMenuResult }) => boolean)

长按特定元素（例如图片，链接），跳出菜单。

参数：

参数名	参数类型	参数描述
param	WebContextMenuParam	菜单相关参数。
result	WebContextMenuResult	菜单相应事件传入内核。

返回值：

类型	说明
boolean	自定义菜单返回true，默认菜单返回false。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .onContextMenuShow((event) => {
          console.info("x coord = " + event.param.x())
          console.info("link url = " + event.param.getLinkUrl())
          return true
      })
    }
  }
}

onScroll⁹⁺

onScroll(callback: (event: {xOffset: number, yOffset: number}) => void)

通知网页滚动条滚动位置。

参数：

参数名	参数类型	参数描述
xOffset	number	水平滚动条滚动所在位置。
yOffset	number	竖直滚动条滚动所在位置。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
      .onScroll((event) => {
          console.info("x = " + event.xOffset)
          console.info("y = " + event.yOffset)
      })
    }
  }
}

onGeolocationShow

onGeolocationShow(callback: (event?: { origin: string, geolocation: JsGeolocation }) => void)

通知用户收到地理位置信息获取请求。

参数：

参数名	参数类型	参数描述
origin	string	指定源的字符串索引。
geolocation	JsGeolocation	通知Web组件用户操作行为。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller:WebController = new WebController()
  build() {
    Column() {
      Web({ src:'www.example.com', controller:this.controller })
      .geolocationAccess(true)
      .onGeolocationShow((event) => {
        AlertDialog.show({
          title: 'title',
          message: 'text',
          confirm: {
            value: 'onConfirm',
            action: () => {
              event.geolocation.invoke(event.origin, true, true)
            }
          },
          cancel: () => {
            event.geolocation.invoke(event.origin, false, true)
          }
        })
      })
    }
  }
}

onGeolocationHide

onGeolocationHide(callback: () => void)

通知用户先前被调用onGeolocationShow时收到地理位置信息获取请求已被取消。

参数：

参数名	参数类型	参数描述
callback	() => void	地理位置信息获取请求已被取消的回调函数。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller:WebController = new WebController()
  build() {
    Column() {
      Web({ src:'www.example.com', controller:this.controller })
      .geolocationAccess(true)
      .onGeolocationHide(() => {
        console.log("onGeolocationHide...")
      })
    }
  }
}

onFullScreenEnter⁹⁺

onFullScreenEnter(callback: (event: { handler: FullScreenExitHandler }) => void)

通知开发者web组件进入全屏模式。

参数：

参数名	参数类型	参数描述
handler	FullScreenExitHandler	用于退出全屏模式的函数句柄。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller:WebController = new WebController()
  handler: FullScreenExitHandler = null
  build() {
    Column() {
      Web({ src:'www.example.com', controller:this.controller })
      .onFullScreenEnter((event) => {
        console.log("onFullScreenEnter...")
        this.handler = event.handler
      })
    }
  }
}

onFullScreenExit⁹⁺

onFullScreenExit(callback: () => void)

通知开发者web组件退出全屏模式。

参数：

参数名	参数类型	参数描述
callback	() => void	退出全屏模式时的回调函数。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller:WebController = new WebController()
  handler: FullScreenExitHandler = null
  build() {
    Column() {
      Web({ src:'www.example.com', controller:this.controller })
      .onFullScreenExit(() => {
        console.log("onFullScreenExit...")
        this.handler.exitFullScreen()
      })
      .onFullScreenEnter((event) => {
        this.handler = event.handler
      })
    }
  }
}

onWindowNew⁹⁺

onWindowNew(callback: (event: {isAlert: boolean, isUserTrigger: boolean, targetUrl: string, handler: ControllerHandler}) => void)

通知用户新建窗口请求。

参数：

参数名	参数类型	参数描述
isAlert	boolean	true代表请求创建对话框，false代表新标签页。
isUserTrigger	boolean	true代表用户触发，false代表非用户触发。
targetUrl	string	目标url。
handler	ControllerHandler	用于设置新建窗口的WebController实例。

示例：

import web_webview from '@ohos.web.webview';
// xxx.ets
@Entry
@Component
struct WebComponent {
  
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  build() {
    Column() {
      Web({ src:'www.example.com', controller: this.controller })
      .multiWindowAccess(true)
      .onWindowNew((event) => {
        console.log("onWindowNew...")
         var popController: web_webview.WebviewController = new web_webview.WebviewController()
        event.handler.setWebController(popController)
      })
    }
  }
}

onWindowExit⁹⁺

onWindowExit(callback: () => void)

通知用户窗口关闭请求。

参数：

参数名	参数类型	参数描述
callback	() => void	窗口请求关闭的回调函数。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller:WebController = new WebController()
  build() {
    Column() {
      Web({ src:'www.example.com', controller: this.controller })
      .onWindowExit(() => {
        console.log("onWindowExit...")
      })
    }
  }
}

onSearchResultReceive⁹⁺

onSearchResultReceive(callback: (event?: {activeMatchOrdinal: number, numberOfMatches: number, isDoneCounting: boolean}) => void): WebAttribute

回调通知调用方网页页内查找的结果。

参数：

参数名	参数类型	参数描述
activeMatchOrdinal	number	当前匹配的查找项的序号（从0开始）。
numberOfMatches	number	所有匹配到的关键词的个数。
isDoneCounting	boolean	当次页内查找操作是否结束。该方法可能会回调多次，直到isDoneCounting为true为止。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()

  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
         .onSearchResultReceive(ret => {
          console.log("on search result receive:" + "[cur]" + ret.activeMatchOrdinal +
            "[total]" + ret.numberOfMatches + "[isDone]"+ ret.isDoneCounting)
        })
    }
  }
}

文章转载自：https://developer.harmonyos.com/cn/docs/documentation/doc-references-V3/ts-basic-components-web-0000001477981205-V3?catalogVersion=V3#ZH-CN_TOPIC_0000001477981205__事件

分类

卡片开发

IDE

标签

HarmonyOS API

51CTO

51CTO博客

51CTO学堂

HarmonyOS API：基础组件

Web

需要权限

子组件

接口

属性

domStorageAccess

fileAccess

imageAccess

javaScriptProxy

javaScriptAccess

mixedMode

onlineImageAccess

zoomAccess

overviewModeAccess

databaseAccess

geolocationAccess

mediaPlayGestureAccess

multiWindowAccess9+

cacheMode

textZoomRatio9+

initialScale9+

userAgent

webDebuggingAccess9+

事件

onAlert

onBeforeUnload

onConfirm

onPrompt9+

onConsole

onDownloadStart

onErrorReceive

onHttpErrorReceive

onPageBegin

onPageEnd

onProgressChange

onTitleReceive

onRefreshAccessedHistory

onRenderExited9+

onRenderExited

onShowFileSelector9+

onResourceLoad9+

onScaleChange9+

onUrlLoadIntercept

onInterceptRequest9+

onHttpAuthRequest9+

onSslErrorEventReceive9+

onClientAuthenticationRequest9+

onPermissionRequest9+

onContextMenuShow9+

onScroll9+

onGeolocationShow

onGeolocationHide

onFullScreenEnter9+

onFullScreenExit9+

onWindowNew9+

onWindowExit9+

onSearchResultReceive9+

目录

订阅鸿蒙技术特刊，精选内容抢先看

multiWindowAccess⁹⁺

textZoomRatio⁹⁺

initialScale⁹⁺

webDebuggingAccess⁹⁺

onPrompt⁹⁺

onRenderExited⁹⁺

onShowFileSelector⁹⁺

onResourceLoad⁹⁺

onScaleChange⁹⁺

onInterceptRequest⁹⁺

onHttpAuthRequest⁹⁺

onSslErrorEventReceive⁹⁺

onClientAuthenticationRequest⁹⁺

onPermissionRequest⁹⁺

onContextMenuShow⁹⁺

onScroll⁹⁺

onFullScreenEnter⁹⁺

onFullScreenExit⁹⁺

onWindowNew⁹⁺

onWindowExit⁹⁺

onSearchResultReceive⁹⁺