From 230a5b04b66ffb97f5c51124c6240d6869e2a341 Mon Sep 17 00:00:00 2001 From: lixingchi1 Date: Fri, 25 Feb 2022 15:15:59 +0800 Subject: [PATCH] add web component js api. Signed-off-by: lixingchi1 --- .../arkui-ts/ts-media-components-web.md | 227 ++++++++++++++---- 1 file changed, 178 insertions(+), 49 deletions(-) diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-media-components-web.md b/zh-cn/application-dev/reference/arkui-ts/ts-media-components-web.md index cce4f89bd5..c729b54fb4 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-media-components-web.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-media-components-web.md @@ -1,9 +1,9 @@ # Web >![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** ->该组件从 API Version 8 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 +>该组件从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 -提供具有网页显示能力的 Web 组件。 +提供具有网页显示能力的Web组件。 ## 权限列表 @@ -17,57 +17,58 @@ ohos.permission.READ_USER_STORAGE ## 接口 -- Web\(options: {src: string, controller?: WebController}\) +- Web\(options: { src: string, controller?: WebController }\) - 表1 options 参数说明 + 表1 options参数说明 - | 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 | - | ---------- | ------------------------------- | ---- | ------ | -------------- | - | src | string | 是 | - | 网页资源地址。 | - | controller | [WebController](#WebController) | 否 | - | 控制器。 | + | 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 | + | ---------- | ------------------------------- | ---- | ---- | ------- | + | src | string | 是 | - | 网页资源地址。 | + | controller | [WebController](#WebController) | 否 | - | 控制器。 | > ![icon-note.gif](public_sys-resources/icon-note.gif)**说明：** > -> - 一个页面只支持一个 Web 组件，全屏显示，页面中的其他组件会被 Web 组件遮挡； > - 不支持转场动画； -> - 只支持加载 rawfile 目录下的 html 文件，不支持远程资源。 +> - 不支持音视频播放； +> - 不支持横竖屏事件。 ## 属性 -| 名称 | 参数类型 | 默认值 | 描述 | -| ----------------- | ---------------- | ------------------------------------------ | ------------------------------------------------------------ | -| javaScriptAccess | boolean | true | 是否允许执行 JavaScript 脚本，默认允许执行。 | -| fileAccess | boolean | true | 启用或禁用 Web 中可通过 file 方式访问应用中的本地文件， 默认启用。 | -| onlineImageAccess | boolean | true | 是否允许从网络加载图片 资源（通过http和http访问的资源），默认允许访问。 | -| domStorageAccess | boolean | false | 设置是否开启DOM存储API权限，默认未开启，设置为true时，WebView能够使用DOM storageAPI。 | -| imageAccess | boolean | true | 设置是否允许自动加载图片资源，默认允许。 | -| mixedMode | MixedModeContent | MixedModeContent.MIXED_CONTENT_NEVER_ALLOW | 设置是否加载http和https混合内容，默认不允许加载http和https混合内容。 | -| zoomAccess | boolean | true | 设置是否支持使用屏幕控件或手势进行缩放，默认执行缩放。 | -| geolocationAccess | boolean | true | 是否允许访问地理位置， 默认允许。 | +| 名称 | 参数类型 | 默认值 | 描述 | +| ----------------- | --------- | -------------- | ---------------------------------------- | +| domStorageAccess | boolean | false | 设置是否开启DOM Storage API权限，默认未开启。 | +| fileAccess | boolean | true | 设置是否开启Web中通过FILE方式访问应用中的本地文件， 默认启用。 | +| geolocationAccess | boolean | true | 设置是否允许访问地理位置， 默认允许访问。 | +| imageAccess | boolean | true | 设置是否允许自动加载图片资源，默认允许。 | +| javaScriptAccess | boolean | true | 设置是否允许执行JavaScript脚本，默认允许执行。 | +| mixedMode | MixedMode | MixedMode.None | 设置是否允许加载HTTP和HTTPS混合内容，默认不允许加载HTTP和HTTPS混合内容。 | +| onlineImageAccess | boolean | true | 设置是否允许从网络加载图片资源（通过HTTP和HTTPS访问的资源），默认允许访问。 | +| zoomAccess | boolean | true | 设置是否支持使用屏幕控件或手势进行缩放，默认允许执行缩放。 | > ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** > -> 不支持通用属性。 -- MixedModeContent枚举说明 +> 通用属性仅支持width、height、padding、margin、border。 +- MixedMode枚举说明 - | 名称 | 描述 | - | -------------------------------- | ------------------------------------------------------------ | - | MIXED_CONTENT_NEVER_ALLOW | 不允许加载http和https混合内容。 | - | MIXED_CONTENT_ALWAYS_ALLOW | 允许加载http和https混合内容。 | - | MIXED_CONTENT_COMPATIBILITY_MODE | 混合内容兼容性模式，一些不安全的内容可能被安全来源加载，其他类型的内容将被阻止。 | + | 名称 | 描述 | + | ---------- | ---------------------------------------- | + | All | 允许加载HTTP和HTTPS混合内容。 | + | Compatible | 混合内容兼容性模式，一些不安全的内容可能被安全来源加载，其他类型的内容将被阻止。 | + | None | 不允许加载HTTP和HTTPS混合内容。 | ## 事件 -不支持通用事件。 +通用事件仅支持onFocus。 -| 名称 | 功能描述 | -| ------------------------------------------------------------ | ------------------------------------------------------------ | -| onPageEnd(callback: (event?: { url: string }) => void) |

