From 0f8427eee77d1bbcd57d8ad314e31af7e11c2c83 Mon Sep 17 00:00:00 2001 From: "ester.zhou" Date: Tue, 27 Jun 2023 09:34:56 +0800 Subject: [PATCH] Update docs (19489) Signed-off-by: ester.zhou --- .../reference/apis/js-apis-webview.md | 334 +++++++++++------- .../arkui-ts/ts-basic-components-web.md | 183 +++++----- 2 files changed, 290 insertions(+), 227 deletions(-) diff --git a/en/application-dev/reference/apis/js-apis-webview.md b/en/application-dev/reference/apis/js-apis-webview.md index 956f922e54..a5334a2608 100644 --- a/en/application-dev/reference/apis/js-apis-webview.md +++ b/en/application-dev/reference/apis/js-apis-webview.md @@ -63,42 +63,6 @@ struct WebComponent { Implements a **WebMessagePort** object to send and receive messages. -### close - -close(): void - -Closes this message port. - -**System capability**: SystemCapability.Web.Webview.Core - -**Example** - -```ts -// xxx.ets -import web_webview from '@ohos.web.webview' - -@Entry -@Component -struct WebComponent { - controller: web_webview.WebviewController = new web_webview.WebviewController(); - msgPort: web_webview.WebMessagePort[] = null; - - build() { - Column() { - Button('close') - .onClick(() => { - if (this.msgPort && this.msgPort[1]) { - this.msgPort[1].close(); - } else { - console.error("msgPort is null, Please initialize first"); - } - }) - Web({ src: 'www.example.com', controller: this.controller }) - } - } -} -``` - ### postMessageEvent postMessageEvent(message: WebMessage): void @@ -364,6 +328,7 @@ struct WebComponent { } ``` +HTML file to be loaded: ```html @@ -448,6 +413,56 @@ function postStringToApp() { } ``` +### close + +close(): void + +Closes this message port. To use this API, a message port must first be created using [createWebMessagePorts](#createwebmessageports). + +**System capability**: SystemCapability.Web.Webview.Core + +**Example** + +```ts +// xxx.ets +import web_webview from '@ohos.web.webview' + +@Entry +@Component +struct WebComponent { + controller: web_webview.WebviewController = new web_webview.WebviewController(); + msgPort: web_webview.WebMessagePort[] = null; + + build() { + Column() { + // Use createWebMessagePorts to create a message port. + Button('createWebMessagePorts') + .onClick(() => { + try { + this.msgPort = this.controller.createWebMessagePorts(); + console.log("createWebMessagePorts size:" + this.msgPort.length) + } catch (error) { + console.error(`ErrorCode: ${error.code}, Message: ${error.message}`); + } + }) + Button('close') + .onClick(() => { + try { + if (this.msgPort && this.msgPort.length == 2) { + this.msgPort[1].close(); + } else { + console.error("msgPort is null, Please initialize first"); + } + } catch (error) { + console.error(`ErrorCode: ${error.code}, Message: ${error.message}`); + } + }) + Web({ src: 'www.example.com', controller: this.controller }) + } + } +} +``` + ## WebviewController Implements a **WebviewController** to control the behavior of the **\** component. A **WebviewController** can control only one **\** component, and the APIs (except static APIs) in the **WebviewController** can be invoked only after it has been bound to the target **\** component. @@ -473,7 +488,6 @@ export default class EntryAbility extends UIAbility { onCreate(want, launchParam) { console.log("EntryAbility onCreate") web_webview.WebviewController.initializeWebEngine() - globalThis.abilityWant = want console.log("EntryAbility onCreate done") } } @@ -516,30 +530,11 @@ export default class EntryAbility extends UIAbility { } ``` -### Creating an Object - -```ts -// xxx.ets -import web_webview from '@ohos.web.webview'; - -@Entry -@Component -struct WebComponent { - controller: web_webview.WebviewController = new web_webview.WebviewController(); - - build() { - Column() { - Web({ src: 'www.example.com', controller: this.controller }) - } - } -} -``` - ### setWebDebuggingAccess static setWebDebuggingAccess(webDebuggingAccess: boolean): void -Sets whether to enable web debugging. +Sets whether to enable web debugging. For details, see [Debugging Frontend Pages by Using DevTools](../../web/web-debugging-with-devtools.md). **System capability**: SystemCapability.Web.Webview.Core @@ -656,70 +651,73 @@ struct WebComponent { ``` There are three methods for loading local resource files: -1. Using $rawfile -```ts -// xxx.ets -import web_webview from '@ohos.web.webview' -@Entry -@Component -struct WebComponent { - controller: web_webview.WebviewController = new web_webview.WebviewController(); +1. Using $rawfile + ```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 { + // Load a local resource file through $rawfile. + this.controller.loadUrl($rawfile('index.html')); + } catch (error) { + console.error(`ErrorCode: ${error.code}, Message: ${error.message}`); + } + }) + Web({ src: 'www.example.com', controller: this.controller }) + } + } + } + ``` - build() { - Column() { - Button('loadUrl') - .onClick(() => { - try { - // Load a local resource file through $rawfile. - this.controller.loadUrl($rawfile('xxx.html')); - } catch (error) { - console.error(`ErrorCode: ${error.code}, Message: ${error.message}`); - } - }) - Web({ src: 'www.example.com', controller: this.controller }) - } - } -} -``` 2. Using the resources protocol -```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 { - // Load a local resource file through the resource protocol. - this.controller.loadUrl("resource://rawfile/xxx.html"); - } catch (error) { - console.error(`ErrorCode: ${error.code}, Message: ${error.message}`); - } - }) - Web({ src: 'www.example.com', controller: this.controller }) - } - } -} -``` + ```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 { + // Load a local resource file through the resource protocol. + this.controller.loadUrl("resource://rawfile/index.html"); + } catch (error) { + console.error(`ErrorCode: ${error.code}, Message: ${error.message}`); + } + }) + Web({ src: 'www.example.com', controller: this.controller }) + } + } + } + ``` 3. Using a sandbox path. For details, see the example of loading local resource files in the sandbox in [Web](../arkui-ts/ts-basic-components-web.md#web). -```html - - - - -

Hello World

- - -``` + HTML file to be loaded: + ```html + + + + +

Hello World

+ + + ``` ### loadData @@ -1343,6 +1341,24 @@ struct Index { } ``` +HTML file to be loaded: +```html + + + + + + Hello world! + + + +``` + ### runJavaScript runJavaScript(script: string, callback : AsyncCallback\): void @@ -1406,6 +1422,24 @@ struct WebComponent { } ``` +HTML file to be loaded: +```html + + + + + + Hello world! + + + +``` + ### runJavaScript runJavaScript(script: string): Promise\ @@ -1444,11 +1478,9 @@ import web_webview from '@ohos.web.webview' @Component struct WebComponent { controller: web_webview.WebviewController = new web_webview.WebviewController(); - @State webResult: string = ''; build() { Column() { - Text(this.webResult).fontSize(20) Web({ src: $rawfile('index.html'), controller: this.controller }) .javaScriptAccess(true) .onPageEnd(e => { @@ -1470,6 +1502,23 @@ struct WebComponent { } ``` +HTML file to be loaded: +```html + + + + + + Hello world! + + + +``` ### runJavaScriptExt10+ @@ -1569,8 +1618,11 @@ struct WebComponent { } } } +``` -//index.html +HTML file to be loaded: +```html + @@ -1681,8 +1733,11 @@ struct WebComponent { } } } +``` -//index.html +HTML file to be loaded: +```html + @@ -2178,14 +2233,15 @@ struct WebComponent { console.error(`ErrorCode: ${error.code}, Message: ${error.message}`); } }) - Web({ src: $rawfile('xxx.html'), controller: this.controller }) + Web({ src: $rawfile('index.html'), controller: this.controller }) } } } ``` +HTML file to be loaded: ```html - + @@ -2973,14 +3029,15 @@ struct WebComponent { console.error(`ErrorCode: ${error.code}, Message: ${error.message}`); } }) - Web({ src: 'www.example.com', controller: this.controller }) + Web({ src: $rawfile('index.html'), controller: this.controller }) } } } ``` +HTML file to be loaded: ```html - + @@ -3045,14 +3102,15 @@ struct WebComponent { console.error(`ErrorCode: ${error.code}, Message: ${error.message}`); } }) - Web({ src: 'www.example.com', controller: this.controller }) + Web({ src: $rawfile('index.html'), controller: this.controller }) } } } ``` +HTML file to be loaded: ```html - + @@ -3117,14 +3175,15 @@ struct WebComponent { console.error(`ErrorCode: ${error.code}, Message: ${error.message}`); } }) - Web({ src: 'www.example.com', controller: this.controller }) + Web({ src: $rawfile('index.html'), controller: this.controller }) } } } ``` +HTML file to be loaded: ```html - + @@ -3640,7 +3699,7 @@ struct WebComponent { .onClick(() => { try { let state = this.controller.serializeWebState(); - // Obtain the value of globalThis.cacheDir from MainAbility.ts. + // globalThis.cacheDir is obtained from EntryAbility.ts. let path = globalThis.cacheDir; path += '/WebState'; // Synchronously open a file. @@ -3657,14 +3716,14 @@ struct WebComponent { } ``` -2. Modify **MainAbility.ts**. +2. Modify the **EntryAbility.ts** file. Obtain the path of the application cache file. ```ts // xxx.ts import UIAbility from '@ohos.app.ability.UIAbility'; import web_webview from '@ohos.web.webview'; -export default class MainAbility extends UIAbility { +export default class EntryAbility extends UIAbility { onCreate(want, launchParam) { // Bind cacheDir to the globalThis object to implement data synchronization between the UIAbility component and the page. globalThis.cacheDir = this.context.cacheDir; @@ -3712,7 +3771,7 @@ struct WebComponent { Button('RestoreWebState') .onClick(() => { try { - // Obtain the value of globalThis.cacheDir from MainAbility.ts. + // globalThis.cacheDir is obtained from EntryAbility.ts. let path = globalThis.cacheDir; path += '/WebState'; // Synchronously open a file. @@ -3739,14 +3798,14 @@ struct WebComponent { } ``` -2. Modify **MainAbility.ts**. +2. Modify the **EntryAbility.ts** file. Obtain the path of the application cache file. ```ts // xxx.ts import UIAbility from '@ohos.app.ability.UIAbility'; import web_webview from '@ohos.web.webview'; -export default class MainAbility extends UIAbility { +export default class EntryAbility extends UIAbility { onCreate(want, launchParam) { // Bind cacheDir to the globalThis object to implement data synchronization between the UIAbility component and the page. globalThis.cacheDir = this.context.cacheDir; @@ -6230,6 +6289,9 @@ Describes the mode in which the **\** component uses HTTPDNS. | Name | Value| Description | | ------------- | -- |----------------------------------------- | -| Off | 0 |HTTPDNS is not used. This value can be used to revoke the previously used HTTPDNS configuration.| -| Auto | 1 |HTTPDNS is used in automatic mode. When the specified HTTPDNS server is unavailable for resolution, the component will fall back to the system DNS server.| -| SecureOnly | 2 |The specified HTTPDNS server is forcibly used for DNS resolution.| +| Off(deprecated) | 0 |HTTPDNS is not used. This value can be used to revoke the previously used HTTPDNS configuration.
This API is deprecated since API version 10. You are advised to use **OFF** instead.| +| Auto(deprecated) | 1 |HTTPDNS is used in automatic mode. When the specified HTTPDNS server is unavailable for resolution, the component will fall back to the system DNS server.
This API is deprecated since API version 10. You are advised to use **AUTO** instead.| +| SecureOnly(deprecated) | 2 |The specified HTTPDNS server is forcibly used for DNS resolution.
This API is deprecated since API version 10. You are advised to use **SECURE_ONLY** instead.| +| OFF | 0 |HTTPDNS is not used. This value can be used to revoke the previously used HTTPDNS configuration.| +| AUTO | 1 |HTTPDNS is used in automatic mode. When the specified HTTPDNS server is unavailable for resolution, the component will fall back to the system DNS server.| +| SECURE_ONLY | 2 |The specified HTTPDNS server is forcibly used for DNS resolution.| 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 5e2e776bf3..2d6b3bab8f 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 @@ -87,28 +87,28 @@ Web(options: { src: ResourceStr, controller: WebviewController | WebController}) Example of loading local resource files in the sandbox: - 1. Use [globalthis](../../application-models/uiability-data-sync-with-ui.md#using-globalthis-between-uiability-and-page) to obtain the path of the sandbox. - ```ts - // xxx.ets - import web_webview from '@ohos.web.webview' - let url = 'file://' + globalThis.filesDir + '/xxx.html' - - @Entry - @Component - struct WebComponent { - controller: web_webview.WebviewController = new web_webview.WebviewController() - build() { - Column() { - // Load the files in the sandbox. - Web({ src: url, controller: this.controller }) - } - } - } - ``` + 1. Use [globalthis](../../application-models/uiability-data-sync-with-ui.md#using-globalthis-between-uiability-and-ui-page) to obtain the path of the sandbox. + ```ts + // xxx.ets + import web_webview from '@ohos.web.webview' + let url = 'file://' + globalThis.filesDir + '/index.html' - 2. Modify the **MainAbility.ts** file. - - The following uses **filesDir** as an example to describe how to obtain the path of the sandbox. For details about how to obtain other paths, see [Obtaining the Application Development Path](../../application-models/application-context-stage.md#obtaining-the-application-development-path). + @Entry + @Component + struct WebComponent { + controller: web_webview.WebviewController = new web_webview.WebviewController() + build() { + Column() { + // Load the files in the sandbox. + Web({ src: url, controller: this.controller }) + } + } + } + ``` + + 2. Modify the **EntryAbility.ts** file. + + The following uses **filesDir** as an example to describe how to obtain the path of the sandbox. For details about how to obtain other paths, see [Obtaining Application File Paths](../../application-models/application-context-stage.md#obtaining-application-file-paths). ```ts // xxx.ts import UIAbility from '@ohos.app.ability.UIAbility'; @@ -123,6 +123,7 @@ Web(options: { src: ResourceStr, controller: WebviewController | WebController}) } ``` + HTML file to be loaded: ```html @@ -587,15 +588,16 @@ Sets whether to display the horizontal scrollbar, including the default system s controller: web_webview.WebviewController = new web_webview.WebviewController() build() { Column() { - Web({ src: 'www.example.com', controller: this.controller }) + Web({ src: $rawfile('index.html'), controller: this.controller }) .horizontalScrollBarAccess(true) } } } ``` + HTML file to be loaded: ```html - + @@ -640,15 +642,16 @@ Sets whether to display the vertical scrollbar, including the default system scr controller: web_webview.WebviewController = new web_webview.WebviewController() build() { Column() { - Web({ src: 'www.example.com', controller: this.controller }) + Web({ src: $rawfile('index.html'), controller: this.controller }) .verticalScrollBarAccess(true) } } } ``` + HTML file to be loaded: ```html - + @@ -669,6 +672,11 @@ Sets whether to display the vertical scrollbar, including the default system scr ``` +### password + +password(password: boolean) + +Sets whether the password should be saved. This API is a void API. ### cacheMode @@ -1236,6 +1244,18 @@ Sets whether to enable forcible dark mode for the web page. By default, this fea } ``` +### tableData + +tableData(tableData: boolean) + +Sets whether form data should be saved. This API is a void API. + +### wideViewModeAccess + +wideViewModeAccess(wideViewModeAccess: boolean) + +Sets whether to support the viewport attribute of the HTML **\** tag. This API is a void API. + ### pinchSmooth9+ pinchSmooth(isEnabled: boolean) @@ -1420,7 +1440,7 @@ Called when **alert()** is invoked to display an alert dialog box on the web pag controller: web_webview.WebviewController = new web_webview.WebviewController() build() { Column() { - Web({ src: $rawfile("xxx.html"), controller: this.controller }) + Web({ src: $rawfile("index.html"), controller: this.controller }) .onAlert((event) => { console.log("event.url:" + event.url) console.log("event.message:" + event.message) @@ -1450,8 +1470,9 @@ Called when **alert()** is invoked to display an alert dialog box on the web pag } ``` - ``` - + HTML file to be loaded: + ```html + @@ -1502,7 +1523,7 @@ Called when this page is about to exit after the user refreshes or closes the pa build() { Column() { - Web({ src: $rawfile("xxx.html"), controller: this.controller }) + Web({ src: $rawfile("index.html"), controller: this.controller }) .onBeforeUnload((event) => { console.log("event.url:" + event.url) console.log("event.message:" + event.message) @@ -1532,8 +1553,9 @@ Called when this page is about to exit after the user refreshes or closes the pa } ``` - ``` - + HTML file to be loaded: + ```html + @@ -1584,7 +1606,7 @@ Called when **confirm()** is invoked by the web page. build() { Column() { - Web({ src: $rawfile("xxx.html"), controller: this.controller }) + Web({ src: $rawfile("index.html"), controller: this.controller }) .onConfirm((event) => { console.log("event.url:" + event.url) console.log("event.message:" + event.message) @@ -1614,8 +1636,9 @@ Called when **confirm()** is invoked by the web page. } ``` - ``` - + HTML file to be loaded: + ```html + @@ -1673,7 +1696,7 @@ onPrompt(callback: (event?: { url: string; message: string; value: string; resul build() { Column() { - Web({ src: $rawfile("xxx.html"), controller: this.controller }) + Web({ src: $rawfile("index.html"), controller: this.controller }) .onPrompt((event) => { console.log("url:" + event.url) console.log("message:" + event.message) @@ -1704,8 +1727,9 @@ onPrompt(callback: (event?: { url: string; message: string; value: string; resul } ``` - ``` - + HTML file to be loaded: + ```html + @@ -1776,6 +1800,8 @@ Called to notify the host application of a JavaScript console message. onDownloadStart(callback: (event?: { url: string, userAgent: string, contentDisposition: string, mimetype: string, contentLength: number }) => void) +Instructs the main application to start downloading a file. + **Parameters** | Name | Type | Description | @@ -2084,6 +2110,26 @@ Called when loading of the web page is complete. This API is used by an applicat } ``` +### onSslErrorReceive(deprecated) + +onSslErrorReceive(callback: (event?: { handler: Function, error: object }) => void) + +Called when an SSL error occurs during resource loading. + +> **NOTE** +> +> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [onSslErrorEventReceive9+](#onsslerroreventreceive9) instead. + +### onFileSelectorShow(deprecated) + +onFileSelectorShow(callback: (event?: { callback: Function, fileSelector: object }) => void) + +Called to process an HTML form whose input type is **file**, in response to the tapping of the **Select File** button. + +> **NOTE** +> +> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [onShowFileSelector9+](#onshowfileselector9) instead. + ### onRenderExited9+ onRenderExited(callback: (event?: { renderExitReason: RenderExitReason }) => void) @@ -3308,7 +3354,7 @@ Called when the **\** component is about to access a URL. This API is used | Name | Type | Description | | ------- | ---------------------------------------- | --------- | -| request | [Webresourcerequest](#webresourcerequest) | Information about the URL request.| +| request | [WebResourceRequest](#webresourcerequest) | Information about the URL request.| **Return value** @@ -4280,6 +4326,7 @@ Enumerates the error codes returned by **onSslErrorEventReceive** API. | Name | Description | Remarks | | --------- | ------------- | -------------------------- | | MidiSysex | MIDI SYSEX resource.| Currently, only permission events can be reported. MIDI devices are not yet supported.| +| VIDEO_CAPTURE10+ | Video capture resource, such as a camera.| | ## WebDarkMode9+ | Name | Description | @@ -4933,6 +4980,7 @@ This API is deprecated since API version 9. You are advised to use [registerJava } ``` + HTML file to be loaded: ```html @@ -4993,7 +5041,7 @@ This API is deprecated since API version 9. You are advised to use [runJavaScrip } } ``` - + HTML file to be loaded: ```html @@ -5009,7 +5057,6 @@ This API is deprecated since API version 9. You are advised to use [runJavaScrip } - ``` ### stop(deprecated) @@ -5075,17 +5122,12 @@ This API is deprecated since API version 9. You are advised to use [clearHistory 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. ### setCookie(deprecated) -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. -This API is deprecated since API version 9. You are advised to use [setCookie9+](../apis/js-apis-webview.md#setcookie) instead. +setCookie(): boolean -**Parameters** +Sets the cookie. This API returns the result synchronously. Returns **true** if the operation is successful; returns **false** otherwise. -| Name | Type | Mandatory | Default Value | Description | -| ----- | ------ | ---- | ---- | ----------------- | -| url | string | Yes | - | URL of the cookie to set. A complete URL is recommended.| -| value | string | Yes | - | Value of the cookie to set. | +This API is deprecated since API version 9. You are advised to use [setCookie9+](../apis/js-apis-webview.md#setcookie) instead. **Return value** @@ -5093,31 +5135,12 @@ This API is deprecated since API version 9. You are advised to use [setCookie { - let result = this.controller.getCookieManager().setCookie("https://www.example.com", "a=b") - console.log("result: " + result) - }) - Web({ src: 'www.example.com', controller: this.controller }) - } - } - } - ``` ### saveCookie(deprecated) + saveCookie(): boolean Saves the cookies in the memory to the drive. This API returns the result synchronously. + This API is deprecated since API version 9. You are advised to use [saveCookieAsync9+](../apis/js-apis-webview.md#savecookieasync) instead. **Return value** @@ -5125,25 +5148,3 @@ This API is deprecated since API version 9. You are advised to use [saveCookieAs | Type | Description | | ------- | -------------------- | | boolean | Operation result.| - -**Example** - - ```ts - // xxx.ets - @Entry - @Component - struct WebComponent { - controller: WebController = new WebController() - - build() { - Column() { - Button('saveCookie') - .onClick(() => { - let result = this.controller.getCookieManager().saveCookie() - console.log("result: " + result) - }) - Web({ src: 'www.example.com', controller: this.controller }) - } - } - } - ``` -- GitLab