From e4de7b63b073dd793533f9b018d8075f792179f3 Mon Sep 17 00:00:00 2001 From: "ester.zhou" Date: Tue, 21 Feb 2023 15:16:06 +0800 Subject: [PATCH] Update docs (14095) Signed-off-by: ester.zhou --- .../reference/apis/js-apis-webview.md | 223 +-- .../arkui-ts/ts-basic-components-web.md | 1302 +---------------- .../OpenHarmony_3.2.10.7/changelog-web.md | 467 ++++++ .../OpenHarmony_4.0.3.2/changelog-web.md | 467 ++++++ 4 files changed, 1062 insertions(+), 1397 deletions(-) create mode 100644 en/release-notes/changelogs/OpenHarmony_3.2.10.7/changelog-web.md create mode 100644 en/release-notes/changelogs/OpenHarmony_4.0.3.2/changelog-web.md diff --git a/en/application-dev/reference/apis/js-apis-webview.md b/en/application-dev/reference/apis/js-apis-webview.md index 08c8413e61..13e7a03a32 100644 --- a/en/application-dev/reference/apis/js-apis-webview.md +++ b/en/application-dev/reference/apis/js-apis-webview.md @@ -278,6 +278,8 @@ Sets whether to enable web debugging. | ------------------ | ------- | ---- | ------------- | | webDebuggingAccess | boolean | Yes | Whether to enable web debugging.| +**Example** + ```ts // xxx.ets import web_webview from '@ohos.web.webview'; @@ -305,7 +307,7 @@ struct WebComponent { ### loadUrl -loadUrl(url: string | Resource, headers?: Array\): void +loadUrl(url: string | Resource, headers?: Array\): void Loads a specified URL. @@ -316,7 +318,7 @@ Loads a specified URL. | Name | Type | Mandatory| Description | | ------- | ---------------- | ---- | :-------------------- | | url | string \| Resource | Yes | URL to load. | -| headers | Array\<[HeaderV9](#headerv9)> | No | Additional HTTP request header of the URL.| +| headers | Array\<[WebHeader](#webheader)> | No | Additional HTTP request header of the URL.| **Error codes** @@ -344,6 +346,7 @@ struct WebComponent { Button('loadUrl') .onClick(() => { try { + // The URL to be loaded is of the string type. this.controller.loadUrl('www.example.com'); } catch (error) { console.error(`ErrorCode: ${error.code}, Message: ${error.message}`); @@ -355,6 +358,69 @@ struct WebComponent { } ``` +```ts +// xxx.ets +import web_webview from '@ohos.web.webview' + +@Entry +@Component +struct WebComponent { + controller: web_webview.WebviewController = new web_webview.WebviewController(); + + build() { + Column() { + Button('loadUrl') + .onClick(() => { + try { + // The headers parameter is carried. + this.controller.loadUrl('www.example.com', [{headerKey: "headerKey", headerValue: "headerValue"}]); + } catch (error) { + console.error(`ErrorCode: ${error.code}, Message: ${error.message}`); + } + }) + Web({ src: 'www.example.com', controller: this.controller }) + .webDebuggingAccess(true) + } + } +} +``` + +```ts +// xxx.ets +import web_webview from '@ohos.web.webview' + +@Entry +@Component +struct WebComponent { + controller: web_webview.WebviewController = new web_webview.WebviewController(); + + build() { + Column() { + Button('loadUrl') + .onClick(() => { + try { + // The URL to be loaded is of the Resource type. + this.controller.loadUrl($rawfile('xxx.html')); + } catch (error) { + console.error(`ErrorCode: ${error.code}, Message: ${error.message}`); + } + }) + Web({ src: 'www.example.com', controller: this.controller }) + } + } +} +``` + +```html + + + + +

Hello World

+ + +``` + ### loadData loadData(data: string, mimeType: string, encoding: string, baseUrl?: string, historyUrl?: string): void @@ -829,7 +895,7 @@ struct WebComponent { ### getHitTest -getHitTest(): HitTestTypeV9 +getHitTest(): WebHitTestType Obtains the element type of the area being clicked. @@ -839,7 +905,7 @@ Obtains the element type of the area being clicked. | Type | Description | | ------------------------------------------------------------ | ---------------------- | -| [HitTestTypeV9](#hittesttypev9)| Element type of the area being clicked.| +| [WebHitTestType](#webhittesttype)| Element type of the area being clicked.| **Error codes** @@ -1026,7 +1092,7 @@ Executes a JavaScript script. This API uses a promise to return the script execu | Type | Description | | --------------- | --------------------------------------------------- | -| Promise\ | Callback used to return the result. Returns **null** if the JavaScript script fails to be executed| +| Promise\ | Promise used to return the result. Returns **null** if the JavaScript script fails to be executed| **Error codes** @@ -1512,7 +1578,7 @@ struct WebComponent { this.ports = this.controller.createWebMessagePorts(); // 2. Register a callback on a message port (for example, port 1) on the application side. this.ports[1].onMessageEvent((result: web_webview.WebMessage) => { - var msg = 'Got msg from HTML:'; + let msg = 'Got msg from HTML:'; if (typeof(result) == "string") { console.log("received string message from html5, string is:" + result); msg = msg + result; @@ -1540,7 +1606,7 @@ struct WebComponent { .onClick(() => { try { if (this.ports && this.ports[1]) { - this.ports[1].postMessageEvent("post message from ets to HTML"); + this.ports[1].postMessageEvent("this.sendFromEts"); } else { console.error(`ports is null, Please initialize first`); } @@ -3579,7 +3645,7 @@ Deletes all data in the specified origin. | Name| Type | Mandatory| Description | | ------ | ------ | ---- | ------------------------ | -| origin | string | Yes | Index of the origin.| +| origin | string | Yes | Index of the origin, which is obtained through [getOrigins](#getorigins).| **Error codes** @@ -4140,7 +4206,7 @@ Checks whether any saved HTTP authentication credentials exist. This API returns | Type | Description | | ------- | ------------------------------------------------------------ | -| boolean | Whether any saved HTTP authentication credentials exist. Returns **true** if any saved HTTP authentication credentials exist exists; returns **false** otherwise.| +| boolean | Whether any saved HTTP authentication credentials exist. Returns **true** if any saved HTTP authentication credentials exist; returns **false** otherwise. | **Example** @@ -4204,133 +4270,6 @@ struct WebComponent { } ``` -## WebAsyncController - -Implements a **WebAsyncController** object, which can be used to control the behavior of a **\** component with asynchronous callbacks. A **WebAsyncController **object controls one **\** component. - -### Creating an Object - - ```ts - // xxx.ets - import web_webview from '@ohos.web.webview' - - @Entry - @Component - struct WebComponent { - controller: WebController = new WebController(); - webAsyncController: web_webview.WebAsyncController = new web_webview.WebAsyncController(this.controller) - build() { - Column() { - Web({ src: 'www.example.com', controller: this.controller }) - } - } - } - ``` - -### constructor9+ - -constructor(controller: WebController) - -Implements a **WebAsyncController** by binding it with a [WebController](../arkui-ts/ts-basic-components-web.md#webcontroller) object. - -**System capability**: SystemCapability.Web.Webview.Core - -**Parameters** - -| Name| Type| Mandatory| Description| -| ----- | ---- | ---- | --- | -| controller | [WebController](../arkui-ts/ts-basic-components-web.md#webcontroller) | Yes| **WebviewController** to bind.| - -### storeWebArchive9+ - -storeWebArchive(baseName: string, autoName: boolean, callback: AsyncCallback\): void - -Stores this web page. This API uses an asynchronous callback to return the result. - -**System capability**: SystemCapability.Web.Webview.Core - -**Parameters** - -| Name | Type | Mandatory | Description | -| -------- | ---------------------------------------- | ---- | ----------------------------------- | -| baseName | string | Yes| Save path. The value cannot be null. | -| autoName | boolean | Yes| Whether to automatically generate a file name.
The value **false** means not to automatically generate a file name.
The value **true** means to automatically generate a file name based on the URL of current page and the **baseName** value. In this case, **baseName** is regarded as a directory. | -| callback | AsyncCallback\ | Yes | Callback used to return the save path if the operation is successful and null otherwise.| - -**Example** - - ```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\ - -Stores this web page. This API uses a promise to return the result. - -**System capability**: SystemCapability.Web.Webview.Core - -**Parameters** - -| Name | Type | Mandatory | Description | -| -------- | ---------------------------------------- | ---- | ----------------------------------- | -| baseName | string | Yes| Save path. The value cannot be null. | -| autoName | boolean | Yes| Whether to automatically generate a file name.
The value **false** means not to automatically generate a file name.
The value **true** means to automatically generate a file name based on the URL of current page and the **baseName** value. In this case, **baseName** is regarded as a directory. | - -**Return value** - -| Type | Description | -| ---------------- | ------------------------------------------------------------ | -| Promise\ | Promise used to return the save path if the operation is successful and null otherwise. | - -**Example** - - ```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 }) - } - } - } - ``` - ## GeolocationPermissions Implements a **GeolocationPermissions** object. @@ -4686,7 +4625,7 @@ struct WebComponent { } } ``` -## HeaderV9 +## WebHeader Describes the request/response header returned by the **\** component. **System capability**: SystemCapability.Web.Webview.Core @@ -4696,7 +4635,7 @@ Describes the request/response header returned by the **\** component. | headerKey | string | Yes| Yes| Key of the request/response header. | | headerValue | string | Yes| Yes| Value of the request/response header.| -## HitTestTypeV9 +## WebHitTestType **System capability**: SystemCapability.Web.Webview.Core @@ -4719,7 +4658,7 @@ Provides the element information of the area being clicked. For details about th | Name| Type| Readable| Writable| Description| | ---- | ---- | ---- | ---- |---- | -| type | [HitTestTypeV9](#hittesttypev9) | Yes| No| Element type of the area being clicked.| +| type | [WebHitTestType](#webhittesttype) | Yes| No| Element type of the area being clicked.| | extra | string | Yes| No|Extra information of the area being clicked. If the area being clicked is an image or a link, the extra information is the URL of the image or link.| ## WebMessage @@ -4788,7 +4727,7 @@ import image from "@ohos.multimedia.image" struct WebComponent { controller: web_webview.WebviewController = new web_webview.WebviewController(); @State icon: image.PixelMap = undefined; - + build() { Column() { Button('getBackForwardEntries') @@ -4796,8 +4735,8 @@ struct WebComponent { try { let list = this.controller.getBackForwardEntries(); let historyItem = list.getItemAtIndex(list.currentIndex); - console.log("HistoryItem: " + JSON.stringify(historyItem)); - this.icon = historyItem.icon; + console.log("HistoryItem: " + JSON.stringify(historyItem)); + this.icon = historyItem.icon; } catch (error) { console.error(`ErrorCode: ${error.code}, Message: ${error.message}`); } diff --git a/en/application-dev/reference/arkui-ts/ts-basic-components-web.md b/en/application-dev/reference/arkui-ts/ts-basic-components-web.md index efd01a21bb..b49036458e 100644 --- a/en/application-dev/reference/arkui-ts/ts-basic-components-web.md +++ b/en/application-dev/reference/arkui-ts/ts-basic-components-web.md @@ -21,6 +21,7 @@ Web(options: { src: ResourceStr, controller: WebController | WebviewController}) > **NOTE** > > Transition animation is not supported. +> Different **\** components on the same page must be bound to different **WebController**s. **Parameters** @@ -526,7 +527,7 @@ Sets whether to enable the multi-window permission. horizontalScrollBarAccess(horizontalScrollBar: boolean) -Sets whether to display the horizontal scrollbar, including the system default scrollbar and custom scrollbar. By default, the horizontal scrollbar is displayed. +Sets whether to display the horizontal scrollbar, including the default system scrollbar and custom scrollbar. By default, the horizontal scrollbar is displayed. **Parameters** @@ -1555,7 +1556,7 @@ onDownloadStart(callback: (event?: { url: string, userAgent: string, contentDisp onErrorReceive(callback: (event?: { request: WebResourceRequest, error: WebResourceError }) => void) -Called when an error occurs during web page loading. For better results, simplify the implementation logic in the callback. +Called when an error occurs during web page loading. For better results, simplify the implementation logic in the callback. This API is called when there is no network connection. **Parameters** @@ -1780,7 +1781,7 @@ Called when the document title of the web page is changed. onRefreshAccessedHistory(callback: (event?: { url: string, isRefreshed: boolean }) => void) -Called when loading of the web page is complete. This API is used by an application to update the historical link it accessed.. +Called when loading of the web page is complete. This API is used by an application to update the historical link it accessed. **Parameters** @@ -1966,7 +1967,7 @@ Called when the display ratio of this page changes. onUrlLoadIntercept(callback: (event?: { data:string | WebResourceRequest }) => boolean) -Called when the **\** component is about to access a URL. This API is used to determine whether to block the access. +Called when the **\** component is about to access a URL. This API is used to determine whether to block the access, which is allowed by default. **Parameters** @@ -2342,8 +2343,8 @@ Called when the scrollbar of the page scrolls. | Name | Type | Description | | ------- | ------ | ------------ | -| xOffset | number | Position of the scrollbar on the x-axis.| -| yOffset | number | Position of the scrollbar on the y-axis.| +| xOffset | number | Position of the scrollbar on the x-axis relative to the leftmost of the web page.| +| yOffset | number | Position of the scrollbar on the y-axis relative to the top of the web page.| **Example** @@ -2684,7 +2685,7 @@ Called when the old page is not displayed and the new page is about to be visibl onInterceptKeyEvent(callback: (event: KeyEvent) => boolean) -Called when the key event is intercepted, before being consumed by the Webview. +Called when the key event is intercepted and before it is consumed by the Webview. **Parameters** @@ -2711,7 +2712,7 @@ Called when the key event is intercepted, before being consumed by the Webview. Column() { Web({ src:'www.example.com', controller: this.controller }) .onInterceptKeyEvent((event) => { - if (event.keyCode == 2017 || event.keyCode == 2018) { + if (event.keyCode == 2017 || event.keyCode == 2018) { console.info(`onInterceptKeyEvent get event.keyCode ${event.keyCode}`) return true; } @@ -3178,18 +3179,6 @@ Instructs the **\** component to select a file. Implements the **FileSelectorParam** object. For the sample code, see [onShowFileSelector](#onshowfileselector9). -### getTitle9+ - -getTitle(): string - -Obtains the title of the file selector. - -**Return value** - -| Type | Description | -| ------ | ---------- | -| string | Title of the file selector.| - ### getMode9+ getMode(): FileSelectorMode @@ -3813,40 +3802,6 @@ This API is deprecated since API version 9. You are advised to use [forward } ``` -### backOrForward9+ - -backOrForward(step: number): void - -Performs a specific number of steps forward or backward on the current page based on the history stack. No redirection will be performed if the corresponding page does not exist in the history stack. - -**Parameters** - -| Name | Type | Mandatory | Default Value | Description | -| ---- | ------ | ---- | ---- | ----------- | -| step | number | Yes | - | Number of the steps to take.| - -**Example** - - ```ts - // xxx.ets - @Entry - @Component - struct WebComponent { - controller: WebController = new WebController() - @State step: number = -2 - - build() { - Column() { - Button('backOrForward') - .onClick(() => { - this.controller.backOrForward(this.step) - }) - Web({ src: 'www.example.com', controller: this.controller }) - } - } - } - ``` - ### deleteJavaScriptRegister(deprecated) deleteJavaScriptRegister(name: string) @@ -3919,73 +3874,6 @@ This API is deprecated since API version 9. You are advised to use [getHitTest9+ -getHitTestValue(): HitTestValue - -Obtains the element information of the area being clicked. - -**Return value** - -| Type | Description | -| ------------------------------ | ---------- | -| [HitTestValue](#hittestvalue9) | Element information of the area being clicked.| - -**Example** - - ```ts - // xxx.ets - @Entry - @Component - struct WebComponent { - controller: WebController = new WebController() - - build() { - Column() { - Button('getHitTestValue') - .onClick(() => { - let hitValue = this.controller.getHitTestValue() - console.log("hitType: " + hitValue.getType()) - console.log("extra: " + hitValue.getExtra()) - }) - Web({ src: 'www.example.com', controller: this.controller }) - } - } - } - ``` - -### getWebId9+ -getWebId(): number - -Obtains the index value of this **\** component, which can be used for **\** component management. - -**Return value** - -| Type | Description | -| ------ | ------------ | -| number | Index value of the current **\** component.| - -**Example** - - ```ts - // xxx.ets - @Entry - @Component - struct WebComponent { - controller: WebController = new WebController() - - build() { - Column() { - Button('getWebId') - .onClick(() => { - let id = this.controller.getWebId() - console.log("id: " + id) - }) - Web({ src: 'www.example.com', controller: this.controller }) - } - } - } - ``` - ### getTitle9+ getTitle(): string @@ -4019,72 +3907,6 @@ Obtains the title of the current web page. } ``` -### getPageHeight9+ -getPageHeight(): number - -Obtains the height of the current web page. - -**Return value** - -| Type | Description | -| ------ | ---------- | -| number | Height of the current web page.| - -**Example** - - ```ts - // xxx.ets - @Entry - @Component - struct WebComponent { - controller: WebController = new WebController() - - build() { - Column() { - Button('getPageHeight') - .onClick(() => { - let pageHeight = this.controller.getPageHeight() - console.log("pageHeight: " + pageHeight) - }) - Web({ src: 'www.example.com', controller: this.controller }) - } - } - } - ``` - -### getDefaultUserAgent9+ -getDefaultUserAgent(): string - -Obtains the default user agent of the current web page. - -**Return value** - -| Type | Description | -| ------ | ------- | -| string | Default user agent.| - -**Example** - - ```ts - // xxx.ets - @Entry - @Component - struct WebComponent { - controller: WebController = new WebController() - - build() { - Column() { - Button('getDefaultUserAgent') - .onClick(() => { - let userAgent = this.controller.getDefaultUserAgent() - console.log("userAgent: " + userAgent) - }) - Web({ src: 'www.example.com', controller: this.controller }) - } - } - } - ``` - ### loadData(deprecated) loadData(options: { data: string, mimeType: string, encoding: string, baseUrl?: string, historyUrl?: string }) @@ -4265,72 +4087,6 @@ This API is deprecated since API version 9. You are advised to use [zoom9+< } ``` -### zoomIn9+ -zoomIn(): boolean - -Zooms in on this web page by 20%. - -**Return value** - -| Type | Description | -| ------- | ----------- | -| boolean | Operation result.| - -**Example** - - ```ts - // xxx.ets - @Entry - @Component - struct WebComponent { - controller: WebController = new WebController() - - build() { - Column() { - Button('zoomIn') - .onClick(() => { - let result = this.controller.zoomIn() - console.log("result: " + result) - }) - Web({ src: 'www.example.com', controller: this.controller }) - } - } - } - ``` - -### zoomOut9+ -zoomOut(): boolean - -Zooms out of this web page by 20%. - -**Return value** - -| Type | Description | -| ------- | ----------- | -| boolean | Operation result.| - -**Example** - - ```ts - // xxx.ets - @Entry - @Component - struct WebComponent { - controller: WebController = new WebController() - - build() { - Column() { - Button('zoomOut') - .onClick(() => { - let result = this.controller.zoomOut() - console.log("result: " + result) - }) - Web({ src: 'www.example.com', controller: this.controller }) - } - } - } - ``` - ### refresh(deprecated) refresh() @@ -4547,11 +4303,17 @@ This API is deprecated since API version 9. You are advised to use [clearHistory } ``` -### clearSslCache +### getCookieManager9+ + +getCookieManager(): WebCookie + +Obtains the cookie management object of the **\** component. -clearSslCache(): void +**Return value** -Clears the user operation corresponding to the SSL certificate error event recorded by the **\** component. +| Type | Description | +| --------- | ---------------------------------------- | +| WebCookie | Cookie management object. For details, see [WebCookie](#webcookie).| **Example** @@ -4564,9 +4326,9 @@ Clears the user operation corresponding to the SSL certificate error event recor build() { Column() { - Button('clearSslCache') + Button('getCookieManager') .onClick(() => { - this.controller.clearSslCache() + let cookieManager = this.controller.getCookieManager() }) Web({ src: 'www.example.com', controller: this.controller }) } @@ -4574,44 +4336,27 @@ Clears the user operation corresponding to the SSL certificate error event recor } ``` -### clearClientAuthenticationCache - -clearClientAuthenticationCache(): void - -Clears the user operation corresponding to the client certificate request event recorded by the **\** component. - -**Example** +## WebCookie - ```ts - // xxx.ets - @Entry - @Component - struct WebComponent { - controller: WebController = new WebController() +Manages behavior of cookies in **\** components. All **\** components in an application share a **WebCookie**. You can use the **getCookieManager** API in **controller** to obtain the **WebCookie** for subsequent cookie management. - build() { - Column() { - Button('clearClientAuthenticationCache') - .onClick(() => { - this.controller.clearClientAuthenticationCache() - }) - Web({ src: 'www.example.com', controller: this.controller }) - } - } - } - ``` +### setCookie9+ +setCookie(url: string, value: string): boolean -### getCookieManager9+ +Sets the cookie. This API returns the result synchronously. Returns **true** if the operation is successful; returns **false** otherwise. -getCookieManager(): WebCookie +**Parameters** -Obtains the cookie management object of the **\** component. +| Name | Type | Mandatory | Default Value | Description | +| ----- | ------ | ---- | ---- | ----------------- | +| url | string | Yes | - | URL of the cookie to set.| +| value | string | Yes | - | Value of the cookie to set. | **Return value** -| Type | Description | -| --------- | ---------------------------------------- | -| WebCookie | Cookie management object. For details, see [WebCookie](#webcookie).| +| Type | Description | +| ------- | ------------- | +| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| **Example** @@ -4624,28 +4369,26 @@ Obtains the cookie management object of the **\** component. build() { Column() { - Button('getCookieManager') + Button('setCookie') .onClick(() => { - let cookieManager = this.controller.getCookieManager() + 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 -### createWebMessagePorts9+ - -createWebMessagePorts(): Array\ - -Creates web message ports. +Saves the cookies in the memory to the drive. This API returns the result synchronously. **Return value** - -| Type | Description | -| ---------------------------------------- | ---------- | -| Array\<[WebMessagePort](#webmessageport9)\> | List of web message ports.| +| Type | Description | +| ------- | -------------------- | +| boolean | Operation result.| **Example** @@ -4655,13 +4398,13 @@ Creates web message ports. @Component struct WebComponent { controller: WebController = new WebController() - ports: WebMessagePort[] = null + build() { Column() { - Button('createWebMessagePorts') + Button('saveCookieSync') .onClick(() => { - this.ports = this.controller.createWebMessagePorts() - console.log("createWebMessagePorts size:" + this.ports.length) + let result = this.controller.getCookieManager().saveCookieSync() + console.log("result: " + result) }) Web({ src: 'www.example.com', controller: this.controller }) } @@ -4669,737 +4412,7 @@ Creates web message ports. } ``` -### postMessage9+ - -postMessage(options: { message: WebMessageEvent, uri: string}): void - -Sends a web message to an HTML5 window. - -**Parameters** - -| Name | Type | Mandatory | Default Value | Description | -| ------- | ------------------------------------ | ---- | ---- | ----------------- | -| message | [WebMessageEvent](#webmessageevent9) | Yes | - | Message to send, including the data and message port.| -| uri | string | Yes | - | URI for receiving the message. | - -**Example** - - ```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() { - // Display the received HTML content. - Text(this.receivedFromHtml) - // Send the content in the text box to an HTML window. - TextInput({placeholder: 'Send this message from ets to HTML'}) - .onChange((value: string) => { - this.sendFromEts = value - }) - - // 1. Create two message ports. - Button('1.CreateWebMessagePorts') - .onClick(() => { - this.ports = this.controller.createWebMessagePorts() - console.log("createWebMessagePorts size:" + this.ports.length) - }) - - // 2. Send one of the message ports to the HTML side, which can then save and use the port. - 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. Register a callback for the other message port on the application side. - Button('3.RegisterCallback') - .onClick(() => { - this.ports[0].onMessageEvent((result: string) => { - var msg = 'Got msg from HTML: ' + result - this.receivedFromHtml = msg - }) - }) - - // 4. Use the port on the application side to send messages to the message port that has been sent to the 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. Save the port number sent from the eTS side. - h5Port.onmessage = function(event) { - // 2. Receive the message sent from the eTS side. - var msg = 'Got message from ets:' + event.data; - output.innerHTML = msg; - } - } - } - }) - - // 3. Use h5Port to send messages to the eTS side. - function PostMsgToEts(data) { - h5Port.postMessage(data) - } - ``` - -### getUrl9+ - -getUrl(): string - -Obtains the URL of this page. - -**Return value** - -| Type | Description | -| ------ | ----------- | -| string | URL of the current page.| - -**Example** - - ```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 - -Searches the web page for content that matches the keyword specified by **'searchString'** and highlights the matches on the page. This API returns the result asynchronously through [onSearchResultReceive](#onsearchresultreceive9). - -**Parameters** - -| Name | Type | Mandatory | Default Value | Description | -| ------------ | ------ | ---- | ---- | ------- | -| searchString | string | Yes | - | Search keyword.| - -**Example** - - ```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 - -Clears the matches found through [searchAllAsync](#searchallasync9). - -**Example** - - ```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 - -Searches for and highlights the next match. - -**Parameters** - -| Name | Type | Mandatory | Default Value | Description | -| ------- | ------- | ---- | ---- | ----------- | -| forward | boolean | Yes | - | Whether to search forward.| - - -**Example** - - ```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+ -Implements the **HitTestValue** object. For the sample code, see [getHitTestValue](#gethittestvalue9). - -### getType9+ -getType(): HitTestType - -Obtains the element type of the area being clicked. - -**Return value** - -| Type | Description | -| ------------------------------- | ------------- | -| [HitTestType](#hittesttype)| Element type of the area being clicked.| - -### getExtra9+ -getExtra(): string - -Obtains the extra information of the area being clicked. If the area being clicked is an image or a link, the extra information is the URL of the image or link. - -**Return value** - -| Type | Description | -| ------ | ------------ | -| string | Extra information of the area being clicked.| - - -## WebCookie - -Manages behavior of cookies in **\** components. All **\** components in an application share a **WebCookie**. You can use the **getCookieManager** API in **controller** to obtain the **WebCookie** for subsequent cookie management. - -### setCookie9+ -setCookie(url: string, value: string): boolean - -Sets the cookie. This API returns the result synchronously. Returns **true** if the operation is successful; returns **false** otherwise. - -**Parameters** - -| Name | Type | Mandatory | Default Value | Description | -| ----- | ------ | ---- | ---- | ----------------- | -| url | string | Yes | - | URL of the cookie to set.| -| value | string | Yes | - | Value of the cookie to set. | - -**Return value** - -| Type | Description | -| ------- | ------------- | -| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| - -**Example** - - ```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 - -Saves the cookies in the memory to the drive. This API returns the result synchronously. - -**Return value** - -| Type | Description | -| ------- | -------------------- | -| boolean | Operation result.| - -**Example** - - ```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 - -Obtains the cookie value corresponding to the specified URL. - -**Parameters** - -| Name | Type | Mandatory | Default Value | Description | -| ---- | ------ | ---- | ---- | ----------------- | -| url | string | Yes | - | URL of the cookie value to obtain.| - -**Return value** - -| Type | Description | -| ------ | ----------------- | -| string | Cookie value corresponding to the specified URL.| - -**Example** - - ```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 - -Sets a cookie value for the specified URL. - -**Parameters** - -| Name | Type | Mandatory | Default Value | Description | -| ----- | ------ | ---- | ---- | ----------------- | -| url | string | Yes | - | URL of the cookie to set.| -| value | string | Yes | - | Cookie value to set. | - -**Return value** - -| Type | Description | -| ------- | ------------- | -| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| - -**Example** - - ```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 }) - } - } - } - ``` - -### saveCookieAsync9+ -saveCookieAsync(): Promise\ - -Saves the cookies in the memory to the drive. This API uses a promise to return the value. - -**Return value** - -| Type | Description | -| ----------------- | --------------------------- | -| Promise\ | Promise used to return the result.| - -**Example** - - ```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 - -Saves the cookies in the memory to the drive. This API uses an asynchronous callback to return the result. - -**Parameters** - -| Name | Type | Mandatory | Default Value | Description | -| -------- | ----------------------- | ---- | ---- | ---------------------------- | -| callback | AsyncCallback\ | Yes | - | Callback used to return the operation result.| - -**Example** - - ```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 - -Checks whether the **WebCookieManager** instance has the permission to send and receive cookies. - -**Return value** - -| Type | Description | -| ------- | ------------------- | -| boolean | Whether the **WebCookieManager** instance has the permission to send and receive cookies.| - -**Example** - - ```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 - -Sets whether the **WebCookieManager** instance has the permission to send and receive cookies. - -**Parameters** - -| Name | Type | Mandatory | Default Value | Description | -| ------ | ------- | ---- | ---- | --------------------- | -| accept | boolean | Yes | - | Whether the **WebCookieManager** instance has the permission to send and receive cookies.| - -**Example** - - ```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 - -Checks whether the **WebCookieManager** instance has the permission to send and receive third-party cookies. - -**Return value** - -| Type | Description | -| ------- | ---------------------- | -| boolean | Whether the **WebCookieManager** instance has the permission to send and receive third-party cookies.| - -**Example** - - ```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 - -Sets whether the **WebCookieManager** instance has the permission to send and receive third-party cookies. - -**Parameters** - -| Name | Type | Mandatory | Default Value | Description | -| ------ | ------- | ---- | ---- | ------------------------ | -| accept | boolean | Yes | - | Whether the **WebCookieManager** instance has the permission to send and receive third-party cookies.| - -**Example** - - ```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 - -Checks whether cookies exist. - -**Return value** - -| Type | Description | -| ------- | ----------- | -| boolean | Whether cookies exist.| - -**Example** - - ```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 - -Deletes all cookies. - -**Example** - - ```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 - -Deletes all session cookies. - -**Example** - - ```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 }) - } - } - } - ``` - -## MessageLevel +## MessageLevel | Name | Description | | ----- | :---- | @@ -5482,227 +4495,6 @@ Enumerates the error codes returned by **onSslErrorEventReceive** API. | On | The web dark mode is enabled. | | Auto | The web dark mode setting follows the system settings. | -## WebMessagePort9+ - -Implements a **WebMessagePort** instance, which can be used to send and receive messages. - -### close9+ -close(): void - -Disables this message port. - -### postMessageEvent9+ -postMessageEvent(message: WebMessageEvent): void - -Sends messages. For the complete sample code, see [postMessage](#postmessage9). - -**Parameters** - -| Name | Type | Mandatory | Default Value | Description | -| ------- | ------------------------------------ | ---- | ---- | ------- | -| message | [WebMessageEvent](#webmessageevent9) | Yes | - | Message to send.| - -**Example** - - ```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 - -Registers a callback to receive messages from an HTML5 page. For the complete sample code, see [postMessage](#postmessage9). - -**Parameters** - -| Name | Type | Mandatory | Default Value | Description | -| -------- | -------- | ---- | ---- | ---------- | -| callback | function | Yes | - | Callback for receiving messages.| - -**Example** - - ```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+ - -Implements the **WebMessageEvent** object to encapsulate the message and port. - -### getData9+ -getData(): string - -Obtains the messages stored in this object. - -**Return value** - -| Type | Description | -| ------ | -------------- | -| string | Message stored in the object of this type.| - -**Example** - - ```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 - -Sets the message in this object. For the complete sample code, see [postMessage](#postmessage9). - -**Parameters** - -| Name | Type | Mandatory | Default Value | Description | -| ---- | ------ | ---- | ---- | ------- | -| data | string | Yes | - | Message to send.| - -**Example** - - ```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\ - -Obtains the message port stored in this object. - -**Return value** - -| Type | Description | -| ---------------------------------------- | ---------------- | -| Array\<[WebMessagePort](#webmessageport9)\> | Message port stored in the object of this type.| - -**Example** - - ```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 - -Sets the message port in this object. For the complete sample code, see [postMessage](#postmessage9). - -**Parameters** - -| Name | Type | Mandatory | Default Value | Description | -| ----- | ---------------------------------------- | ---- | ---- | --------- | -| ports | Array\<[WebMessagePort](#webmessageport9)\> | Yes | - | Message port.| - -**Example** - - ```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+ Implements the **DataResubmissionHandler** object for resubmitting or canceling the web form data. diff --git a/en/release-notes/changelogs/OpenHarmony_3.2.10.7/changelog-web.md b/en/release-notes/changelogs/OpenHarmony_3.2.10.7/changelog-web.md new file mode 100644 index 0000000000..806f127061 --- /dev/null +++ b/en/release-notes/changelogs/OpenHarmony_3.2.10.7/changelog-web.md @@ -0,0 +1,467 @@ +# Web Subsystem Changelog + +Compared with earlier versions, OpenHarmony 3.2.10.7 has the following API changes in its web subsystem: + +## cl.web.1 HitTestTypeV9 Name Change + +Renamed the enum class **HitTestTypeV9** **WebHitTestType** to meet the naming conventions. + +**Change Impact** + +The enum class **HitTestTypeV9** and APIs that use **HitTestTypeV9** as a parameter or return value cannot be used in OpenHarmony 3.2.10.7 and later versions. + +**Key API/Component Changes** + +- Involved APIs: + + enum HitTestTypeV9 + +- Before change: + + ```ts + enum HitTestTypeV9 + ``` + +- After change: + + ```ts + enum WebHitTestType + ``` + +**Adaptation Guide** + +Replace **HitTestTypeV9** with **WebHitTestType**. + +## cl.web.2 HeaderV9 Name Change + +Renamed the struct **HeaderV9** **WebHeader** to meet the naming conventions. + +**Change Impact** + +The struct **HeaderV9** and APIs that use **HeaderV9** as a parameter or return value cannot be used in OpenHarmony 3.2.10.7 and later versions. + +**Key API/Component Changes** + +- Involved APIs: + + interface HeaderV9 + +- Before change: + + ```ts + interface HeaderV9 + ``` + +- After change: + + ```ts + interface WebHeader + ``` + +**Adaptation Guide** + +Replace **HeaderV9** with **WebHeader**. + +## cl.web.3 Member Change of HitTestValue + +Rename the member variable **HitTestTypeV9** in the **HitTestValue** struct **WebHitTestType** to meet the naming conventions. + +**Change Impact** + +The struct **HitTestValue** and APIs that use **HitTestValue** as a parameter or return value cannot be used in OpenHarmony 3.2.10.7 and later versions. + +**Key API/Component Changes** + +- Involved APIs: + + interface HitTestValue + +- Before change: + + ```ts + interface HitTestValue { + + /** + * Get the hit test type. + * + * @since 9 + */ + type: HitTestTypeV9; + + /** + * Get the hit test extra data. + * + * @since 9 + */ + extra: string; + } + ``` + +- After change: + + ```ts + interface HitTestValue { + + /** + * Get the hit test type. + * + * @since 9 + */ + type: WebHitTestType; + + /** + * Get the hit test extra data. + * + * @since 9 + */ + extra: string; + } + ``` + +**Adaptation Guide** + +Replace **HitTestTypeV9** with **WebHitTestType**. + +## cl.web.4 Parameter Type Change of loadUrl + +Changed the type of the **headers** parameter in **loadUrl** to **WebHeader** to meet the naming conventions. + +**Change Impact** + +The **loadUrl** API that uses the **headers** parameter cannot be used in OpenHarmony 3.2.10.7 and later versions. + +**Key API/Component Changes** + +- Involved APIs: + + loadUrl(url: string | Resource, headers?: Array\): void + +- Before change: + + ```ts + loadUrl(url: string | Resource, headers?: Array): void + ``` + +- After change: + + ```ts + loadUrl(url: string | Resource, headers?: Array): void + ``` + +**Adaptation Guide** + +Change the type of the **headers** parameter in **loadUrl** from **HeaderV9** to **WebHeader**. + +## cl.web.5 Return Value Type Change of getHitTest + +Changed the return value type of the **getHitTest** API to **WebHitTest** to meet the naming conventions. + +**Change Impact** + +The **getHitTest** API cannot be used in OpenHarmony 3.2.10.7 and later versions. + +**Key API/Component Changes** + +- Involved APIs: + + getHitTest(): HitTestTypeV9 + +- Before change: + + ```ts + getHitTest(): HitTestTypeV9 + ``` + +- After change: + + ```ts + getHitTest(): WebHitTestType + ``` + +**Adaptation Guide** + +Change the return value type of the **getHitTest** API from **HitTestTypeV9** to **WebHitTestType**. + +## cl.web.6 Moving of the WebMessagePort Class + +Moved the **WebMessagePort** class to **@ohos.web.webview.d.ts** and added error throwing. + +**Change Impact** + +If your application is developed based on earlier versions, note that the **d.ts** file storage location and the name of the module to be imported are changed. In addition, be mindful of the error codes now that the APIs in the class support error code processing. + +**Key API/Component Changes** + +- Involved APIs: + + postMessageEvent(message: WebMessageEvent): void; + onMessageEvent(callback: (result: string) => void): void; + +- Before change: + + ```ts + postMessageEvent(message: WebMessageEvent): void; + onMessageEvent(callback: (result: string) => void): void; + ``` + +- After change: + + ```ts + postMessageEvent(message: WebMessage): void; + onMessageEvent(callback: (result: WebMessage) => void): void; + ``` + +**Adaptation Guide** + +Instead of importing APIs from the original **WebMessagePort** class, import APIs from **@ohos.web.webview** as follows: + + ```ts + import web_webview from '@ohos.web.webview'; + ``` + +## cl.web.7 Moving of the HitTestValue Class + +Moved the **HitTestValue** class to **@ohos.web.webview.d.ts**; changed **HitTestValue** from a class to an API; changed the **getType** and **getExtra** from APIs to attributes. + +**Change Impact** + +If your application is developed based on earlier versions, note that the **d.ts** file storage location and the name of the module to be imported are changed. + +**Key API/Component Changes** + +- Involved APIs: + + getType(): HitTestType; + getExtra(): string; + +- Before change: + + ```ts + getType(): HitTestType; + getExtra(): string; + ``` + +- After change: + + ```ts + type: WebHitTestType; + extra: string; + ``` + +**Adaptation Guide** + +Instead of importing APIs from the original **HitTestValue** class, import APIs from **@ohos.web.webview** as follows: + + ```ts + import web_webview from '@ohos.web.webview'; + ``` + +## cl.web.8 Moving of API Version 9 APIs Under WebCookie + +Moved APIs of API version 9 in the **WebCookie** class to **web.webview.webview.WebCookieManager** +and added error throwing. + +**Change Impact** + +If your application is developed based on earlier versions, note that the **d.ts** file storage location and the name of the module to be imported are changed. In addition, be mindful of the error codes now that the APIs in the class support error code processing. +The APIs in the class are static. + +**Key API/Component Changes** + +- Involved APIs: + + isCookieAllowed(): boolean; + isThirdPartyCookieAllowed(): boolean; + putAcceptCookieEnabled(accept: boolean): void; + putAcceptThirdPartyCookieEnabled(accept: boolean): void; + setCookie(url: string, value: string): boolean; + saveCookieSync(): boolean; + getCookie(url: string): string; + existCookie(): boolean; + deleteEntireCookie(): void; + deleteSessionCookie(): void; + +- Before change: + + ```ts + isCookieAllowed(): boolean; + isThirdPartyCookieAllowed(): boolean; + putAcceptCookieEnabled(accept: boolean): void; + putAcceptThirdPartyCookieEnabled(accept: boolean): void; + setCookie(url: string, value: string): boolean; + saveCookieSync(): boolean; + getCookie(url: string): string; + existCookie(): boolean; + deleteEntireCookie(): void; + deleteSessionCookie(): void; + ``` + +- After change: + + ```ts + static isCookieAllowed(): boolean; + static isThirdPartyCookieAllowed(): boolean; + static putAcceptCookieEnabled(accept: boolean): void; + static putAcceptThirdPartyCookieEnabled(accept: boolean): void; + static setCookie(url: string, value: string): void; + static saveCookieAsync(): Promise; + static saveCookieAsync(callback: AsyncCallback): void; + static getCookie(url: string): string; + static existCookie(): boolean; + static deleteEntireCookie(): void; + static deleteSessionCookie(): void; + ``` + +**Adaptation Guide** + +Instead of importing APIs from the original **WebCookie** class, import APIs from **@ohos.web.webview** as follows: + + ```ts + import web_webview from '@ohos.web.webview'; + ``` + +## cl.web.9 Moving of API Version 9 APIs Under WebController + +Moved APIs of API version 9 in the **WebController** class to **web.webview.webview.WebviewController** and added error throwing. + +**Change Impact** + +If your application is developed based on earlier versions, note that the **d.ts** file storage location and the name of the module to be imported are changed. In addition, be mindful of the error codes now that the APIs in the class support error code processing. +The **getDefaultUserAgent** API is renamed **getUserAgent**. + +**Key API/Component Changes** + +- Involved APIs: + + zoomIn(): boolean; + zoomOut(): boolean; + createWebMessagePorts(): Array\; + postMessage(options: { message: WebMessageEvent, uri: string}): void; + getHitTestValue(): HitTestValue; + getWebId(): number; + getDefaultUserAgent(): string; + getTitle(): string; + getPageHeight(): number; + backOrForward(step: number): void; + searchAllAsync(searchString: string): void; + clearMatches(): void; + searchNext(forward: boolean): void; + clearSslCache(): void; + clearClientAuthenticationCache(): void; + getUrl(): string; + +- Before change: + + ```ts + zoomIn(): boolean; + zoomOut(): boolean; + createWebMessagePorts(): Array; + postMessage(options: { message: WebMessageEvent, uri: string}): void; + getHitTestValue(): HitTestValue; + getWebId(): number; + getDefaultUserAgent(): string; + getTitle(): string; + getPageHeight(): number; + backOrForward(step: number): void; + searchAllAsync(searchString: string): void; + clearMatches(): void; + searchNext(forward: boolean): void; + clearSslCache(): void; + clearClientAuthenticationCache(): void; + getUrl(): string; + ``` + +- After change: + + ```ts + zoomIn(): void; + zoomOut(): void; + createWebMessagePorts(): Array; + postMessage(name: string, ports: Array, uri: string): void; + getHitTestValue(): HitTestValue; + getWebId(): number; + getUserAgent(): string; + getTitle(): string; + getPageHeight(): number; + backOrForward(step: number): void; + searchAllAsync(searchString: string): void; + clearMatches(): void; + searchNext(forward: boolean): void; + clearSslCache(): void; + clearClientAuthenticationCache(): void; + getUrl(): string; + ``` + +**Adaptation Guide** + +Instead of importing APIs from the original **WebController** class, import APIs from **@ohos.web.webview** as follows: + + ```ts + import web_webview from '@ohos.web.webview'; + ``` + +## cl.web.10 Moving of the WebAsyncController Class + +Moved the APIs in the **WebAsyncController** class to the **web.webview.webview.WebviewController** class and added error throwing. + +**Change Impact** + +If your application is developed based on earlier versions, pay attention to error code processing. + +**Key API/Component Changes** + +- Involved APIs: + + storeWebArchive(baseName: string, autoName: boolean): Promise\; + storeWebArchive(baseName: string, autoName: boolean, callback : AsyncCallback\): void; + +- Before change: + + ```ts + storeWebArchive(baseName: string, autoName: boolean): Promise; + storeWebArchive(baseName: string, autoName: boolean, callback : AsyncCallback): void; + ``` + +- After change: + + ```ts + storeWebArchive(baseName: string, autoName: boolean): Promise; + storeWebArchive(baseName: string, autoName: boolean, callback : AsyncCallback): void; + ``` + +**Adaptation Guide** + +Example: + + ```ts + // xxx.ets + import web_webview from '@ohos.web.webview' + + @Entry + @Component + struct WebComponent { + controller: web_webview.WebviewController = new web_webview.WebviewController(); + + build() { + Column() { + Button('saveWebArchive') + .onClick(() => { + try { + this.controller.storeWebArchive("/data/storage/el2/base/", true, (error, filename) => { + if (error) { + console.info(`save web archive error: ` + JSON.stringify(error)) + return; + } + if (filename != null) { + console.info(`save web archive success: ${filename}`) + } + }); + } catch (error) { + console.error(`ErrorCode: ${error.code}, Message: ${error.message}`); + } + }) + Web({ src: 'www.example.com', controller: this.controller }) + } + } + } + ``` diff --git a/en/release-notes/changelogs/OpenHarmony_4.0.3.2/changelog-web.md b/en/release-notes/changelogs/OpenHarmony_4.0.3.2/changelog-web.md new file mode 100644 index 0000000000..44380d1195 --- /dev/null +++ b/en/release-notes/changelogs/OpenHarmony_4.0.3.2/changelog-web.md @@ -0,0 +1,467 @@ +# Web Subsystem Changelog + +Compared with earlier versions, OpenHarmony 4.0.3.2 has the following API changes in its web subsystem: + +## cl.web.1 HitTestTypeV9 Name Change + +Renamed the enum class **HitTestTypeV9** **WebHitTestType** to meet the naming conventions. + +**Change Impact** + +The enum class **HitTestTypeV9** and APIs that use **HitTestTypeV9** as a parameter or return value cannot be used in OpenHarmony 4.0.3.2 and later versions. + +**Key API/Component Changes** + +- Involved APIs: + + enum HitTestTypeV9 + +- Before change: + + ```ts + enum HitTestTypeV9 + ``` + +- After change: + + ```ts + enum WebHitTestType + ``` + +**Adaptation Guide** + +Replace **HitTestTypeV9** with **WebHitTestType**. + +## cl.web.2 HeaderV9 Name Change + +Renamed the struct **HeaderV9** **WebHeader** to meet the naming conventions. + +**Change Impact** + +The struct **HeaderV9** and APIs that use **HeaderV9** as a parameter or return value cannot be used in OpenHarmony 4.0.3.2 and later versions. + +**Key API/Component Changes** + +- Involved APIs: + + interface HeaderV9 + +- Before change: + + ```ts + interface HeaderV9 + ``` + +- After change: + + ```ts + interface WebHeader + ``` + +**Adaptation Guide** + +Replace **HeaderV9** with **WebHeader**. + +## cl.web.3 Member Change of HitTestValue + +Rename the member variable **HitTestTypeV9** in the **HitTestValue** struct **WebHitTestType** to meet the naming conventions. + +**Change Impact** + +The struct **HitTestValue** and APIs that use **HitTestValue** as a parameter or return value cannot be used in OpenHarmony 4.0.3.2 and later versions. + +**Key API/Component Changes** + +- Involved APIs: + + interface HitTestValue + +- Before change: + + ```ts + interface HitTestValue { + + /** + * Get the hit test type. + * + * @since 9 + */ + type: HitTestTypeV9; + + /** + * Get the hit test extra data. + * + * @since 9 + */ + extra: string; + } + ``` + +- After change: + + ```ts + interface HitTestValue { + + /** + * Get the hit test type. + * + * @since 9 + */ + type: WebHitTestType; + + /** + * Get the hit test extra data. + * + * @since 9 + */ + extra: string; + } + ``` + +**Adaptation Guide** + +Replace **HitTestTypeV9** with **WebHitTestType**. + +## cl.web.4 Parameter Type Change of loadUrl + +Changed the type of the **headers** parameter in **loadUrl** to **WebHeader** to meet the naming conventions. + +**Change Impact** + +The **loadUrl** API that uses the **headers** parameter cannot be used in OpenHarmony 4.0.3.2 and later versions. + +**Key API/Component Changes** + +- Involved APIs: + + loadUrl(url: string | Resource, headers?: Array\): void + +- Before change: + + ```ts + loadUrl(url: string | Resource, headers?: Array): void + ``` + +- After change: + + ```ts + loadUrl(url: string | Resource, headers?: Array): void + ``` + +**Adaptation Guide** + +Change the type of the **headers** parameter in **loadUrl** from **HeaderV9** to **WebHeader**. + +## cl.web.5 Return Value Type Change of getHitTest + +Changed the return value type of the **getHitTest** API to **WebHitTest** to meet the naming conventions. + +**Change Impact** + +The **getHitTest** API cannot be used in OpenHarmony 4.0.3.2 and later versions. + +**Key API/Component Changes** + +- Involved APIs: + + getHitTest(): HitTestTypeV9 + +- Before change: + + ```ts + getHitTest(): HitTestTypeV9 + ``` + +- After change: + + ```ts + getHitTest(): WebHitTestType + ``` + +**Adaptation Guide** + +Change the return value type of the **getHitTest** API from **HitTestTypeV9** to **WebHitTestType**. + +## cl.web.6 Moving of the WebMessagePort Class + +Moved the **WebMessagePort** class to **@ohos.web.webview.d.ts** and added error throwing. + +**Change Impact** + +If your application is developed based on earlier versions, note that the **d.ts** file storage location and the name of the module to be imported are changed. In addition, be mindful of the error codes now that the APIs in the class support error code processing. + +**Key API/Component Changes** + +- Involved APIs: + + postMessageEvent(message: WebMessageEvent): void; + onMessageEvent(callback: (result: string) => void): void; + +- Before change: + + ```ts + postMessageEvent(message: WebMessageEvent): void; + onMessageEvent(callback: (result: string) => void): void; + ``` + +- After change: + + ```ts + postMessageEvent(message: WebMessage): void; + onMessageEvent(callback: (result: WebMessage) => void): void; + ``` + +**Adaptation Guide** + +Instead of importing APIs from the original **WebMessagePort** class, import APIs from **@ohos.web.webview** as follows: + + ```ts + import web_webview from '@ohos.web.webview'; + ``` + +## cl.web.7 Moving of the HitTestValue Class + +Moved the **HitTestValue** class to **@ohos.web.webview.d.ts**; changed **HitTestValue** from a class to an API; changed the **getType** and **getExtra** from APIs to attributes. + +**Change Impact** + +If your application is developed based on earlier versions, note that the **d.ts** file storage location and the name of the module to be imported are changed. + +**Key API/Component Changes** + +- Involved APIs: + + getType(): HitTestType; + getExtra(): string; + +- Before change: + + ```ts + getType(): HitTestType; + getExtra(): string; + ``` + +- After change: + + ```ts + type: WebHitTestType; + extra: string; + ``` + +**Adaptation Guide** + +Instead of importing APIs from the original **HitTestValue** class, import APIs from **@ohos.web.webview** as follows: + + ```ts + import web_webview from '@ohos.web.webview'; + ``` + +## cl.web.8 Moving of API Version 9 APIs Under WebCookie + +Moved APIs of API version 9 in the **WebCookie** class to **web.webview.webview.WebCookieManager** +and added error throwing. + +**Change Impact** + +If your application is developed based on earlier versions, note that the **d.ts** file storage location and the name of the module to be imported are changed. In addition, be mindful of the error codes now that the APIs in the class support error code processing. +The APIs in the class are static. + +**Key API/Component Changes** + +- Involved APIs: + + isCookieAllowed(): boolean; + isThirdPartyCookieAllowed(): boolean; + putAcceptCookieEnabled(accept: boolean): void; + putAcceptThirdPartyCookieEnabled(accept: boolean): void; + setCookie(url: string, value: string): boolean; + saveCookieSync(): boolean; + getCookie(url: string): string; + existCookie(): boolean; + deleteEntireCookie(): void; + deleteSessionCookie(): void; + +- Before change: + + ```ts + isCookieAllowed(): boolean; + isThirdPartyCookieAllowed(): boolean; + putAcceptCookieEnabled(accept: boolean): void; + putAcceptThirdPartyCookieEnabled(accept: boolean): void; + setCookie(url: string, value: string): boolean; + saveCookieSync(): boolean; + getCookie(url: string): string; + existCookie(): boolean; + deleteEntireCookie(): void; + deleteSessionCookie(): void; + ``` + +- After change: + + ```ts + static isCookieAllowed(): boolean; + static isThirdPartyCookieAllowed(): boolean; + static putAcceptCookieEnabled(accept: boolean): void; + static putAcceptThirdPartyCookieEnabled(accept: boolean): void; + static setCookie(url: string, value: string): void; + static saveCookieAsync(): Promise; + static saveCookieAsync(callback: AsyncCallback): void; + static getCookie(url: string): string; + static existCookie(): boolean; + static deleteEntireCookie(): void; + static deleteSessionCookie(): void; + ``` + +**Adaptation Guide** + +Instead of importing APIs from the original **WebCookie** class, import APIs from **@ohos.web.webview** as follows: + + ```ts + import web_webview from '@ohos.web.webview'; + ``` + +## cl.web.9 Moving of API Version 9 APIs Under WebController + +Moved APIs of API version 9 in the **WebController** class to **web.webview.webview.WebviewController** and added error throwing. + +**Change Impact** + +If your application is developed based on earlier versions, note that the **d.ts** file storage location and the name of the module to be imported are changed. In addition, be mindful of the error codes now that the APIs in the class support error code processing. +The **getDefaultUserAgent** API is renamed **getUserAgent**. + +**Key API/Component Changes** + +- Involved APIs: + + zoomIn(): boolean; + zoomOut(): boolean; + createWebMessagePorts(): Array\; + postMessage(options: { message: WebMessageEvent, uri: string}): void; + getHitTestValue(): HitTestValue; + getWebId(): number; + getDefaultUserAgent(): string; + getTitle(): string; + getPageHeight(): number; + backOrForward(step: number): void; + searchAllAsync(searchString: string): void; + clearMatches(): void; + searchNext(forward: boolean): void; + clearSslCache(): void; + clearClientAuthenticationCache(): void; + getUrl(): string; + +- Before change: + + ```ts + zoomIn(): boolean; + zoomOut(): boolean; + createWebMessagePorts(): Array; + postMessage(options: { message: WebMessageEvent, uri: string}): void; + getHitTestValue(): HitTestValue; + getWebId(): number; + getDefaultUserAgent(): string; + getTitle(): string; + getPageHeight(): number; + backOrForward(step: number): void; + searchAllAsync(searchString: string): void; + clearMatches(): void; + searchNext(forward: boolean): void; + clearSslCache(): void; + clearClientAuthenticationCache(): void; + getUrl(): string; + ``` + +- After change: + + ```ts + zoomIn(): void; + zoomOut(): void; + createWebMessagePorts(): Array; + postMessage(name: string, ports: Array, uri: string): void; + getHitTestValue(): HitTestValue; + getWebId(): number; + getUserAgent(): string; + getTitle(): string; + getPageHeight(): number; + backOrForward(step: number): void; + searchAllAsync(searchString: string): void; + clearMatches(): void; + searchNext(forward: boolean): void; + clearSslCache(): void; + clearClientAuthenticationCache(): void; + getUrl(): string; + ``` + +**Adaptation Guide** + +Instead of importing APIs from the original **WebController** class, import APIs from **@ohos.web.webview** as follows: + + ```ts + import web_webview from '@ohos.web.webview'; + ``` + +## cl.web.10 Moving of the WebAsyncController Class + +Moved the APIs in the **WebAsyncController** class to the **web.webview.webview.WebviewController** class and added error throwing. + +**Change Impact** + +If your application is developed based on earlier versions, pay attention to error code processing. + +**Key API/Component Changes** + +- Involved APIs: + + storeWebArchive(baseName: string, autoName: boolean): Promise\; + storeWebArchive(baseName: string, autoName: boolean, callback : AsyncCallback\): void; + +- Before change: + + ```ts + storeWebArchive(baseName: string, autoName: boolean): Promise; + storeWebArchive(baseName: string, autoName: boolean, callback : AsyncCallback): void; + ``` + +- After change: + + ```ts + storeWebArchive(baseName: string, autoName: boolean): Promise; + storeWebArchive(baseName: string, autoName: boolean, callback : AsyncCallback): void; + ``` + +**Adaptation Guide** + +Example: + + ```ts + // xxx.ets + import web_webview from '@ohos.web.webview' + + @Entry + @Component + struct WebComponent { + controller: web_webview.WebviewController = new web_webview.WebviewController(); + + build() { + Column() { + Button('saveWebArchive') + .onClick(() => { + try { + this.controller.storeWebArchive("/data/storage/el2/base/", true, (error, filename) => { + if (error) { + console.info(`save web archive error: ` + JSON.stringify(error)) + return; + } + if (filename != null) { + console.info(`save web archive success: ${filename}`) + } + }); + } catch (error) { + console.error(`ErrorCode: ${error.code}, Message: ${error.message}`); + } + }) + Web({ src: 'www.example.com', controller: this.controller }) + } + } + } + ``` -- GitLab