网页加载结束时触发该回调。
url：Web 引擎返回的 URL。

| -| onPageBegin(callback: (event?: {url: string }) => void) |

网页加载时触发该回调。
url：Web 引擎返回的 URL。

| +| 名称 | 功能描述 | +| ---------------------------------------- | ---------------------------------------- | +| onDownloadStart(callback: (event?: { url: string, userAgent: string, contentDisposition: string, mimetype: string, contentLength: number }) => void) |

下载开始时触发该回调。
url：Web引擎返回的下载URL。
userAgent：Web引擎返回的用户代理名称。
contentDisposition：Web引擎返回的响应头。
mimetype：Web引擎返回的mimetype信息。
contentLength：Web引擎返回的内容长度。

| +| onGeolocationHide(callback: () => void) |

调用onGeolocationShow时发出的地理位置权限请求被取消后触发该回调。

| +| onGeolocationShow(callback: (event?: { origin: string, geolocation: JsGeolocation }) => void) |

应用尝试使用地理位置时触发该回调，并向用户请求权限。
origin：尝试获取地理位置的Web内容的来源。
geolocation：用于请求地理位置权限。

| +| onPageBegin(callback: (event?: { url: string }) => void) |

网页加载时触发该回调。
url：Web引擎返回的URL。

| +| onPageEnd(callback: (event?: { url: string }) => void) |

网页加载结束时触发该回调。
url：Web引擎返回的URL。

| | onProgressChange(callback: (event?: { newProgress: number }) => void) |

网页加载进度变化时触发该回调。
newProgress：加载进度，取值范围为0到100的整数。

| -| onTitleReceive(callback: (event?: { title: string }) => void) |

网页主页面标题更改时触发该回调。
title：标题内容。

| -| onGeolocationHide(callback: () => void) |

调用onGeolocationShow()时发出的地理位置权限请求被取消后触发该回调。
开发者可以在该回调中实现隐藏相关UI界面的逻辑。

| -| onGeolocationShow(callback: (event?: { origin: string, geolocation: JsGeolocation }) => void) |

应用尝试使用地理位置时触发该回调，并向用户请求权限。
-origin：尝试获取地理位置的Web内容的来源。
-geolocation：用于请求地理位置权限。

| +| onTitleReceive(callback: (event?: { title: string }) => void) |

网页主页面标题更改时触发该回调。
title：标题内容。

| ### JsGeolocation 对象说明 @@ -75,9 +76,9 @@ ohos.permission.READ_USER_STORAGE - 接口 - | 接口名称 | 功能描述 | - | ------------------------------------------------------------ | ------------------------------------------------------------ | - | invoke(origin: string, allow: boolean, retain: boolean): void |

通知系统用户是否批准该应用使用地理位置权限。
-origin：尝试获取地理位置的Web内容的来源。
-allow：用户是否批准该应用使用地理位置权限。true: 允许访问，false: 不允许访问。
-retain：是否允许将地理位置权限状态保存到系统中。true: 允许，false: 不允许。

| + | 接口名称 | 功能描述 | + | ---------------------------------------- | ---------------------------------------- | + | invoke(origin: string, allow: boolean, retain: boolean): void |

通知系统用户是否批准该应用使用地理位置权限。
origin：尝试获取地理位置的Web内容的来源。
allow：用户是否批准该应用使用地理位置权限。true: 允许访问，false: 不允许访问。
retain：是否允许将地理位置权限状态保存到系统中。true: 允许，false: 不允许。

