display received message send from ets
+ + + ``` diff --git a/zh-cn/application-dev/web/web-component-overview.md b/zh-cn/application-dev/web/web-component-overview.md new file mode 100644 index 0000000000000000000000000000000000000000..194d99267c2ab27725aa78565530dd785ca7b224 --- /dev/null +++ b/zh-cn/application-dev/web/web-component-overview.md @@ -0,0 +1,14 @@ +# Web组件概述 + + +Web组件用于在应用程序中显示Web页面内容，为开发者提供页面加载、页面交互、页面调试等能力。 + + +- 页面加载：Web组件提供基础的前端页面加载的能力，包括加载网络页面、本地页面、Html格式文本数据。 + +- 页面交互：Web组件提供丰富的页面交互的方式，包括：设置前端页面深色模式，新窗口中加载页面，位置权限管理，Cookie管理，应用侧使用前端页面JavaScript等能力。 + +- 页面调试：Web组件支持使用Devtools工具调试前端页面。 + + +下面通过常见使用场景举例，来具体介绍Web组件功能特性。 diff --git a/zh-cn/application-dev/web/web-cookie-and-data-storage-mgmt.md b/zh-cn/application-dev/web/web-cookie-and-data-storage-mgmt.md new file mode 100644 index 0000000000000000000000000000000000000000..8f8dd1357c30b4c51a0434ffb8db34b029345eaf --- /dev/null +++ b/zh-cn/application-dev/web/web-cookie-and-data-storage-mgmt.md @@ -0,0 +1,131 @@ +# 管理Cookie及数据存储 + + +## Cookie管理 + +Cookie是网络访问过程中，由服务端发送给客户端的一小段数据。客户端可持有该数据，并在后续访问该服务端时，方便服务端快速对客户端身份、状态等进行识别。 + +Web组件提供了WebCookieManager类，用于管理Web组件的Cookie信息。Cookie信息保存在应用沙箱路径下/proc/{pid}/root/data/storage/el2/base/cache/web/Cookiesd的文件中。 + +下面以[setCookie()](../reference/apis/js-apis-webview.md#setcookie)接口举例，为“www.example.com”设置单个Cookie的值“value=test”。其他Cookie的相关功能及使用，请参考[WebCookieManager()](../reference/apis/js-apis-webview.md#webcookiemanager)接口文档。 + + +```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('setCookie') + .onClick(() => { + try { + web_webview.WebCookieManager.setCookie('https://www.example.com', 'value=test'); + } catch (error) { + console.error(`ErrorCode: ${error.code}, Message: ${error.message}`); + } + }) + Web({ src: 'www.example.com', controller: this.controller }) + } + } +} +``` + + +## 缓存与存储管理 + +在访问网站时，网络资源请求是相对比较耗时的。开发者可以通过Cache、Dom Storage等手段将资源保持至本地，以提升访问同一网站的速度。 + + +### Cache + +使用[cacheMode()](../reference/arkui-ts/ts-basic-components-web.md#cachemode%E6%9E%9A%E4%B8%BE%E8%AF%B4%E6%98%8E)配置页面资源的缓存模式，Web组件为开发者提供四种缓存模式，分别为： + +- Default : 优先使用未过期的缓存，如果缓存不存在，则从网络获取。 + +- None : 加载资源使用cache，如果cache中无该资源则从网络中获取。 + +- Online : 加载资源不使用cache，全部从网络中获取。 + +- Only ：只从cache中加载资源。 + + +在下面的示例中，选用缓存设置为None模式。 + + + +```ts +// xxx.ets +import web_webview from '@ohos.web.webview'; + +@Entry +@Component +struct WebComponent { + @State mode: CacheMode = CacheMode.None; + controller: web_webview.WebviewController = new web_webview.WebviewController(); + build() { + Column() { + Web({ src: 'www.example.com', controller: this.controller }) + .cacheMode(this.mode) + } + } +} +``` + + + 同时，为了获取最新资源，开发者可以通过[removeCache()](../reference/apis/js-apis-webview.md#removecache)接口清除已经缓存的资源，示例代码如下： + +```ts +// xxx.ets +import web_webview from '@ohos.web.webview'; + +@Entry +@Component +struct WebComponent { + @State mode: CacheMode = CacheMode.None; + controller: web_webview.WebviewController = new web_webview.WebviewController(); + build() { + Column() { + Button('removeCache') + .onClick(() => { + try { + // 设置为true时同时清除rom和ram中的缓存，设置为false时只清除ram中的缓存 + this.controller.removeCache(true); + } catch (error) { + console.error(`ErrorCode: ${error.code}, Message: ${error.message}`); + } + }) + Web({ src: 'www.example.com', controller: this.controller }) + .cacheMode(this.mode) + } + } +} +``` + + +### Dom Storage + +Dom Storage包含了Session Storage和Local Storage两类。前者为临时数据，其存储与释放跟随会话生命周期；后者为可持久化数据，落盘在应用目录下。两者的数据均通过Key-Value的形式存储，通常在访问需要客户端存储的页面时使用。开发者可以通过Web组件的属性接口[domStorageAccess()](../reference/arkui-ts/ts-basic-components-web.md#domstorageaccess)进行使能配置，示例如下： + + + +```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 }) + .domStorageAccess(true) + } + } +} +``` diff --git a/zh-cn/application-dev/web/web-debugging-with-devtools.md b/zh-cn/application-dev/web/web-debugging-with-devtools.md new file mode 100644 index 0000000000000000000000000000000000000000..2917bca7bb527dd54af497783ad06faf2bb802f7 --- /dev/null +++ b/zh-cn/application-dev/web/web-debugging-with-devtools.md @@ -0,0 +1,45 @@ +# 使用Devtools工具调试前端页面 + + +Web组件支持使用DevTools工具调试前端页面。DevTools是一个 Web前端开发调试工具，提供了电脑上调试移动设备前端页面的能力。开发者通过[setWebDebuggingAccess()](../reference/apis/js-apis-webview.md#setwebdebuggingaccess)接口开启Web组件前端页面调试能力，利用DevTools工具可以在电脑上调试移动设备上的前端网页。 + + +使用DevTools工具，可以执行以下步骤： + + +1. 在应用代码中开启Web调试开关，具体如下： + + ```ts + // xxx.ets + import web_webview from '@ohos.web.webview'; + + @Entry + @Component + struct WebComponent { + controller: web_webview.WebviewController = new web_webview.WebviewController(); + aboutToAppear() { + // 配置web开启调试模式 + web_webview.WebviewController.setWebDebuggingAccess(true); + } + build() { + Column() { + Web({ src: 'www.example.com', controller: this.controller }) + } + } + } + ``` + +2. 将设备连接上电脑，在电脑端配置端口映射，配置方法如下： + + ``` + // 添加映射 + hdc fport tcp:9222 tcp:9222 + // 查看映射 + hdc fport ls + ``` + +3. 在电脑端chrome浏览器地址栏中输入chrome://inspect/\#devices，页面识别到设备后，就可以开始页面调试。调试效果如下： + + **图1** 页面调试效果图 + +  diff --git a/zh-cn/application-dev/web/web-file-upload.md b/zh-cn/application-dev/web/web-file-upload.md new file mode 100644 index 0000000000000000000000000000000000000000..d2d37e6734fabb5f8dabd3a1df04a0ed62c20c89 --- /dev/null +++ b/zh-cn/application-dev/web/web-file-upload.md @@ -0,0 +1,52 @@ +# 上传文件 + + +Web组件支持前端页面选择文件上传功能，应用开发者可以使用[onShowFileSelector()](../reference/arkui-ts/ts-basic-components-web.md#onshowfileselector9)接口来处理前端页面文件上传的请求。 + + +下面的示例中，当用户在前端页面点击文件上传按钮，应用侧在[onShowFileSelector()](../reference/arkui-ts/ts-basic-components-web.md#onshowfileselector9)接口中收到文件上传请求，在此接口中开发者将上传的本地文件路径设置给前端页面。 + + +- 应用侧代码。 + + ```ts + // xxx.ets + import web_webview from '@ohos.web.webview'; + @Entry + @Component + struct WebComponent { + controller: WebController = new WebController() + build() { + Column() { + // 加载本地local.html页面 + Web({ src: $rawfile('local.html'), controller: this.controller }) + .onShowFileSelector((event) => { + // 开发者设置要上传的文件路径 + let fileList: Array位置信息
+ + + + + ``` + + +- 应用代码。 + + ```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:$rawfile('getLocation.html'), controller:this.controller }) + .geolocationAccess(true) + .onGeolocationShow((event) => { // 地理位置权限申请通知 + AlertDialog.show({ + title: '位置权限请求', + message: '是否允许获取位置信息', + primaryButton: { + value: 'cancel', + action: () => { + event.geolocation.invoke(event.origin, false, false); // 不允许此站点地理位置权限请求 + } + }, + secondaryButton: { + value: 'ok', + action: () => { + event.geolocation.invoke(event.origin, true, false); // 允许此站点地理位置权限请求 + } + }, + cancel: () => { + event.geolocation.invoke(event.origin, false, false); // 不允许此站点地理位置权限请求 + } + }) + }) + } + } + } + ``` diff --git a/zh-cn/application-dev/web/web-in-app-frontend-page-function-invoking.md b/zh-cn/application-dev/web/web-in-app-frontend-page-function-invoking.md new file mode 100644 index 0000000000000000000000000000000000000000..2a490281b417a51f408e09acf18b3e62c66a917e --- /dev/null +++ b/zh-cn/application-dev/web/web-in-app-frontend-page-function-invoking.md @@ -0,0 +1,48 @@ +# 应用侧调用前端页面函数 + + +应用侧可以通过[runJavaScript()](../reference/apis/js-apis-webview.md#runjavascript)方法调用前端页面的JavaScript相关函数。 + + +在下面的示例中，点击应用侧的“runJavaScript”按钮时，来触发前端页面的htmlTest()方法。 + + +- 前端页面代码。 + + ```html + + + + + + + + ``` + + +- 应用侧代码。 + + ```ts + // xxx.ets + import web_webview from '@ohos.web.webview'; + + @Entry + @Component + struct WebComponent { + webviewController: web_webview.WebviewController = new web_webview.WebviewController(); + + build() { + Column() { + Web({ src: $rawfile('index.html'), controller: this.webviewController}) + Button('runJavaScript') + .onClick(() => { + this.webviewController.runJavaScript('htmlTest()'); + }) + } + } + } + ``` diff --git a/zh-cn/application-dev/web/web-in-page-app-function-invoking.md b/zh-cn/application-dev/web/web-in-page-app-function-invoking.md new file mode 100644 index 0000000000000000000000000000000000000000..caffe3d2cc2a18efae36fd67650113202e5e4d2d --- /dev/null +++ b/zh-cn/application-dev/web/web-in-page-app-function-invoking.md @@ -0,0 +1,113 @@ +# 前端页面调用应用侧函数 + + +开发者使用Web组件将应用侧代码注册到前端页面中，注册完成之后，前端页面中使用注册的对象名称就可以调用应用侧的函数，实现在前端页面中调用应用侧方法。 + + +注册应用侧代码有两种方式，一种在Web组件初始化使用调用，使用[javaScriptProxy()](../reference/arkui-ts/ts-basic-components-web.md#javascriptproxy)接口。另外一种在Web组件初始化完成后调用，使用[registerJavaScriptProxy()](../reference/apis/js-apis-webview.md#registerjavascriptproxy)接口。 + + +在下面的示例中，将test()方法注册在前端页面中， 该函数可以在前端页面触发运行。 + + +- [javaScriptProxy()](../reference/arkui-ts/ts-basic-components-web.md#javascriptproxy)接口使用示例如下。 + + ```ts + // xxx.ets + import web_webview from '@ohos.web.webview'; + + @Entry + @Component + struct WebComponent { + webviewController: web_webview.WebviewController = new web_webview.WebviewController(); + // 声明需要注册的对象 + testObj = { + test: () => { + return 'ArkTS Hello World!'; + } + } + + build() { + Column() { + // web组件加载本地index.html页面 + Web({ src: $rawfile('index.html'), controller: this.webviewController}) + // 将对象注入到web端 + .javaScriptProxy({ + object: this.testObj, + name: "testObjName", + methodList: ["test"], + controller: this.webviewController + }) + } + } + } + ``` + + +- 应用侧使用registerJavaScriptProxy()接口注册。 + + ```ts + // xxx.ets + import web_webview from '@ohos.web.webview'; + + @Entry + @Component + struct Index { + webviewController: web_webview.WebviewController = new web_webview.WebviewController(); + testObj = { + test: (data) => { + return "ArkUI Web Component"; + }, + toString: () => { + console.info('Web Component toString'); + } + } + + build() { + Column() { + Button('refresh') + .onClick(() => { + try { + this.webviewController.refresh(); + } catch (error) { + console.error(`Errorcode: ${error.code}, Message: ${error.message}`); + } + }) + Button('Register JavaScript To Window') + .onClick(() => { + try { + this.webviewController.registerJavaScriptProxy(this.testObj, "objName", ["test", "toString"]); + } catch (error) { + console.error(`Errorcode: ${error.code}, Message: ${error.message}`); + } + }) + Web({ src: $rawfile('index.html'), controller: this.webviewController }) + } + } + } + ``` + + > **说明：** + > + > 使用[registerJavaScriptProxy()](../reference/apis/js-apis-webview.md#registerjavascriptproxy)接口注册方法时，注册后需调用[refresh()](../reference/apis/js-apis-webview.md#refresh)接口生效。 + + +- index.htm前端页面触发应用侧代码。 + + ```html + + + + + + + + + + ``` diff --git a/zh-cn/application-dev/web/web-open-in-new-window.md b/zh-cn/application-dev/web/web-open-in-new-window.md new file mode 100644 index 0000000000000000000000000000000000000000..99a244544598060f16881ab6b020eb431e6f8ecf --- /dev/null +++ b/zh-cn/application-dev/web/web-open-in-new-window.md @@ -0,0 +1,69 @@ +# 在新窗口中打开页面 + + +Web组件提供了在新窗口打开页面的能力，开发者可以通过[multiWindowAccess()](../reference/arkui-ts/ts-basic-components-web.md#multiwindowaccess9)接口来设置是否允许网页在新窗口打开。当有新窗口打开时，应用侧会在[onWindowNew()](../reference/arkui-ts/ts-basic-components-web.md#onwindownew9)接口中收到Web组件新窗口事件，开发者需要在此接口事件中，新建窗口来处理Web组件窗口请求。 + + +> **说明：** +> +> - [allowWindowOpenMethod()](../reference/arkui-ts/ts-basic-components-web.md#allowwindowopenmethod9)接口设置为true时，前端页面通过JavaScript函数调用的方式打开新窗口。 +> +> - 如果开发者在[onWindowNew()](../reference/arkui-ts/ts-basic-components-web.md#onwindownew9)接口通知中不需要打开新窗口，需要将[ControllerHandler.setWebController()](../reference/arkui-ts/ts-basic-components-web.md#onwindownew9)接口返回值设置成null。 + + +如下面的本地示例，当用户点击“新窗口中打开网页”按钮时，应用侧会在[onWindowNew()](../reference/arkui-ts/ts-basic-components-web.md#onwindownew9)接口中收到Web组件新窗口事件。 + + +- 应用侧代码。 + + 创建新窗口的方法可参考[Web开发相关例子](https://gitee.com/openharmony/applications_app_samples/tree/master/code/BasicFeature/Web/Browser)。 + + ```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:$rawfile("window.html"), controller: this.controller }) + .multiWindowAccess(true) + .onWindowNew((event) => { + console.info("onWindowNew..."); + var popController: web_webview.WebviewController = new web_webview.WebviewController(); + // 开发者需要在此处新建窗口,跟popController关联，并且将popController返回给Web组件。如果不需要打开新窗口请将返回值设置为event.handler.setWebController(null); + event.handler.setWebController(popController); + }) + } + } + } + ``` + + +- window.html页面代码。 + + ```html + + + + +Hello World
+ + + ``` + + +## 加载HTML格式的文本数据 + +Web组件可以通过[loadData()](../reference/apis/js-apis-webview.md#loaddata)接口实现加载HTML格式的文本数据。当开发者不需要加载整个页面，只需要显示一些页面片段时，可通过此功能来快速加载页面。 + + + +```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('loadData') + .onClick(() => { + try { + // 点击按钮时，通过loadData，加载HTML格式的文本数据 + this.controller.loadData( + 'Source:source', + 'text/html', + 'UTF-8' + ); + } catch (error) { + console.error(`ErrorCode: ${error.code}, Message: ${error.message}`); + } + }) + // 组件创建时，加载www.example.com + Web({ src: 'www.example.com', controller: this.controller }) + } + } +} +``` diff --git a/zh-cn/application-dev/web/web-redirection-and-browsing-history-mgmt.md b/zh-cn/application-dev/web/web-redirection-and-browsing-history-mgmt.md new file mode 100644 index 0000000000000000000000000000000000000000..4d64482bf4e2ed1751e2e1f120064d481fa670cf --- /dev/null +++ b/zh-cn/application-dev/web/web-redirection-and-browsing-history-mgmt.md @@ -0,0 +1,157 @@ +# 管理页面跳转及浏览记录导航 + + +## 历史记录导航 + +使用者在前端页面点击网页中的链接时，Web组件默认会自动打开并加载目标网址。当前端页面替换为新的加载链接时，会自动记录已经访问的网页地址。可以通过[forward()](../reference/apis/js-apis-webview.md#forward)和[backward()](../reference/apis/js-apis-webview.md#backward)接口向前/向后浏览上一个/下一个历史记录。 + + 在下面的示例中，点击应用的按钮来触发前端页面的后退操作。 + +```ts +// xxx.ets +import web_webview from '@ohos.web.webview'; + +@Entry +@Component +struct WebComponent { + webviewController: web_webview.WebviewController = new web_webview.WebviewController(); + build() { + Column() { + Button('loadData') + .onClick(() => { + if (this.webviewController.accessBackward()) { + this.webviewController.backward(); + return true; + } + }) + Web({ src: 'https://www.example.com/cn/', controller: this.webviewController}) + } + } +} +``` + + +如果存在历史记录，[accessBackward()](../reference/apis/js-apis-webview.md#accessbackward)接口会返回true。同样，您可以使用[accessForward()](../reference/apis/js-apis-webview.md#accessforward)接口检查是否存在前进的历史记录。如果您不执行检查，那么当用户浏览到历史记录的末尾时，调用[forward()](../reference/apis/js-apis-webview.md#forward)和[backward()](../reference/apis/js-apis-webview.md#backward)接口时将不执行任何操作。 + + +## 页面跳转 + +当点击网页中的链接需要跳转到应用内其他页面时，可以通过使用Web组件的[onUrlLoadIntercept()](../reference/arkui-ts/ts-basic-components-web.md#onurlloadintercept)接口来实现。 + +在下面的示例中，应用首页Index.ets加载前端页面route.html，在前端route.html页面点击超链接，可跳转到应用的ProfilePage.ets页面。 + +- 应用首页index.ets页面代码。 + + ```ts + // index.ets + import web_webview from '@ohos.web.webview'; + import router from '@ohos.router'; + @Entry + @Component + struct WebComponent { + webviewController: web_webview.WebviewController = new web_webview.WebviewController(); + + build() { + Column() { + Web({ src: $rawfile('route.html'), controller: this.webviewController }) + .onUrlLoadIntercept((event) => { + let url: string = event.data as string; + if (url.indexOf('native://') === 0) { + // 跳转其他界面 + router.pushUrl({ url:url.substring(9) }) + return true; + } + return false; + }) + } + } + } + ``` + +- route.html前端页面代码。 + + ```html + + + + +