Hello World
``` ## loadData loadData(data: string, mimeType: string, encoding: string, baseUrl?: string, historyUrl?: string): void 加载指定的数据。 baseUrl与historyUrl同时为空的情况下： encoding如果为非base64（包括空值），则假定数据对安全URL字符范围内的八位字节使用ASCII编码，对该范围外的八位字节使用URL的标准%xx十六进制编码。 data数据必须使用base64编码或将内容中的任何#字符编码为%23。否则#将被视为内容的结尾而剩余的文本将被用作文档片段标识符。 > 说明 > > * 若加载本地图片，可以给baseUrl或historyUrl任一参数赋值空格，详情请参考示例代码。 > > * 加载本地图片场景，baseUrl和historyUrl不能同时为空，否则图片无法成功加载。 > > * 若html中的富文本中带有注入#等特殊字符，建议将baseUrl和historyUrl两个参数的值设置为"空格"。 > > * 加载文字场景，需主动设置避免文本字体大小不一致。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** |参数名|类型|必填|说明| |:---------|:-----|:-|:----------------------------------------------------------------------------------------------------------------| |data|string|是|按照"base64"或者"URL"编码后的一段字符串。| |mimeType|string|是|媒体类型（MIME）。| |encoding|string|是|编码类型，具体为"base64"或者"URL"编码。| |baseUrl|string|否|指定的一个URL路径（"http"/"https"/"data"协议），并由Web组件赋值给window.origin。当加载大量html文件时，需设置为"data"。 传入undefined或null会抛出异常错误码401。| |historyUrl|string|否|用作历史记录所使用的URL。非空时，历史记录以此URL进行管理。当baseUrl为空时，此属性无效。 传入undefined或null会抛出异常错误码401。| **错误码：** 以下错误码的详细介绍请参见[Webview错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-webview)、[通用错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。 |错误码ID|错误信息| |:-------|:---------------------------------------------------------------------------------------------------------------------------------------------| |17100001|Init error. The WebviewController must be associated with a Web component.| |17100002|URL error. The webpage corresponding to the URL is invalid, or the URL length exceeds 2048. 适用版本：9-10| |401|Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed.| **示例：** baseUrl与historyUrl同时为空。 ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; import { BusinessError } from '@kit.BasicServicesKit'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Button('loadData') .onClick(() => { try { this.controller.loadData( "Source:source", "text/html", // UTF-8为charset。 "UTF-8" ); } catch (error) { console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); } }) Web({ src: 'www.example.com', controller: this.controller }) } } } ``` ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; import { BusinessError } from '@kit.BasicServicesKit'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Button('loadData') .onClick(() => { try { this.controller.loadData( // Coding tests通过base64编码后的字符串。 "Q29kaW5nIHRlc3Rz", "text/html", "base64" ); } catch (error) { console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); } }) Web({ src: 'www.example.com', controller: this.controller }) } } } ``` 指定baseUrl。 ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; import { BusinessError } from '@kit.BasicServicesKit'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Button('loadData') .onClick(() => { try { this.controller.loadData( "
", // 会尝试从"https://xxx.com/" + "aa/bb.jpg"加载该图片
"text/html",
"UTF-8",
"https://xxx.com/",
"about:blank"
);
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
加载本地资源。
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
updateContent: string = '
", // 尝试从"file:///xxx/" + "bb.jpg"加载该图片。
"text/html",
"UTF-8",
// 加载本地应用沙箱内的图片路径，请将路径改为实际使用的沙箱路径。
"file:///data/storage/el2/base/haps/entry/files/data/.cache_dir/",
""
);
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Web({ src: 'www.example.com', controller: this.controller })
.fileAccess(true) // 为了加载应用沙箱内的图片，需要启用文件访问功能。
}
}
}
```
## accessForward
accessForward(): boolean
当前页面是否可前进，即当前页面是否有前进历史记录。
可以结合使用[getBackForwardEntries](#getbackforwardentries)来获取当前WebView的历史信息列表，以及使用[accessStep](#accessstep)来判断是否可以按照给定的步数前进或后退。
**系统能力：** SystemCapability.Web.Webview.Core
**返回值：**
|类型|说明|
|:------|:--------------------|
|boolean|可以前进返回true，否则返回false。|
**错误码：**
以下错误码的详细介绍请参见[Webview错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-webview)。
|错误码ID|错误信息|
|:-------|:-------------------------------------------------------------------------|
|17100001|Init error. The WebviewController must be associated with a Web component.|
**示例：**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
build() {
Column() {
Button('accessForward')
.onClick(() => {
try {
let result = this.controller.accessForward();
console.info('result:' + result);
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
## forward
forward(): void
按照历史栈，前进一个页面。一般结合[accessForward](#accessforward)一起使用。
**系统能力：** SystemCapability.Web.Webview.Core
**错误码：**
以下错误码的详细介绍请参见[Webview错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-webview)。
|错误码ID|错误信息|
|:-------|:-------------------------------------------------------------------------|
|17100001|Init error. The WebviewController must be associated with a Web component.|
**示例：**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
build() {
Column() {
Button('forward')
.onClick(() => {
try {
this.controller.forward();
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
## accessBackward
accessBackward(): boolean
当前页面是否可后退，即当前页面是否有返回历史记录。
可以结合使用[getBackForwardEntries](#getbackforwardentries)来获取当前WebView的历史信息列表，以及使用[accessStep](#accessstep)来判断是否可以按照给定的步数前进或后退。
> 说明
>
> 在Web组件首次加载过程中调用[setCustomUserAgent](#setcustomuseragent10)，可能会导致在当前存在多个历史节点的情况下，获取的accessBackward实际为false，即没有后退节点。建议先调用setCustomUserAgent方法设置UserAgent，再通过loadUrl加载具体页面。
>
> 该现象是由于在Web组件首次加载时，调用[setCustomUserAgent](#setcustomuseragent10)会导致组件重新加载并保持初始历史节点的状态。随后新增的节点将替换初始历史节点，不会生成新的历史节点，导致accessBackward为false。
**系统能力：** SystemCapability.Web.Webview.Core
**返回值：**
|类型|说明|
|:------|:------------------------|
|boolean|当前页面可以后退返回true,否则返回false。|
**错误码：**
以下错误码的详细介绍请参见[Webview错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-webview)。
|错误码ID|错误信息|
|:-------|:-------------------------------------------------------------------------|
|17100001|Init error. The WebviewController must be associated with a Web component.|
**示例：**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
build() {
Column() {
Button('accessBackward')
.onClick(() => {
try {
let result = this.controller.accessBackward();
console.info('result:' + result);
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
## backward
backward(): void
按照历史栈，后退一个页面。一般结合[accessBackward](#accessbackward)一起使用。
**系统能力：** SystemCapability.Web.Webview.Core
**错误码：**
以下错误码的详细介绍请参见[Webview错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-webview)。
|错误码ID|错误信息|
|:-------|:-------------------------------------------------------------------------|
|17100001|Init error. The WebviewController must be associated with a Web component.|
**示例：**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
build() {
Column() {
Button('backward')
.onClick(() => {
try {
this.controller.backward();
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
## onActive
onActive(): void
调用此接口通知Web组件进入前台激活状态。
激活状态是应用与用户互动的状态。应用会保持这种状态，直到发生某些事件（例如收到来电或设备屏幕关闭）时将焦点从应用移开。
若页面此前处于未激活状态，H5页面中通过document.addEventListener('visibilitychange',...)注册的事件监听器将被触发，document.visibilityState 从"hidden"变为"visible"。
**系统能力：** SystemCapability.Web.Webview.Core
**错误码：**
以下错误码的详细介绍请参见[Webview错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-webview)。
|错误码ID|错误信息|
|:-------|:-------------------------------------------------------------------------|
|17100001|Init error. The WebviewController must be associated with a Web component.|
**示例：**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
build() {
Column() {
Button('onActive')
.onClick(() => {
try {
this.controller.onActive();
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
## onInactive
onInactive(): void
调用此接口通知Web组件进入未激活状态。开发者可以在此回调中实现应用失去焦点时应表现的恰当行为。
此状态下会尽可能的暂停任何可以安全暂停的内容，例如动画和地理位置。但不会暂停JavaScript，要全局暂停JavaScript，请使用[pauseAllTimers](#pausealltimers12)。要重新激活Web组件，请调用[onActive](#onactive)。
**系统能力：** SystemCapability.Web.Webview.Core
**错误码：**
以下错误码的详细介绍请参见[Webview错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-webview)。
|错误码ID|错误信息|
|:-------|:-------------------------------------------------------------------------|
|17100001|Init error. The WebviewController must be associated with a Web component.|
**示例：**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
build() {
Column() {
Button('onInactive')
.onClick(() => {
try {
this.controller.onInactive();
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
## refresh
refresh(): void
调用此接口通知Web组件刷新网页。
**系统能力：** SystemCapability.Web.Webview.Core
**错误码：**
以下错误码的详细介绍请参见[Webview错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-webview)。
|错误码ID|错误信息|
|:-------|:-------------------------------------------------------------------------|
|17100001|Init error. The WebviewController must be associated with a Web component.|
**示例：**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
build() {
Column() {
Button('refresh')
.onClick(() => {
try {
this.controller.refresh();
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
## refresh^24+^
refresh(ignoreCache: boolean): void
通知Web组件刷新网页，可以选择是否忽略缓存刷新。
**系统能力：** SystemCapability.Web.Webview.Core
**参数：**
|参数名|类型|必填|说明|
|:----------|:------|:-|:----------------------------------------------------------------------------------|
|ignoreCache|boolean|是|Web组件刷新网页，选择是否忽略缓存刷新。 true表示忽略缓存刷新，false表示不忽略缓存刷新。 **说明：** 传入undefined或null时为false。|
**错误码：**
以下错误码的详细介绍请参见[Webview错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-webview)。
|错误码ID|错误信息|
|:-------|:-------------------------------------------------------------------------|
|17100001|Init error. The WebviewController must be associated with a Web component.|
**示例：**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
build() {
Column() {
Button('refresh')
.onClick(() => {
try {
this.controller.refresh(true);
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
## accessStep
accessStep(step: number): boolean
当前页面是否可前进或者后退给定的step步。
**系统能力：** SystemCapability.Web.Webview.Core
**参数：**
|参数名|类型|必填|说明|
|:---|:-----|:-|:--------------------|
|step|number|是|要跳转的步数，正数代表前进，负数代表后退。|
**返回值：**
|类型|说明|
|:------|:---------------------------------------------|
|boolean|页面是否前进或后退。 返回true表示可以前进或者后退，返回false表示不可以前进或后退。|
**错误码：**
以下错误码的详细介绍请参见[Webview错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-webview)、[通用错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。
|错误码ID|错误信息|
|:-------|:---------------------------------------------------------------------------------------------------------------------------------------------|
|17100001|Init error. The WebviewController must be associated with a Web component.|
|401|Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed.|
**示例：**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
@State steps: number = 2;
build() {
Column() {
Button('accessStep')
.onClick(() => {
try {
let result = this.controller.accessStep(this.steps);
console.info('result:' + result);
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
## clearHistory
clearHistory(): void
删除所有前进后退记录，不建议在onErrorReceive与onPageBegin中调用clearHistory，会造成异常退出。
**系统能力：** SystemCapability.Web.Webview.Core
**错误码：**
以下错误码的详细介绍请参见[Webview错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-webview)。
|错误码ID|错误信息|
|:-------|:-------------------------------------------------------------------------|
|17100001|Init error. The WebviewController must be associated with a Web component.|
**示例：**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
build() {
Column() {
Button('clearHistory')
.onClick(() => {
try {
this.controller.clearHistory();
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
## registerJavaScriptProxy
registerJavaScriptProxy(jsObject: object, name: string, methodList: Arrayrun JavaScript Ext demo
``` ## runJavaScriptExt^10+^ runJavaScriptExt(script: string | ArrayBuffer): Promiserun JavaScript Ext demo
``` ## deleteJavaScriptRegister deleteJavaScriptRegister(name: string): void 删除通过[registerJavaScriptProxy](#registerjavascriptproxy)或者[javaScriptProxy](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-basic-components-web-attributes#javascriptproxy)注册到window上的指定name的应用侧JavaScript对象。删除操作在页面下次（重新）加载后生效。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** |参数名|类型|必填|说明| |:---|:-----|:-|:----------------------------------------------| |name|string|是|注册对象的名称，可在网页侧JavaScript中通过此名称调用应用侧JavaScript对象。| **错误码：** 以下错误码的详细介绍请参见[Webview错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-webview)、[通用错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。 |错误码ID|错误信息| |:-------|:---------------------------------------------------------------------------------------------------------------------------------------------| |17100001|Init error. The WebviewController must be associated with a Web component.| |17100008|Failed to delete JavaScriptProxy because it does not exist.| |401|Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed.| **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; import { BusinessError } from '@kit.BasicServicesKit'; class TestObj { constructor() { } test(): string { return "ArkUI Web Component"; } toString(): void { console.info('Web Component toString'); } } @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); @State testObjtest: TestObj = new TestObj(); @State name: string = 'objName'; build() { Column() { Button('refresh') .onClick(() => { try { this.controller.refresh(); } catch (error) { console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); } }) Button('Register JavaScript To Window') .onClick(() => { try { this.controller.registerJavaScriptProxy(this.testObjtest, this.name, ["test", "toString"]); } catch (error) { console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); } }) Button('deleteJavaScriptRegister') .onClick(() => { try { this.controller.deleteJavaScriptRegister(this.name); } catch (error) { console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); } }) Web({ src: $rawfile('index.html'), controller: this.controller }) .javaScriptAccess(true) } } } ``` 加载的html文件。 ```html ``` ## zoom zoom(factor: number): void 调整当前网页的缩放比例，[zoomAccess](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-basic-components-web-attributes#zoomaccess)需为true。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** |参数名|类型|必填|说明| |:-----|:-----|:-|:----------------------------------------------------------------------------| |factor|number|是|基于当前网页所需调整的相对缩放比例，入参要求大于0，当入参为1时为默认加载网页的缩放比例，入参小于1为缩小，入参大于1为放大。 取值范围：(0，100]。| **错误码：** 以下错误码的详细介绍请参见[Webview错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-webview)、[通用错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。 |错误码ID|错误信息| |:-------|:---------------------------------------------------------------------------------------------------------------------------------------------| |17100001|Init error. The WebviewController must be associated with a Web component.| |17100004|Function not enabled.| |401|Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed.| **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; import { BusinessError } from '@kit.BasicServicesKit'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); @State factor: number = 2; build() { Column() { Button('zoom') .onClick(() => { try { this.controller.zoom(this.factor); } catch (error) { console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); } }) Web({ src: 'www.example.com', controller: this.controller }) .zoomAccess(true) } } } ``` ## searchAllAsync searchAllAsync(searchString: string): void 异步查找网页中所有匹配关键字'searchString'的内容并高亮，结果通过[onSearchResultReceive](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-basic-components-web-events#onsearchresultreceive9)异步返回。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** |参数名|类型|必填|说明| |:-----------|:-----|:-|:------| |searchString|string|是|查找的关键字。| **错误码：** 以下错误码的详细介绍请参见[Webview错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-webview)、[通用错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。 |错误码ID|错误信息| |:-------|:---------------------------------------------------------------------------------------------------------------------------------------------| |17100001|Init error. The WebviewController must be associated with a Web component.| |401|Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed.| **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; import { BusinessError } from '@kit.BasicServicesKit'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); @State searchString: string = "Hello World"; build() { Column() { Button('searchString') .onClick(() => { try { this.controller.searchAllAsync(this.searchString); } catch (error) { console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); } }) Web({ src: $rawfile('index.html'), controller: this.controller }) .onSearchResultReceive(ret => { if (ret) { console.info("on search result receive:" + "[cur]" + ret.activeMatchOrdinal + "[total]" + ret.numberOfMatches + "[isDone]" + ret.isDoneCounting); } }) } } } ``` 加载的html文件。 ```htmlHello World Highlight Hello World
``` ## clearMatches clearMatches(): void 清除所有通过[searchAllAsync](#searchallasync)匹配到的高亮字符查找结果。 **系统能力：** SystemCapability.Web.Webview.Core **错误码：** 以下错误码的详细介绍请参见[Webview错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-webview)。 |错误码ID|错误信息| |:-------|:-------------------------------------------------------------------------| |17100001|Init error. The WebviewController must be associated with a Web component.| **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; import { BusinessError } from '@kit.BasicServicesKit'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Button('clearMatches') .onClick(() => { try { this.controller.clearMatches(); } catch (error) { console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); } }) Web({ src: $rawfile('index.html'), controller: this.controller }) } } } ``` 加载的html文件，请参考[searchAllAsync](#searchallasync)接口下加载的html文件。 ## searchNext searchNext(forward: boolean): void 滚动到下一个匹配的查找结果并高亮。 **系统能力：** SystemCapability.Web.Webview.Core **参数：** |参数名|类型|必填|说明| |:------|:------|:-|:----------------------------------------| |forward|boolean|是|从前向后或者逆向查找方式。 true表示从前向后查找，false表示从后向前查找。| **错误码：** 以下错误码的详细介绍请参见[Webview错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-webview)、[通用错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。 |错误码ID|错误信息| |:-------|:---------------------------------------------------------------------------------------------------------------------------------------------| |17100001|Init error. The WebviewController must be associated with a Web component.| |401|Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed.| **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; import { BusinessError } from '@kit.BasicServicesKit'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Button('searchNext') .onClick(() => { try { this.controller.searchNext(true); } catch (error) { console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); } }) Web({ src: $rawfile('index.html'), controller: this.controller }) } } } ``` 加载的html文件，请参考[searchAllAsync](#searchallasync)接口下加载的html文件。 ## clearSslCache clearSslCache(): void 清除Web组件记录的SSL证书错误事件对应的用户操作行为。 **系统能力：** SystemCapability.Web.Webview.Core **错误码：** 以下错误码的详细介绍请参见[Webview错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-webview)。 |错误码ID|错误信息| |:-------|:-------------------------------------------------------------------------| |17100001|Init error. The WebviewController must be associated with a Web component.| **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; import { BusinessError } from '@kit.BasicServicesKit'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Button('clearSslCache') .onClick(() => { try { this.controller.clearSslCache(); } catch (error) { console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); } }) Web({ src: 'www.example.com', controller: this.controller }) } } } ``` ## clearClientAuthenticationCache clearClientAuthenticationCache(): void 清除Web组件记录的客户端证书请求事件对应的用户操作行为。 **系统能力：** SystemCapability.Web.Webview.Core **错误码：** 以下错误码的详细介绍请参见[Webview错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-webview)。 |错误码ID|错误信息| |:-------|:-------------------------------------------------------------------------| |17100001|Init error. The WebviewController must be associated with a Web component.| **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; import { BusinessError } from '@kit.BasicServicesKit'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Button('clearClientAuthenticationCache') .onClick(() => { try { this.controller.clearClientAuthenticationCache(); } catch (error) { console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); } }) Web({ src: 'www.example.com', controller: this.controller }) } } } ``` ## createWebMessagePorts createWebMessagePorts(isExtentionType?: boolean): ArrayWebView Message Port Demo
display received message send from ets
``` ```js // xxx.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:'; var result = event.data; if (typeof(result) == "string") { console.info("received string message from html5, string is:" + result); msg = msg + result; } else if (typeof(result) == "object") { if (result instanceof ArrayBuffer) { console.info("received arraybuffer from html5, length is:" + result.byteLength); msg = msg + "length is " + result.byteLength; } else { console.info("not support"); } } else { console.info("not support"); } output.innerHTML = msg; } } } }) // 3. 使用h5Port往ets侧发送消息. function PostMsgToEts(data) { if (h5Port) { h5Port.postMessage(data); } else { console.error("h5Port is null, Please initialize first"); } } ``` ## requestFocus requestFocus(): void 使指定组件获取焦点。 **系统能力：** SystemCapability.Web.Webview.Core **错误码：** 以下错误码的详细介绍请参见[Webview错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-webview)。 |错误码ID|错误信息| |:-------|:-------------------------------------------------------------------------| |17100001|Init error. The WebviewController must be associated with a Web component.| **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; import { BusinessError } from '@kit.BasicServicesKit'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Button('requestFocus') .onClick(() => { try { this.controller.requestFocus(); } catch (error) { console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); } }); Web({ src: 'www.example.com', controller: this.controller }) } } } ``` ## zoomIn zoomIn(): void 调用此接口将当前网页进行放大，比例为25%。 **系统能力：** SystemCapability.Web.Webview.Core **错误码：** 以下错误码的详细介绍请参见[Webview错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-webview)。 |错误码ID|错误信息| |:-------|:-------------------------------------------------------------------------| |17100001|Init error. The WebviewController must be associated with a Web component.| |17100004|Function not enabled.| **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; import { BusinessError } from '@kit.BasicServicesKit'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Button('zoomIn') .onClick(() => { try { this.controller.zoomIn(); } catch (error) { console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); } }) Web({ src: 'www.example.com', controller: this.controller }) } } } ``` ## zoomOut zoomOut(): void 调用此接口将当前网页进行缩小，比例为20%。 **系统能力：** SystemCapability.Web.Webview.Core **错误码：** 以下错误码的详细介绍请参见[Webview错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-webview)。 |错误码ID|错误信息| |:-------|:-------------------------------------------------------------------------| |17100001|Init error. The WebviewController must be associated with a Web component.| |17100004|Function not enabled.| **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; import { BusinessError } from '@kit.BasicServicesKit'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Button('zoomOut') .onClick(() => { try { this.controller.zoomOut(); } catch (error) { console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); } }) Web({ src: 'www.example.com', controller: this.controller }) } } } ``` ## getWebId getWebId(): number 获取Web组件的索引值，用于多个Web组件的管理。 **系统能力：** SystemCapability.Web.Webview.Core **返回值：** |类型|说明| |:-----|:---------| |number|Web组件的索引值。| **错误码：** 以下错误码的详细介绍请参见[Webview错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-webview)。 |错误码ID|错误信息| |:-------|:-------------------------------------------------------------------------| |17100001|Init error. The WebviewController must be associated with a Web component.| **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; import { BusinessError } from '@kit.BasicServicesKit'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Button('getWebId') .onClick(() => { try { let id = this.controller.getWebId(); console.info("id: " + id); } catch (error) { console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); } }) Web({ src: 'www.example.com', controller: this.controller }) } } } ``` ## getUserAgent getUserAgent(): string 获取当前默认用户代理。 默认User-Agent定义与使用场景请参考[User-Agent开发指导](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/web-default-useragent) **系统能力：** SystemCapability.Web.Webview.Core **返回值：** |类型|说明| |:-----|:------| |string|默认用户代理。| **错误码：** 以下错误码的详细介绍请参见[Webview错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-webview)。 |错误码ID|错误信息| |:-------|:-------------------------------------------------------------------------| |17100001|Init error. The WebviewController must be associated with a Web component.| **示例：** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; import { BusinessError } from '@kit.BasicServicesKit'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Button('getUserAgent') .onClick(() => { try { let userAgent = this.controller.getUserAgent(); console.info("userAgent: " + userAgent); } catch (error) { console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); } }) Web({ src: 'www.example.com', controller: this.controller }) } } } ``` 支持开发者基于默认的User-Agent去定制User-Agent。 ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; import { BusinessError } from '@kit.BasicServicesKit'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); @State ua: string = ""; aboutToAppear(): void { webview.once('webInited', () => { try { // 应用侧用法示例，定制User-Agent。 this.ua = this.controller.getUserAgent() + 'xxx'; this.controller.setCustomUserAgent(this.ua); } catch (error) { console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); } }) } build() { Column() { Web({ src: 'www.example.com', controller: this.controller }) } } } ``` ## getTitle getTitle(): string 获取当前网页的标题。 **系统能力：** SystemCapability.Web.Webview.Core **返回值：** |类型|说明| |:-----|:-------| |string|当前网页的标题。| **错误码：** 以下错误码的详细介绍请参见[Webview错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-webview)。 |错误码ID|错误信息| |:-------|:-------------------------------------------------------------------------| |17100001|Init error. The WebviewController must be associated with a Web component.| **示例:** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; import { BusinessError } from '@kit.BasicServicesKit'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Button('getTitle') .onClick(() => { try { let title = this.controller.getTitle(); console.info("title: " + title); } catch (error) { console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); } }) Web({ src: 'www.example.com', controller: this.controller }) } } } ``` ## getPageHeight getPageHeight(): number 获取当前网页的页面高度。具体使用详情请参考[获取网页内容高度](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/web-getpage-height)。 **系统能力：** SystemCapability.Web.Webview.Core **返回值：** |类型|说明| |:-----|:---------------| |number|当前网页的页面高度。单位：vp。| **错误码：** 以下错误码的详细介绍请参见[Webview错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-webview)。 |错误码ID|错误信息| |:-------|:-------------------------------------------------------------------------| |17100001|Init error. The WebviewController must be associated with a Web component.| **示例:** ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; import { BusinessError } from '@kit.BasicServicesKit'; @Entry @Component struct WebComponent { controller: webview.WebviewController = new webview.WebviewController(); build() { Column() { Button('getPageHeight') .onClick(() => { try { let pageHeight = this.controller.getPageHeight(); console.info("pageHeight : " + pageHeight); } catch (error) { console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); } }) Web({ src: 'www.example.com', controller: this.controller }) } } } ``` ## storeWebArchive storeWebArchive(baseName: string, autoName: boolean, callback: AsyncCallbackonline 属性
``` ## hasImage hasImage(callback: AsyncCallbackwebArea
webArea
webArea
webArea
webArea
webArea
webArea
```
## pageDown
pageDown(bottom: boolean): void
将Webview的内容向下滚动半个视框大小或者跳转到页面最底部，通过bottom入参控制。
**系统能力：** SystemCapability.Web.Webview.Core
**参数：**
|参数名|类型|必填|说明|
|:-----|:------|:-|:--------------------------------------------------|
|bottom|boolean|是|是否跳转到页面最底部。 false时表示将页面内容向下滚动半个视框大小，true表示跳转到页面最底部。|
**错误码：**
以下错误码的详细介绍请参见[Webview错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-webview)、[通用错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。
|错误码ID|错误信息|
|:-------|:------------------------------------------------------------------------------------------------------------|
|17100001|Init error. The WebviewController must be associated with a Web component.|
|401|Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.|
**示例：**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
build() {
Column() {
Button('pageDown')
.onClick(() => {
try {
this.controller.pageDown(false);
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Web({ src: $rawfile("index.html"), controller: this.controller })
}
}
}
```
加载的html文件。
```html
webArea
webArea
webArea
webArea
webArea
webArea
webArea
```
## getBackForwardEntries
getBackForwardEntries(): BackForwardList
获取当前WebView的历史信息列表。
> 说明
>
> [onLoadIntercept](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-basic-components-web-events#onloadintercept10)在加载开始的时候触发，该时刻还未生成历史节点，所以在onLoadIntercept中调用getBackForwardEntries拿到的历史栈不包括当前正在加载中的跳转。
**系统能力：** SystemCapability.Web.Webview.Core
**返回值：**
|类型|说明|
|:----------------------------------------------------------------------------------------------------------------------|:----------------|
|[BackForwardList](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-webview-backforwardlist)|当前WebView的历史信息列表。|
**错误码：**
以下错误码的详细介绍请参见[Webview错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-webview)。
|错误码ID|错误信息|
|:-------|:-------------------------------------------------------------------------|
|17100001|Init error. The WebviewController must be associated with a Web component.|
**示例：**
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
build() {
Column() {
Button('getBackForwardEntries')
.onClick(() => {
try {
let list = this.controller.getBackForwardEntries()
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
## serializeWebState
serializeWebState(): Uint8Array
将当前WebView的页面状态历史记录信息序列化。
**系统能力：** SystemCapability.Web.Webview.Core
**返回值：**
|类型|说明|
|:---------|:-------------------------|
|Uint8Array|当前WebView的页面状态历史记录序列化后的数据。|
**错误码：**
以下错误码的详细介绍请参见[Webview错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-webview)。
|错误码ID|错误信息|
|:-------|:-------------------------------------------------------------------------|
|17100001|Init error. The WebviewController must be associated with a Web component.|
**示例：**
1. 对文件的操作需要导入文件管理模块，详情请参考[文件管理](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-file-fs)。
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
import { fileIo } from '@kit.CoreFileKit';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
build() {
Column() {
Button('serializeWebState')
.onClick(() => {
try {
let state = this.controller.serializeWebState();
let path:string | undefined = AppStorage.get("cacheDir");
if (path) {
path += '/WebState';
// 以同步方法打开文件。
let file = fileIo.openSync(path, fileIo.OpenMode.READ_WRITE | fileIo.OpenMode.CREATE);
fileIo.writeSync(file.fd, state.buffer);
fileIo.closeSync(file.fd);
}
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
2. 修改EntryAbility.ets。
获取应用缓存文件路径。
```ts
// xxx.ets
import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
export default class EntryAbility extends UIAbility {
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
// 通过在AppStorage对象上绑定cacheDir，可以实现UIAbility组件与Page之间的数据同步。
AppStorage.setOrCreate("cacheDir", this.context.cacheDir);
}
}
```
## restoreWebState
restoreWebState(state: Uint8Array): void
当前WebView从序列化数据中恢复页面状态历史记录。
如果state过大，可能会导致异常。建议state大于512k时，放弃恢复页面状态历史记录。
**系统能力：** SystemCapability.Web.Webview.Core
**参数：**
|参数名|类型|必填|说明|
|:----|:---------|:-|:-------------|
|state|Uint8Array|是|页面状态历史记录序列化数据。|
**错误码：**
以下错误码的详细介绍请参见[Webview错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-webview)、[通用错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。
|错误码ID|错误信息|
|:-------|:---------------------------------------------------------------------------------------------------------------------------------------------|
|17100001|Init error. The WebviewController must be associated with a Web component.|
|401|Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed.|
**示例：**
1. 对文件的操作需要导入文件管理模块，详情请参考[文件管理](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-file-fs)。
```ts
// xxx.ets
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
import { fileIo } from '@kit.CoreFileKit';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
build() {
Column() {
Button('RestoreWebState')
.onClick(() => {
try {
let path: string | undefined = AppStorage.get("cacheDir");
if (path) {
path += '/WebState';
// 以同步方法打开文件。
let file = fileIo.openSync(path, fileIo.OpenMode.READ_WRITE);
let stat = fileIo.statSync(path);
let size = stat.size;
let buf = new ArrayBuffer(size);
fileIo.read(file.fd, buf, (err, readLen) => {
if (err) {
console.error("console error with error message: " + err.message + ", error code: " + err.code);
} else {
console.info("read file data succeed");
this.controller.restoreWebState(new Uint8Array(buf.slice(0, readLen)));
fileIo.closeSync(file);
}
});
}
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Web({ src: 'www.example.com', controller: this.controller })
}
}
}
```
2. 修改EntryAbility.ets。
获取应用缓存文件路径。
```ts
// xxx.ets
import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
export default class EntryAbility extends UIAbility {
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
// 通过在AppStorage对象上绑定cacheDir，可以实现UIAbility组件与Page之间的数据同步。
AppStorage.setOrCreate("cacheDir", this.context.cacheDir);
}
}
```
## customizeSchemes
static customizeSchemes(schemes: Array