| ## WebController @@ -89,30 +90,158 @@ Web 组件的控制器。 webController: WebController = new WebController() ``` -### runJavaScript +### accessBackward + +accessBackward(): boolean + +当前页面是否可后退。 + +### accessForward + +accessForward(): boolean + +当前页面是否可前进。 + +### accessStep -runJavaScript(script: string): void +accessStep(step: number): boolean -执行 JavaScript 脚本。 +当前页面是否可前进或者后退step步。 - 参数 - | 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 | - | ------ | ------ | ---- | ---- | -------------- | - | script | string | 是 | - | JavaScript 脚本。 | + | 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 | + | ---- | ------ | ---- | ---- | --------------------- | + | step | number | 是 | - | 要跳转的步数，正数代表前进，负数代表后退。 | + +### deleteJavaScriptRegister + +deleteJavaScriptRegister(options: { name: string }): void + +清空指定对象已注册的JavaScript方法。 + +- options参数说明 + + | 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 | + | ---- | ------ | ---- | ---- | ----------------------- | + | name | string | 是 | - | 注册对象的名称，与HTML中调用的对象名一致。 | + +### backward + +backward(): void + +页面后退。 + +### forward + +forward(): void + +页面前进。 + +### getHitTest + +getHitTest(): HitTestType + +获取当前已点击的对象类型。 + +- HitTestType枚举说明 + + | 名称 | 描述 | + | ------- | -------------------------------- | + | Edit | 可编辑的区域。 | + | Email | 邮件地址。 | + | Http | HTTP网址的HTML \标签。 | + | HttpImg | HTTP网址与\标签组成的HTML \标签。 | + | Img | HTML \标签。 | + | Map | 地图地址。 | + | Phone | 电话号码。 | + | Unknown | 未知内容。 | + +### loadData + +loadData(options: { data: string, mimeType: string, encoding: string, baseUrl?: string, historyUrl?: string }): void + +加载数据。 + +- options参数说明 + + | 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 | + | ---------- | ------ | ---- | ---- | ------------------ | + | data | string | 是 | - | 需要加载的数据。 | + | mimeType | string | 是 | - | 媒体类型，格式为''\*/\*''。 | + | encoding | string | 是 | - | 编码类型。 | + | baseUrl | string | 否 | - | 基础URL。 | + | historyUrl | string | 否 | - | 历史URL。 | ### loadUrl -loadUrl(url: string): void +loadUrl(url: string, additionalHttpHeaders?: Array<{ key: string, value: string }>): void -加载 URL。 +加载URL。 - 参数 - | 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 | - | ---- | ------ | ---- | ---- | ---------- | - | url | string | 是 | - | 需要加载的 URL。 | + | 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 | + | --------------------- | ------------------------------------- | ---- | ---- | ---------- | + | url | string | 是 | - | 需要加载的 URL。 | + | additionalHttpHeaders | Array<{ key: string, value: string }> | 否 | [] | HTTP附加信息。 | + +### onActive + +onActive(): void + +页面重新激活。当Web被重新激活为活跃状态时，执行此方法。 + +### onInactive + +onInactive(): void + +页面暂停渲染。当Web被切换到后台不可见状态时，执行此方法。 + +### refresh + +refresh(): void + +刷新页面。 + +### registerJavaScriptProxy + +registerJavaScriptProxy(options: { obj: object, name: string, methodList: string[] }): void + +将JavaScript对象与方法注册到Web内核，可被已加载的HTML直接调用。注册后，须调用refresh接口生效。 + +- options 参数说明 + + | 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 | + | ---------- | -------- | ---- | ---- | ----------------------- | + | obj | object | 是 | - | 参与注册的对象。 | + | name | string | 是 | - | 注册对象的名称，与HTML中调用的对象名一致。 | + | methodList | string[] | 是 | - | 参与注册的方法。 | + +### runJavaScript + +runJavaScript(script: string, callback?: (result: string) => void): void + +执行JavaScript脚本。 + +- 参数 + + | 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 | + | -------- | ------------------------ | ---- | ---- | ------------------------------------ | + | script | string | 是 | - | JavaScript脚本。 | + | callback | (result: string) => void | 否 | - | 回调执行JavaScript脚本结果，默认result为null字符串。 | + +### requestFocus + +requestFocus(): void + +Web组件获焦。 + +### stop + +stop(): void +停止页面加载。 ## 示例 -- GitLab