创建Web消息端口。
**返回值：**
| 类型 | 说明 |
| ---------------------------------------- | ---------- |
| Array\<[WebMessagePort](#webmessageport9)\> | web消息端口列表。 |
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController()
ports: WebMessagePort[] = null
build() {
Column() {
Button('createWebMessagePorts')
.onClick(() => {
this.ports = this.controller.createWebMessagePorts()
console.log("createWebMessagePorts size:" + this.ports.length)
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
### postMessage9+
postMessage(options: { message: WebMessageEvent, uri: string}): void
发送Web消息端口到HTML5。
**参数：**
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| ------- | ------------------------------------ | ---- | ---- | ----------------- |
| message | [WebMessageEvent](#webmessageevent9) | 是 | - | 要发送的消息，包含数据和消息端口。 |
| uri | string | 是 | - | 接收该消息的URI。 |
**示例：**
```ts
// index.ets
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController()
ports: WebMessagePort[] = null
@State sendFromEts: string = 'Send this message from ets to HTML'
@State receivedFromHtml: string = 'Display received message send from HTML'
build() {
Column() {
// 展示接收到的来自HTML的内容
Text(this.receivedFromHtml)
// 输入框的内容发送到HTML
TextInput({placeholder: 'Send this message from ets to HTML'})
.onChange((value: string) => {
this.sendFromEts = value
})
// 1、创建两个消息端口
Button('1.CreateWebMessagePorts')
.onClick(() => {
this.ports = this.controller.createWebMessagePorts()
console.log("createWebMessagePorts size:" + this.ports.length)
})
// 2、将其中一个消息端口发送到HTML侧，由HTML侧保存并使用。
Button('2.PostMessagePort')
.onClick(() => {
var sendPortArray = new Array(this.ports[1])
var msgEvent = new WebMessageEvent()
msgEvent.setData("__init_port__")
msgEvent.setPorts(sendPortArray)
this.controller.postMessage({message: msgEvent, uri: "*"})
})
// 3、另一个消息端口在应用侧注册回调事件。
Button('3.RegisterCallback')
.onClick(() => {
this.ports[0].onMessageEvent((result: string) => {
var msg = 'Got msg from HTML: ' + result
this.receivedFromHtml = msg
})
})
// 4、使用应用侧的端口给另一个已经发送到HTML的消息端口发送消息。
Button('4.SendDataToHtml5')
.onClick(() => {
var msg = new WebMessageEvent()
msg.setData(this.sendFromEts)
this.ports[0].postMessageEvent(msg)
})
Web({ src: $rawfile("index.html"), controller: this.controller })
.javaScriptAccess(true)
.fileAccess(true)
}
}
}
// index.html
Web Message Port Demo
display received message send from ets
// index.js
var h5Port;
var output = document.querySelector('.output');
window.addEventListener('message', function(event) {
if (event.data == '__init_port__') {
if(event.ports[0] != null) {
h5Port = event.ports[0]; // 1. 保存从ets侧发送过来的端口
h5Port.onmessage = function(event) {
// 2. 接收ets侧发送过来的消息.
var msg = 'Got message from ets:' + event.data;
output.innerHTML = msg;
}
}
}
})
// 3. 使用h5Port往ets侧发送消息.
function PostMsgToEts(data) {
h5Port.postMessage(data)
}
```
### getUrl9+
getUrl(): string
获取当前页面的url地址。
**返回值：**
| 类型 | 说明 |
| ------ | ----------- |
| string | 当前页面的url地址。 |
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController()
build() {
Column() {
Button('getUrl')
.onClick(() => {
console.log("url: " + this.controller.getUrl())
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
### searchAllAsync9+
searchAllAsync(searchString: string): void
异步查找网页中所有匹配关键字'searchString'的内容并高亮，结果通过[onSearchResultReceive](#onsearchresultreceive9)异步返回。
**参数：**
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| ------------ | ------ | ---- | ---- | ------- |
| searchString | string | 是 | - | 查找的关键字。 |
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController()
@State searchString: string = "xxx"
build() {
Column() {
Button('searchString')
.onClick(() => {
this.controller.searchAllAsync(this.searchString)
})
Button('clearMatches')
.onClick(() => {
this.controller.clearMatches()
})
Button('searchNext')
.onClick(() => {
this.controller.searchNext(true)
})
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)
})
}
}
}
```
### clearMatches9+
clearMatches(): void
清除所有通过[searchAllAsync](#searchallasync9)匹配到的高亮字符查找结果。
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController()
build() {
Column() {
Button('clearMatches')
.onClick(() => {
this.controller.clearMatches()
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
### searchNext9+
searchNext(forward: boolean): void
滚动到下一个匹配的查找结果并高亮。
**参数：**
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| ------- | ------- | ---- | ---- | ----------- |
| forward | boolean | 是 | - | 从前向后或者逆向查找。 |
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController()
build() {
Column() {
Button('searchNext')
.onClick(() => {
this.controller.searchNext(true)
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
## HitTestValue9+
提供点击区域的元素信息。示例代码参考[getHitTestValue](#gethittestvalue9)。
### getType9+
getType(): HitTestType
获取当前被点击区域的元素类型。
**返回值：**
| 类型 | 说明 |
| ------------------------------- | ------------- |
| [HitTestType](#hittesttype枚举说明) | 当前被点击区域的元素类型。 |
### getExtra9+
getExtra(): string
若被点击区域为图片或链接，则附加参数信息为其url地址。
**返回值：**
| 类型 | 说明 |
| ------ | ------------ |
| string | 点击区域的附加参数信息。 |
## WebCookie
通过WebCookie可以控制Web组件中的cookie的各种行为，其中每个应用中的所有web组件共享一个WebCookie。通过controller方法中的getCookieManager方法可以获取WebCookie对象，进行后续的cookie管理操作。
### setCookie9+
setCookie(url: string, value: string): boolean
设置cookie，该方法为同步方法。设置成功返回true，否则返回false。
**参数：**
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| ----- | ------ | ---- | ---- | ----------------- |
| url | string | 是 | - | 要设置的cookie所属的url。 |
| value | string | 是 | - | cookie的值。 |
**返回值：**
| 类型 | 说明 |
| ------- | ------------- |
| boolean | 设置cookie是否成功。 |
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController()
build() {
Column() {
Button('setCookie')
.onClick(() => {
let result = this.controller.getCookieManager().setCookie("www.example.com", "a=b")
console.log("result: " + result)
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
### saveCookieSync9+
saveCookieSync(): boolean
将当前存在内存中的cookie同步到磁盘中，该方法为同步方法。
**返回值：**
| 类型 | 说明 |
| ------- | -------------------- |
| boolean | 同步内存cookie到磁盘操作是否成功。 |
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController()
build() {
Column() {
Button('saveCookieSync')
.onClick(() => {
let result = this.controller.getCookieManager().saveCookieSync()
console.log("result: " + result)
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
### getCookie9+
getCookie(url: string): string
获取指定url对应cookie的值。
**参数：**
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| ---- | ------ | ---- | ---- | ----------------- |
| url | string | 是 | - | 要获取的cookie所属的url。 |
**返回值：**
| 类型 | 说明 |
| ------ | ----------------- |
| string | 指定url对应的cookie的值。 |
**示例：**
```ts
// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController()
build() {
Column() {
Button('getCookie')
.onClick(() => {
let value = web_webview.WebCookieManager.getCookie('www.example.com')
console.log("value: " + value)
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
### setCookie9+
setCookie(url: string, value: string): boolean
为指定url设置单个cookie的值。
**参数：**
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| ----- | ------ | ---- | ---- | ----------------- |
| url | string | 是 | - | 要设置的cookie所属的url。 |
| value | string | 是 | - | 要设置的cookie的值。 |
**返回值：**
| 类型 | 说明 |
| ------- | ------------- |
| boolean | 设置cookie是否成功。 |
**示例：**
```ts
// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController()
build() {
Column() {
Button('setCookie')
.onClick(() => {
let result = web_webview.WebCookieManager.setCookie('www.example.com', 'a=b')
console.log("result: " + result)
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
### saveCookieSync9+
saveCookieSync(): boolean
将当前存在内存中的cookie保存到磁盘中，该方法为同步方法。
**返回值：**
| 类型 | 说明 |
| ------- | -------------------- |
| boolean | 同步内存cookie到磁盘操作是否成功。 |
**示例：**
```ts
// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController()
build() {
Column() {
Button('saveCookieSync')
.onClick(() => {
let result = web_webview.WebCookieManager.saveCookieSync()
console.log("result: " + result)
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
### saveCookieAsync9+
saveCookieAsync(): Promise\
将当前存在内存中的cookie以Promise方法异步保存到磁盘中。
**返回值：**
| 类型 | 说明 |
| ----------------- | --------------------------- |
| Promise\ | Promise实例，用于获取cookie是否成功保存。 |
**示例：**
```ts
// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController()
build() {
Column() {
Button('saveCookieAsync')
.onClick(() => {
web_webview.WebCookieManager.saveCookieAsync()
.then (function(result) {
console.log("result: " + result)
})
.catch(function(error) {
console.error("error: " + error)
})
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
### saveCookieAsync9+
saveCookieAsync(callback: AsyncCallback\): void
将当前存在内存中的cookie异步保存到磁盘中。
**参数：**
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| -------- | ----------------------- | ---- | ---- | ---------------------------- |
| callback | AsyncCallback\ | 是 | - | 返回cookie是否成功保存的布尔值作为回调函数的入参。 |
**示例：**
```ts
// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController()
build() {
Column() {
Button('saveCookieAsync')
.onClick(() => {
web_webview.WebCookieManager.saveCookieAsync(function(result) {
console.log("result: " + result)
})
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
### isCookieAllowed9+
isCookieAllowed(): boolean
获取WebCookieManager实例是否拥有发送和接收cookie的权限。
**返回值：**
| 类型 | 说明 |
| ------- | ------------------- |
| boolean | 是否拥有发送和接收cookie的权限。 |
**示例：**
```ts
// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController()
build() {
Column() {
Button('isCookieAllowed')
.onClick(() => {
let result = web_webview.WebCookieManager.isCookieAllowed()
console.log("result: " + result)
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
### putAcceptCookieEnabled9+
putAcceptCookieEnabled(accept: boolean): void
设置WebCookieManager实例是否拥有发送和接收cookie的权限。
**参数：**
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| ------ | ------- | ---- | ---- | --------------------- |
| accept | boolean | 是 | - | 设置是否拥有发送和接收cookie的权限。 |
**示例：**
```ts
// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController()
build() {
Column() {
Button('putAcceptCookieEnabled')
.onClick(() => {
web_webview.WebCookieManager.putAcceptCookieEnabled(false)
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
### isThirdPartyCookieAllowed9+
isThirdCookieAllowed(): boolean
获取WebCookieManager实例是否拥有发送和接收第三方cookie的权限。
**返回值：**
| 类型 | 说明 |
| ------- | ---------------------- |
| boolean | 是否拥有发送和接收第三方cookie的权限。 |
**示例：**
```ts
// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController()
build() {
Column() {
Button('isThirdPartyCookieAllowed')
.onClick(() => {
let result = web_webview.WebCookieManager.isThirdPartyCookieAllowed()
console.log("result: " + result)
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
### putAcceptThirdPartyCookieEnabled9+
putAcceptThirdPartyCookieEnabled(accept: boolean): void
设置WebCookieManager实例是否拥有发送和接收第三方cookie的权限。
**参数：**
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| ------ | ------- | ---- | ---- | ------------------------ |
| accept | boolean | 是 | - | 设置是否拥有发送和接收第三方cookie的权限。 |
**示例：**
```ts
// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController()
build() {
Column() {
Button('putAcceptThirdPartyCookieEnabled')
.onClick(() => {
web_webview.WebCookieManager.putAcceptThirdPartyCookieEnabled(false)
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
### existCookie9+
existCookie(): boolean
获取是否存在cookie。
**返回值：**
| 类型 | 说明 |
| ------- | ----------- |
| boolean | 是否存在cookie。 |
**示例：**
```ts
// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController()
build() {
Column() {
Button('existCookie')
.onClick(() => {
let result = web_webview.WebCookieManager.existCookie()
console.log("result: " + result)
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
### deleteEntireCookie9+
deleteEntireCookie(): void
清除所有cookie。
**示例：**
```ts
// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController()
build() {
Column() {
Button('deleteEntireCookie')
.onClick(() => {
web_webview.WebCookieManager.deleteEntireCookie()
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
### deleteSessionCookie9+
deleteSessionCookie(): void
清除所有会话cookie。
**示例：**
```ts
// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController()
build() {
Column() {
Button('deleteSessionCookie')
.onClick(() => {
web_webview.WebCookieManager.deleteSessionCookie()
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
## WebDataBase9+
web组件数据库管理对象。
### existHttpAuthCredentials9+
static existHttpAuthCredentials(): boolean
判断是否存在任何已保存的HTTP身份验证凭据，该方法为同步方法。存在返回true，不存在返回false。
**返回值：**
| 类型 | 说明 |
| ------- | ---------------------------------------- |
| boolean | 是否存在任何已保存的HTTP身份验证凭据。存在返回true，不存在返回false |
**示例：**
```ts
// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController()
build() {
Column() {
Button('existHttpAuthCredentials')
.onClick(() => {
let result = web_webview.WebDataBase.existHttpAuthCredentials()
console.log('result: ' + result)
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
### deleteHttpAuthCredentials9+
static deleteHttpAuthCredentials(): void
清除所有已保存的HTTP身份验证凭据，该方法为同步方法。
**示例：**
```ts
// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController()
build() {
Column() {
Button('deleteHttpAuthCredentials')
.onClick(() => {
web_webview.WebDataBase.deleteHttpAuthCredentials()
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
### getHttpAuthCredentials9+
static getHttpAuthCredentials(host: string, realm: string): Array\
检索给定主机和域的HTTP身份验证凭据，该方法为同步方法。检索成功返回一个包含用户名和密码的组数，检索不成功返回空数组。
**参数：**
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| ----- | ------ | ---- | ---- | ---------------- |
| host | string | 是 | - | HTTP身份验证凭据应用的主机。 |
| realm | string | 是 | - | HTTP身份验证凭据应用的域。 |
**返回值：**
| 类型 | 说明 |
| --------------- | ---------------------- |
| Array\ | 包含用户名和密码的组数，检索失败返回空数组。 |
**示例：**
```ts
// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController()
host: string = "www.spincast.org"
realm: string = "protected example"
username_password: string[]
build() {
Column() {
Button('getHttpAuthCredentials')
.onClick(() => {
this.username_password = web_webview.WebDataBase.getHttpAuthCredentials(this.host, this.realm)
console.log('num: ' + this.username_password.length)
ForEach(this.username_password, (item) => {
console.log('username_password: ' + item)
}, item => item)
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
### saveHttpAuthCredentials9+
static saveHttpAuthCredentials(host: string, realm: string, username: string, password: string): void
保存给定主机和域的HTTP身份验证凭据，该方法为同步方法。
**参数：**
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| -------- | ------ | ---- | ---- | ---------------- |
| host | string | 是 | - | HTTP身份验证凭据应用的主机。 |
| realm | string | 是 | - | HTTP身份验证凭据应用的域。 |
| username | string | 是 | - | 用户名。 |
| password | string | 是 | - | 密码。 |
**示例：**
```ts
// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController()
host: string = "www.spincast.org"
realm: string = "protected example"
build() {
Column() {
Button('saveHttpAuthCredentials')
.onClick(() => {
web_webview.WebDataBase.saveHttpAuthCredentials(this.host, this.realm, "Stromgol", "Laroche")
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
## GeolocationPermissions9+
web组件地理位置权限管理对象。
### allowGeolocation9+
static allowGeolocation(origin: string): void
允许指定来源使用地理位置接口。
**参数：**
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| ------ | ------ | ---- | ---- | ---------- |
| origin | string | 是 | - | 指定源的字符串索引。 |
**示例：**
```ts
// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController()
origin: string = "file:///"
build() {
Column() {
Button('allowGeolocation')
.onClick(() => {
web_webview.GeolocationPermissions.allowGeolocation(this.origin)
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
### deleteGeolocation9+
static deleteGeolocation(origin: string): void
清除指定来源的地理位置权限状态。
**参数：**
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| ------ | ------ | ---- | ---- | ---------- |
| origin | string | 是 | - | 指定源的字符串索引。 |
**示例：**
```ts
// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController()
origin: string = "file:///"
build() {
Column() {
Button('deleteGeolocation')
.onClick(() => {
web_webview.GeolocationPermissions.deleteGeolocation(this.origin)
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
### deleteAllGeolocation9+
static deleteAllGeolocation(): void
清除所有来源的地理位置权限状态。
**示例：**
```ts
// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController()
build() {
Column() {
Button('deleteAllGeolocation')
.onClick(() => {
web_webview.GeolocationPermissions.deleteAllGeolocation()
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
### getAccessibleGeolocation9+
static getAccessibleGeolocation(origin: string, callback: AsyncCallback\): void
以回调方式异步获取指定源的地理位置权限状态。
**参数：**
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| -------- | ------------------------ | ---- | ---- | ---------------------------------------- |
| origin | string | 是 | - | 指定源的字符串索引。 |
| callback | AsyncCallback\ | 是 | - | 返回指定源的地理位置权限状态。获取成功，true表示已授权，false表示拒绝访问。获取失败，表示不存在指定源的权限状态。 |
**示例：**
```ts
// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController()
origin: string = "file:///"
build() {
Column() {
Button('getAccessibleGeolocationAsync')
.onClick(() => {
web_webview.GeolocationPermissions.getAccessibleGeolocation(this.origin, (error, result) => {
if (error) {
console.log('getAccessibleGeolocationAsync error: ' + JSON.stringify(error))
return
}
console.log('getAccessibleGeolocationAsync result: ' + result)
})
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
### getAccessibleGeolocation9+
static getAccessibleGeolocation(origin: string): Promise\
以Promise方式异步获取指定源的地理位置权限状态。
**参数：**
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| ------ | ------ | ---- | ---- | ---------- |
| origin | string | 是 | - | 指定源的字符串索引。 |
**返回值：**
| 类型 | 说明 |
| ------------------ | ---------------------------------------- |
| Promise\ | Promise实例，用于获取指定源的权限状态，获取成功，true表示已授权，false表示拒绝访问。获取失败，表示不存在指定源的权限状态。 |
**示例：**
```ts
// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController()
origin: string = "file:///"
build() {
Column() {
Button('getAccessibleGeolocationPromise')
.onClick(() => {
web_webview.GeolocationPermissions.getAccessibleGeolocation(this.origin).then(result => {
console.log('getAccessibleGeolocationPromise result: ' + result)
}).catch(error => {
console.log('getAccessibleGeolocationPromise error: ' + JSON.stringify(error))
})
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
### getStoredGeolocation9+
static getStoredGeolocation(callback: AsyncCallback\\>): void
以回调方式异步获取已存储地理位置权限状态的所有源信息。
**参数：**
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| -------- | -------------------------------- | ---- | ---- | -------------------- |
| callback | AsyncCallback\\> | 是 | - | 返回已存储地理位置权限状态的所有源信息。 |
**示例：**
```ts
// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController()
build() {
Column() {
Button('getStoredGeolocationAsync')
.onClick(() => {
web_webview.GeolocationPermissions.getStoredGeolocation((error, origins) => {
if (error) {
console.log('getStoredGeolocationAsync error: ' + JSON.stringify(error))
return
}
let origins_str: string = origins.join()
console.log('getStoredGeolocationAsync origins: ' + origins_str)
})
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
### getStoredGeolocation9+
static getStoredGeolocation(): Promise\\>
以Promise方式异步获取已存储地理位置权限状态的所有源信息。
**参数：**
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| -------- | -------------------------------- | ---- | ---- | -------------------- |
| callback | AsyncCallback\\> | 是 | - | 返回已存储地理位置权限状态的所有源信息。 |
**返回值：**
| 类型 | 说明 |
| -------------------------- | -------------------------------- |
| Promise\\> | Promise实例，用于获取已存储地理位置权限状态的所有源信息。 |
**示例：**
```ts
// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController()
build() {
Column() {
Button('getStoredGeolocationPromise')
.onClick(() => {
web_webview.GeolocationPermissions.getStoredGeolocation().then(origins => {
let origins_str: string = origins.join()
console.log('getStoredGeolocationPromise origins: ' + origins_str)
}).catch(error => {
console.log('getStoredGeolocationPromise error: ' + JSON.stringify(error))
})
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
## WebStorage9+
通过WebStorage可管理Web SQL数据库接口和HTML5 Web存储接口，每个应用中的所有Web组件共享一个WebStorage。
### deleteAllData9+
static deleteAllData(): void
清除Web SQL数据库当前使用的所有存储。
**示例：**
```ts
// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController()
build() {
Column() {
Button('deleteAllData')
.onClick(() => {
web_webview.WebStorage.deleteAllData()
})
Web({ src: 'www.example.com', controller: this.controller })
.databaseAccess(true)
}
}
}
```
### deleteOrigin9+
static deleteOrigin(origin : string): void
清除指定源所使用的存储。
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| ------ | ------ | ---- | ---------- |
| origin | string | 是 | 指定源的字符串索引。 |
**示例：**
```ts
// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController()
origin: string = "origin"
build() {
Column() {
Button('getHttpAuthCredentials')
.onClick(() => {
web_webview.WebStorage.deleteOrigin(this.origin)
})
Web({ src: 'www.example.com', controller: this.controller })
.databaseAccess(true)
}
}
}
```
### getOrigins9+
static getOrigins(callback: AsyncCallback\>) : void
以回调方式异步获取当前使用Web SQL数据库的所有源的信息。
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| -------- | ---------------------------------------- | ---- | ----------------------------------- |
| callback | AsyncCallback> | 是 | 以数组方式返回源的信息，信息内容参考WebStorageOrigin。 |
**示例：**
```ts
// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController()
origin: string = "origin"
build() {
Column() {
Button('getOrigins')
.onClick(() => {
web_webview.WebStorage.getOrigins((error, origins) => {
if (error) {
console.log('error: ' + error)
return
}
for (let i = 0; i < origins.length; i++) {
console.log('origin: ' + origins[i].origin)
console.log('usage: ' + origins[i].usage)
console.log('quota: ' + origins[i].quota)
}
})
})
Web({ src: 'www.example.com', controller: this.controller })
.databaseAccess(true)
}
}
}
```
### getOrigins9+
static getOrigins() : Promise\>
以Promise方式异步获取当前使用Web SQL数据库的所有源的信息。
**返回值：**
| 类型 | 说明 |
| ---------------------------------------- | ---------------------------------------- |
| Promise> | Promise实例，用于获取当前所有源的信息，信息内容参考WebStorageOrigin。 |
**示例：**
```ts
// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController()
origin: string = "origin"
build() {
Column() {
Button('getOrigins')
.onClick(() => {
web_webview.WebStorage.getOrigins()
.then(origins => {
for (let i = 0; i < origins.length; i++) {
console.log('origin: ' + origins[i].origin)
console.log('usage: ' + origins[i].usage)
console.log('quota: ' + origins[i].quota)
}
})
.catch(error => {
console.log('error: ' + error)
})
})
Web({ src: 'www.example.com', controller: this.controller })
.databaseAccess(true)
}
}
}
```
### getOriginQuota9+
static getOriginQuota(origin : string, callback : AsyncCallback\) : void
使用callback回调异步获取指定源的Web SQL数据库的存储配额，配额以字节为单位。
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| -------- | ---------------------- | ---- | --------- |
| origin | string | 是 | 指定源的字符串索引 |
| callback | AsyncCallback\ | 是 | 指定源的存储配额。 |
**示例：**
```ts
// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController()
origin: string = "origin"
build() {
Column() {
Button('getOriginQuota')
.onClick(() => {
web_webview.WebStorage.getOriginQuota(this.origin, (error, quota) => {
if (error) {
console.log('error: ' + error)
return
}
console.log('quota: ' + quota)
})
})
Web({ src: 'www.example.com', controller: this.controller })
.databaseAccess(true)
}
}
}
```
### getOriginQuota9+
static getOriginQuota(origin : string) : Promise\
以Promise方式异步获取指定源的Web SQL数据库的存储配额，配额以字节为单位。
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| ------ | ------ | ---- | ---------- |
| origin | string | 是 | 指定源的字符串索引。 |
**返回值：**
| 类型 | 说明 |
| ---------------- | ----------------------- |
| Promise\ | Promise实例，用于获取指定源的存储配额。 |
**示例：**
```ts
// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController();
origin: string = "origin"
build() {
Column() {
Button('getOriginQuota')
.onClick(() => {
web_webview.WebStorage.getOriginQuota(this.origin)
.then(quota => {
console.log('quota: ' + quota)
})
.catch(error => {
console.log('error: ' + error)
})
})
Web({ src: 'www.example.com', controller: this.controller })
.databaseAccess(true)
}
}
}
```
### getOriginUsage9+
static getOriginUsage(origin : string, callback : AsyncCallback\) : void
以回调方式异步获取指定源的Web SQL数据库的存储量，存储量以字节为单位。
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| -------- | ---------------------- | ---- | ---------- |
| origin | string | 是 | 指定源的字符串索引。 |
| callback | AsyncCallback\ | 是 | 指定源的存储量。 |
**示例：**
```ts
// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController();
origin: string = "origin"
build() {
Column() {
Button('getOriginUsage')
.onClick(() => {
web_webview.WebStorage.getOriginUsage(this.origin, (error, usage) => {
if (error) {
console.log('error: ' + error)
return
}
console.log('usage: ' + usage)
})
})
Web({ src: 'www.example.com', controller: this.controller })
.databaseAccess(true)
}
}
}
```
### getOriginUsage9+
static getOriginUsage(origin : string) : Promise\
以Promise方式异步获取指定源的Web SQL数据库的存储量，存储量以字节为单位。
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| ------ | ------ | ---- | ---------- |
| origin | string | 是 | 指定源的字符串索引。 |
**返回值：**
| 类型 | 说明 |
| ---------------- | ---------------------- |
| Promise\ | Promise实例，用于获取指定源的存储量。 |
**示例：**
```ts
// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController();
origin: string = "origin"
build() {
Column() {
Button('getOriginQuota')
.onClick(() => {
web_webview.WebStorage.getOriginUsage(this.origin)
.then(usage => {
console.log('usage: ' + usage)
})
.catch(error => {
console.log('error: ' + error)
})
})
Web({ src: 'www.example.com', controller: this.controller })
.databaseAccess(true)
}
}
}
```
## WebStorageOrigin9+
提供Web SQL数据库的使用信息。
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| ------ | ------ | ---- | ---------- |
| origin | string | 是 | 指定源的字符串索引。 |
| usage | number | 是 | 指定源的存储量。 |
| quota | number | 是 | 指定源的存储配额。 |
## MessageLevel枚举说明
| 名称 | 描述 |
| ----- | :---- |
| Debug | 调试级别。 |
| Error | 错误级别。 |
| Info | 消息级别。 |
| Log | 日志级别。 |
| Warn | 警告级别。 |
## RenderExitReason枚举说明
onRenderExited接口返回的渲染进程退出的具体原因。
| 名称 | 描述 |
| -------------------------- | ----------------- |
| ProcessAbnormalTermination | 渲染进程异常退出。 |
| ProcessWasKilled | 收到SIGKILL，或被手动终止。 |
| ProcessCrashed | 渲染进程崩溃退出，如段错误。 |
| ProcessOom | 程序内存不足。 |
| ProcessExitUnknown | 其他原因。 |
## MixedMode枚举说明
| 名称 | 描述 |
| ---------- | ---------------------------------- |
| All | 允许加载HTTP和HTTPS混合内容。所有不安全的内容都可以被加载。 |
| Compatible | 混合内容兼容性模式，部分不安全的内容可能被加载。 |
| None | 不允许加载HTTP和HTTPS混合内容。 |
## CacheMode枚举说明
| 名称 | 描述 |
| ------- | ------------------------------------ |
| Default | 使用未过期的cache加载资源，如果cache中无该资源则从网络中获取。 |
| None | 加载资源使用cache，如果cache中无该资源则从网络中获取。 |
| Online | 加载资源不使用cache，全部从网络中获取。 |
| Only | 只从cache中加载资源。 |
## FileSelectorMode枚举说明
| 名称 | 描述 |
| -------------------- | ---------- |
| FileOpenMode | 打开上传单个文件。 |
| FileOpenMultipleMode | 打开上传多个文件。 |
| FileOpenFolderMode | 打开上传文件夹模式。 |
| FileSaveMode | 文件保存模式。 |
## HitTestType枚举说明
| 名称 | 描述 |
| ------------- | ------------------------ |
| EditText | 可编辑的区域。 |
| Email | 电子邮件地址。 |
| HttpAnchor | 超链接，其src为http。 |
| HttpAnchorImg | 带有超链接的图片，其中超链接的src为http。 |
| Img | HTML::img标签。 |
| Map | 地理地址。 |
| Phone | 电话号码。 |
| Unknown | 未知内容。 |
## SslError9+枚举说明
onSslErrorEventReceive接口返回的SSL错误的具体原因。
| 名称 | 描述 |
| ------------ | ----------- |
| Invalid | 一般错误。 |
| HostMismatch | 主机名不匹配。 |
| DateInvalid | 证书日期无效。 |
| Untrusted | 证书颁发机构不受信任。 |
## ProtectedResourceType9+枚举说明
| 名称 | 描述 | 备注 |
| --------- | ------------- | -------------------------- |
| MidiSysex | MIDI SYSEX资源。 | 目前仅支持权限事件上报，MIDI设备的使用还未支持。 |
## WebDarkMode9+枚举说明
| 名称 | 描述 |
| ------- | ------------------------------------ |
| Off | Web深色模式关闭。 |
| On | Web深色模式开启。 |
| Auto | Web深色模式跟随系统。 |
## WebAsyncController
通过WebAsyncController可以控制Web组件具有异步回调通知的行为，一个WebAsyncController对象控制一个Web组件。
### 创建对象
```
webController: WebController = new WebController();
webAsyncController: WebAsyncController = new WebAsyncController(webController);
```
### storeWebArchive9+
storeWebArchive(baseName: string, autoName: boolean, callback: AsyncCallback): void
以回调方式异步保存当前页面。
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| -------- | ---------------------------------------- | ---- | ----------------------------------- |
| baseName | string | 是 | 文件存储路径，该值不能为空。
| autoName | boolean | 是 | 决定是否自动生成文件名。
如果为false，则将baseName作为文件存储路径。
如果为true，则假定baseName是一个目录，将根据当前页的Url自动生成文件名。
| callback | AsyncCallback | 是 | 返回文件存储路径，保持网页失败会返回null。 |
**示例：**
```ts
// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController()
build() {
Column() {
Button('saveWebArchive')
.onClick(() => {
let webAsyncController = new web_webview.WebAsyncController(this.controller)
webAsyncController.storeWebArchive("/data/storage/el2/base/", true, (filename) => {
if (filename != null) {
console.info(`save web archive success: ${filename}`)
}
})
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
### storeWebArchive9+
storeWebArchive(baseName: string, autoName: boolean): Promise
以Promise方式异步保存当前页面。
**参数：**
| 参数名 | 参数类型 | 必填 | 说明 |
| -------- | ---------------------------------------- | ---- | ----------------------------------- |
| baseName | string | 是 | 文件存储路径，该值不能为空。
| autoName | boolean | 是 | 决定是否自动生成文件名。
如果为false，则将baseName作为文件存储路径。
如果为true，则假定baseName是一个目录，将根据当前页的Url自动生成文件名。
**返回值：**
| 类型 | 说明 |
| --------------- | -------------------------------- |
| Promise | Promise实例，保存成功返回文件路径，保存失败返回null。 |
**示例：**
```ts
// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController();
build() {
Column() {
Button('saveWebArchive')
.onClick(() => {
let webAsyncController = new web_webview.WebAsyncController(this.controller);
webAsyncController.storeWebArchive("/data/storage/el2/base/", true)
.then(filename => {
if (filename != null) {
console.info(`save web archive success: ${filename}`)
}
})
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
## WebMessagePort9+
通过WebMessagePort可以进行消息的发送以及接收。
### close9+
close(): void
关闭该消息端口。
### postMessageEvent9+
postMessageEvent(message: WebMessageEvent): void
发送消息。完整示例代码参考[postMessage](#postmessage9)
**参数：**
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| ------- | ------------------------------------ | ---- | ---- | ------- |
| message | [WebMessageEvent](#webmessageevent9) | 是 | - | 要发送的消息。 |
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController()
ports: WebMessagePort[] = null
build() {
Column() {
Button('postMessageEvent')
.onClick(() => {
var msg = new WebMessageEvent()
msg.setData("post message from ets to html5")
this.ports[0].postMessageEvent(msg)
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
### onMessageEvent9+
onMessageEvent(callback: (result: string) => void): void
注册回调函数，接收HTML5侧发送过来的消息。完整示例代码参考[postMessage](#postmessage9)
**参数：**
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| -------- | -------- | ---- | ---- | ---------- |
| callback | function | 是 | - | 接收消息的回调函数。 |
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController()
ports: WebMessagePort[] = null
build() {
Column() {
Button('onMessageEvent')
.onClick(() => {
this.ports[0].onMessageEvent((result: string) => {
console.log("received message from html5, on message:" + result);
})
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
## WebMessageEvent9+
通过WebMessagePort对要发送的消息和端口进行封装。
### getData9+
getData(): string
获取当前对象中存放的消息。
**返回值：**
| 类型 | 说明 |
| ------ | -------------- |
| string | 当前该类型对象中存放的消息。 |
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
build() {
Column() {
Button('getPorts')
.onClick(() => {
var msgEvent = new WebMessageEvent();
msgEvent.setData("message event data")
var messageData = msgEvent.getData()
console.log("message is:" + messageData)
})
}
}
}
```
### setData9+
setData(data: string): void
设置当前对象中的消息。完整示例代码参考[postMessage](#postmessage9)
**参数：**
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| ---- | ------ | ---- | ---- | ------- |
| data | string | 是 | - | 要发送的消息。 |
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController()
ports: WebMessagePort[] = null
build() {
Column() {
Button('setData')
.onClick(() => {
var msg = new WebMessageEvent()
msg.setData("post message from ets to HTML5")
this.ports[0].postMessageEvent(msg)
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
### getPorts9+
getPorts(): Array\
获取当前对象中存放的消息端口。
**返回值：**
| 类型 | 说明 |
| ---------------------------------------- | ---------------- |
| Array\<[WebMessagePort](#webmessageport9)\> | 当前该类型对象中存放的消息端口。 |
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
ports: WebMessagePort[] = null
build() {
Column() {
Button('getPorts')
.onClick(() => {
var sendPortArray = new Array(this.ports[0])
var msgEvent = new WebMessageEvent()
msgEvent.setPorts(sendPortArray)
var getPorts = msgEvent.getPorts()
console.log("Ports is:" + getPorts)
})
}
}
}
```
### setPorts9+
setPorts(ports: Array\): void
设置当前对象中的消息端口。完整示例代码参考[postMessage](#postmessage9)
**参数：**
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| ----- | ---------------------------------------- | ---- | ---- | --------- |
| ports | Array\<[WebMessagePort](#webmessageport9)\> | 是 | - | 要发送的消息端口。 |
**示例：**
```ts
// xxx.ets
@Entry
@Component
struct WebComponent {
controller: WebController = new WebController()
ports: WebMessagePort[] = null
build() {
Column() {
Button('setPorts')
.onClick(() => {
var sendPortArray = new Array(this.ports[1])
var msgEvent = new WebMessageEvent()
msgEvent.setData("__init_ports__")
msgEvent.setPorts(sendPortArray)
this.controller.postMessage({message: msgEvent, uri: "*"})
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
## DataResubmissionHandler9+
通过DataResubmissionHandler可以重新提交表单数据或取消提交表单数据。
### resend9+
resend(): void
重新发送表单数据。
**示例：**
```ts
// 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 })
.onDataResubmitted((event) => {
console.log('onDataResubmitted')
event.handler.resend();
})
}
}
}
```
### cancel9+
cancel(): void
取消重新发送表单数据。
**示例：**
```ts
// 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 })
.onDataResubmitted((event) => {
console.log('onDataResubmitted')
event.handler.cancel();
})
}
}
}
```