diff --git a/zh-cn/application-dev/reference/apis-arkweb/arkts-apis-webview-WebviewController.md b/zh-cn/application-dev/reference/apis-arkweb/arkts-apis-webview-WebviewController.md index cca982acd28f8b8771953cff463f92dd5653eb8e..1e3609c2d31e713b77b15cac8db1009ce133f939 100644 --- a/zh-cn/application-dev/reference/apis-arkweb/arkts-apis-webview-WebviewController.md +++ b/zh-cn/application-dev/reference/apis-arkweb/arkts-apis-webview-WebviewController.md @@ -469,6 +469,40 @@ struct WebComponent { } ``` +指定baseURL +```ts +// xxx.ets +import { webview } from '@kit.ArkWeb'; +import { BusinessError } from '@kit.BasicServicesKit'; + +@Entry +@Component +struct WebComponent { + controller: webview.WebviewController = new webview.WebviewController(); + + build() { + Column() { + Button('loadData') + .onClick(() => { + try { + this.controller.loadData( + "", // 会尝试从`"https://xxx.com/" + "aa/bb.jpg"加载该图片 + "text/html", + "UTF-8", + "https://xxx.com/", + "about:blank" + ); + } catch (error) { + console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); + } + }) + Web({ src: 'www.example.com', controller: this.controller }) + } + } +} +``` + +加载在线资源 ```ts // xxx.ets import { webview } from '@kit.ArkWeb'; @@ -3397,7 +3431,7 @@ getFavicon(): image.PixelMap | 类型 | 说明 | | -------------------------------------- | ------------------------------- | -| [PixelMap](../apis-image-kit/arkts-apis-image-PixelMap.md) | 页面favicon图标的PixelMap对象。 | +| [PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7) | 页面favicon图标的PixelMap对象。 | **错误码：** @@ -4926,119 +4960,6 @@ struct WebComponent { } ``` -## setAppCustomUserAgent20+ - -static setAppCustomUserAgent(userAgent: string): void - -设置应用级自定义用户代理，会覆盖系统的用户代理，应用内所有Web组件生效。 - -当需要设置应用级自定义用户代理时，建议在Web组件创建前调用setAppCustomUserAgent方法设置User-Agent，再创建指定src的Web组件或通过[loadUrl](#loadurl)加载具体页面。 - -默认User-Agent定义与使用场景，及相关User-Agent接口定义优先级请参考[User-Agent开发指导](../../web/web-default-userAgent.md)。 - -**系统能力：** SystemCapability.Web.Webview.Core - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ---------------| ------- | ---- | ------------- | -| userAgent | string | 是 | 用户自定义代理信息。建议先使用[getDefaultUserAgent](#getdefaultuseragent14)获取当前默认用户代理，在此基础上追加自定义用户代理信息。 | - -**示例：** - -```ts -// xxx.ets -import { webview } from '@kit.ArkWeb'; -import { BusinessError } from '@kit.BasicServicesKit'; - -@Entry -@Component -struct WebComponent { - controller: webview.WebviewController = new webview.WebviewController(); - - aboutToAppear(): void { - try { - webview.WebviewController.initializeWebEngine(); - let defaultUserAgent = webview.WebviewController.getDefaultUserAgent(); - let appUA = defaultUserAgent + " appUA"; - webview.WebviewController.setAppCustomUserAgent(appUA); - } catch (error) { - console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); - } - } - - build() { - Column() { - Web({ src: 'www.example.com', controller: this.controller }) - } - } -} -``` - -## setUserAgentForHosts20+ - -static setUserAgentForHosts(userAgent: string, hosts: Array\): void - -针对特定网站设置自定义用户代理，会覆盖系统的用户代理，应用内所有Web组件生效。 - -当需要对特定网站设置自定义用户代理时，建议在Web组件创建前调用setUserAgentForHosts方法设置User-Agent，再创建指定src的Web组件或通过[loadUrl](#loadurl)加载具体页面。 - -默认User-Agent定义与使用场景，及相关User-Agent接口定义优先级请参考[User-Agent开发指导](../../web/web-default-userAgent.md)。 - -**系统能力：** SystemCapability.Web.Webview.Core - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ---------------| ------- | ---- | ------------- | -| userAgent | string | 是 | 用户自定义代理信息。建议先使用[getDefaultUserAgent](#getdefaultuseragent14)获取当前默认用户代理，在此基础上追加自定义用户代理信息。 | -| hosts | Array\ | 是 | 用户自定义代理的相关域名列表，每次调用时仅保留最新传入的列表，并限制最大条目数为两万，超出部分自动截断。 | - -**错误码：** - -以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 - -| 错误码ID | 错误信息 | -| -------- | ------------------------------------------------------------ | -| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | - -**示例：** - -```ts -// xxx.ets -import { webview } from '@kit.ArkWeb'; -import { BusinessError } from '@kit.BasicServicesKit'; - -@Entry -@Component -struct WebComponent { - controller: webview.WebviewController = new webview.WebviewController(); - - aboutToAppear(): void { - try { - webview.WebviewController.initializeWebEngine(); - let defaultUserAgent = webview.WebviewController.getDefaultUserAgent(); - let appUA = defaultUserAgent + " appUA"; - webview.WebviewController.setUserAgentForHosts( - appUA, - [ - "www.example.com", - "www.baidu.com" - ] - ); - } catch (error) { - console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); - } - } - - build() { - Column() { - Web({ src: 'www.example.com', controller: this.controller }) - } - } -} -``` - ## setConnectionTimeout11+ static setConnectionTimeout(timeout: number): void @@ -6969,10 +6890,14 @@ struct WebComponent { startCamera(): void -开启当前网页摄像头捕获。使用摄像头功能前请在module.json5中添加权限: ohos.permission.CAMERA，具体权限的添加方法请参考[在配置文件中声明权限](../../security/AccessToken/declare-permissions.md#在配置文件中声明权限)。 +开启当前网页摄像头捕获。 **系统能力：** SystemCapability.Web.Webview.Core +**需要权限：** + +使用摄像头功能前请在module.json5中添加权限: ohos.permission.CAMERA，具体权限的添加方法请参考[在配置文件中声明权限](../../security/AccessToken/declare-permissions.md)。 + **错误码：** 以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 @@ -8707,74 +8632,6 @@ struct WebComponent { } ``` -## getPageOffset20+ - -getPageOffset(): ScrollOffset - -获取网页当前的滚动偏移量（不包含过滚动偏移量）。 - -**系统能力：** SystemCapability.Web.Webview.Core - -**返回值** - -| 类型 | 说明 | -| :------------------------------ | ---------------------- | -| [ScrollOffset](./arkts-apis-webview-i.md#scrolloffset13) | 网页当前的滚动偏移量（不包含过滚动偏移量）。 | - -**示例：** - -```ts -import { webview } from '@kit.ArkWeb'; - -@Entry -@Component -struct WebComponent { - controller: webview.WebviewController = new webview.WebviewController(); - - build() { - Column() { - Web({ src: $rawfile('index.html'), controller: this.controller }) - .onScroll((event) => { - console.log("getPageOffset x:" + this.controller.getPageOffset().x + ",y:" + - this.controller.getPageOffset().y); - }) - } - } -} -``` -```html - - - - - - - - -
webArea
-
webArea
-
webArea
-
webArea
-
webArea
-
webArea
-
webArea
- - -``` - ## getLastHitTest18+ getLastHitTest(): HitTestValue @@ -8827,298 +8684,6 @@ struct WebComponent { } ``` -## getAttachState20+ - -getAttachState(): ControllerAttachState - -查询当前WebViewController是否绑定一个Web组件。 - -**系统能力：** SystemCapability.Web.Webview.Core - -**返回值：** - -| 类型 | 说明 | -| ------------ | -------------------- | -| [ControllerAttachState](./arkts-apis-webview-i.md#controllerattachstate20) | WebViewController与Web组件的绑定状态。 | - -**示例：** -点击Button可以获取当前WebViewController的绑定状态并输出日志。 - -```ts -// xxx.ets -import { webview } from '@kit.ArkWeb'; -import { BusinessError } from '@kit.BasicServicesKit'; - -@Entry -@Component -struct WebComponent { - controller: webview.WebviewController = new webview.WebviewController(); - - build() { - Column() { - Button('getAttachState') - .onClick(() => { - try { - if (this.controller.getAttachState() == webview.ControllerAttachState.ATTACHED) { - console.log('Controller is attached.'); - this.controller.refresh(); - } else { - console.log('Controller is unattached.'); - this.controller.refresh(); - } - } catch (error) { - console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); - } - }) - Web({ src: 'www.example.com', controller: this.controller }) - } - } -} -``` -## on('controllerAttachStateChange')20+ - -on(type: 'controllerAttachStateChange', callback: Callback<ControllerAttachState>): void - -注册WebViewController绑定状态事件，通过Callback方式获取WebViewController绑定状态的变化通知。 - -**系统能力：** SystemCapability.Web.Webview.Core - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------- | -------- | -------- | -| type | string | 是 | 表示注册WebViewController绑定状态事件，固定为"controllerAttachStateChange"。 | -| callback | Callback<[ControllerAttachState](./arkts-apis-webview-i.md#controllerattachstate20)> | 是 | WebViewController绑定状态改变时的回调函数。 | - -**示例：** - -请参考[off](#offcontrollerattachstatechange20)。 - -## off('controllerAttachStateChange')20+ - -off(type: 'controllerAttachStateChange', callback?: Callback<ControllerAttachState>): void - -取消WebViewController绑定状态事件的注册，取消后将不再接收Callback通知。 - -**系统能力：** SystemCapability.Web.Webview.Core - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------- | -------- | -------- | -| type | string | 是 | 表示注册WebViewController绑定状态事件，固定为"controllerAttachStateChange"。 | -| callback | Callback<[ControllerAttachState](./arkts-apis-webview-i.md#controllerattachstate20)> | 否 | WebViewController绑定状态发生改变时的回调函数，默认情况下不填写回调函数。如果填写了Callback，将仅取消注册该特定的回调。如果不填写Callback，将取消注册所有回调。 | - -**示例：** - -on可以注册多个回调，当绑定状态改变后会获取当前的绑定状态并触发这些回调。off可以取消注册某个回调，也可以取消注册所有回调。 - -```ts -// xxx.ets -import { webview } from '@kit.ArkWeb'; -import { BusinessError } from '@kit.BasicServicesKit'; - -@Entry -@Component -struct WebComponent { - controller: webview.WebviewController = new webview.WebviewController(); - - aboutToAppear() { - // 构建回调函数 - const handleControllerAttachStateChange = (state: webview.ControllerAttachState) => { - if (state == webview.ControllerAttachState.UNATTACHED) { - console.log('handleControllerAttachStateChange: Controller is unattached.'); - } else { - console.log('handleControllerAttachStateChange: Controller is attached.'); - } - }; - try { - // 注册回调以接收controller绑定状态更改通知 - this.controller.on('controllerAttachStateChange', handleControllerAttachStateChange); - // 取消指定注册回调 - this.controller.off('controllerAttachStateChange', handleControllerAttachStateChange); - } catch (error) { - console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); - } - try { - // 注册回调以接收controller绑定状态更改通知 - this.controller.on('controllerAttachStateChange', (state: webview.ControllerAttachState)=>{ - if (state == webview.ControllerAttachState.UNATTACHED) { - console.log('Controller is unattached.'); - } else { - console.log('Controller is attached.'); - // 取消所有注册回调 - this.controller.off('controllerAttachStateChange'); - } - }) - } catch (error) { - console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); - } - } - - build() { - Column() { - Web({ src: 'www.example.com', controller: this.controller }) - } - } -} -``` -## waitForAttached20+ - -waitForAttached(timeout: number):Promise<ControllerAttachState> - -异步等待WebViewController与Web组件绑定完成，绑定完成或超时触发回调，通过Promise方式返回当前[ControllerAttachState](./arkts-apis-webview-i.md#controllerattachstate20)状态。 - -**系统能力：** SystemCapability.Web.Webview.Core - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------------- | --------------------------------------- | ---- | ----------------- | -| timeout | number | 是 | 异步等待时长（单位ms，取值范围0-300000）。 | - -**返回值：** - -| 类型 | 说明 | -| ------------------------------ | ----------------------------- | -| Promise<[ControllerAttachState](./arkts-apis-webview-i.md#controllerattachstate20)> | Promise实例，返回当前[ControllerAttachState](./arkts-apis-webview-i.md#controllerattachstate20)状态。 | - - -**示例：** - -在初始化阶段设置WebViewController等待绑定完成，超时时间为1000ms。若绑定完成或者超时则会触发回调。 - -```ts -// xxx.ets -import { webview } from '@kit.ArkWeb'; -import { BusinessError } from '@kit.BasicServicesKit'; - -@Entry -@Component -struct WebComponent { - controller: webview.WebviewController = new webview.WebviewController(); - - async aboutToAppear() { - this.controller.waitForAttached(1000).then((state: webview.ControllerAttachState)=>{ - if (state == webview.ControllerAttachState.ATTACHED) { - console.log('Controller is attached.'); - this.controller.refresh(); - } - }) - try { - const state = await this.controller.waitForAttached(1000); - if (state == webview.ControllerAttachState.ATTACHED) { - console.log('Controller is attached.'); - this.controller.refresh(); - } - } catch (error) { - console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); - } - } - - build() { - Column() { - Web({ src: 'www.example.com', controller: this.controller }) - } - } -} -``` - -## setWebDebuggingAccess20+ - -static setWebDebuggingAccess(webDebuggingAccess: boolean, port: number): void - -设置是否启用无线网页调试功能，默认不开启。 - -* 当没有指定端口port时，该接口等同于[setWebDebuggingAccess](#setwebdebuggingaccess)接口，ArkWeb会启动一个本地domain socket监听。 -* 当指定了端口port时，ArkWeb会启动一个tcp socket监听。这时可以无线调试网页。详情请参考[无线调试](../../web/web-debugging-with-devtools.md#无线调试)。 - -由于小于1024的端口号作为熟知或系统端口，在操作系统上需要特权才能开启，因此port的取值必须大于1024，否则该接口会抛出异常。 - -安全提示：启用网页调试功能可以让用户检查修改Web页面内部状态，存在安全隐患，不建议在应用正式发布版本中启用。 - -**系统能力：** SystemCapability.Web.Webview.Core - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------------------ | ------- | ---- | ------------- | -| webDebuggingAccess | boolean | 是 | 设置是否启用网页调试功能。
true表示开启网页调试功能，false表示关闭网页调试功能。 | -| port | number | 是 | 指定devtools服务的tcp端口号。如果没有指定port，那么该接口等同于[setWebDebuggingAccess](#setwebdebuggingaccess)接口。
取值范围: (1024, 65535]
如果port的值在区间[0, 1024]内，则会抛出BusinessError异常，错误码为17100023。 | - - -**错误码：** - -以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[webview错误码](errorcode-webview.md)。 - -| 错误码ID | 错误信息 | -| -------- | ------------------------------------------------------------ | -| 17100023 | The port number is not within the allowed range. | - -**示例：** - -```ts -// xxx.ets -import { webview } from '@kit.ArkWeb'; -import { BusinessError } from '@kit.BasicServicesKit'; - -@Entry -@Component -struct WebComponent { - controller: webview.WebviewController = new webview.WebviewController(); - - aboutToAppear(): void { - try { - webview.WebviewController.setWebDebuggingAccess(true, 8888); - } catch (error) { - console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); - } - } - - build() { - Column() { - Web({ src: 'www.example.com', controller: this.controller }) - } - } -} -``` - -## getProgress20+ - -getProgress(): number - -获取当前网页加载进度。 - -**系统能力：** SystemCapability.Web.Webview.Core - -**返回值** - -| 类型 | 说明 | -| :------------------------------ | ---------------------- | -| number | 当前页面加载进度，取值范围[0, 100] | - -**示例：** - -```ts -import { webview } from '@kit.ArkWeb'; - -@Entry -@Component -struct WebComponent { - controller: webview.WebviewController = new webview.WebviewController(); - - build() { - Column() { - Web({ src: 'www.example.com', controller: this.controller }) - .onPageBegin(() => { - let curProgress = this.controller.getProgress(); - console.info("current page loading progress is :" + curProgress); - }) - } - } -} -``` - ## getHitTest(deprecated) getHitTest(): WebHitTestType @@ -9228,69 +8793,4 @@ struct WebComponent { } } } -``` - -## avoidVisibleViewportBottom20+ - -avoidVisibleViewportBottom(avoidHeight: number): void - -设置Web网页可视视口底部避让高度。 - -> **说明：** -> -> - avoidHeight有效值区间为[0, Web组件高度]，超出有效值区间时取边界值。 -> - 该接口高度设置为非0时，Web组件位置和尺寸不变，可视视口向上避让avoidHeight，表现为Web网页内容抬升avoidHeight。该接口一般用于应用自定义网页底部避让区，不建议和点击web网页可编辑区拉起键盘的场景同时使用。同时使用时，键盘弹起避让模式将使用OVERLAYS_CONTENT。 -> - 该接口高度设置为0时，Web网页内容可恢复，键盘弹起避让模式将使用[keyboardAvoidMode()](./arkts-basic-components-web-attributes.md#keyboardavoidmode12)声明的模式。 - -**系统能力：** SystemCapability.Web.Webview.Core - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------ | -------- | ---- | ---------------------- | -| avoidHeight | number | 是 | 设置Web网页可视视口底部避让高度。
默认值：0
单位：vp
合法取值范围：0~Web组件高度
非法值设置行为：超出合法取值范围时取边界值。 | - -**错误码：** - -以下错误码的详细介绍请参见[webview错误码](errorcode-webview.md)。 - -| 错误码ID | 错误信息 | -| -------- | ------------------------------------------------------------ | -| 17100001 | Init error. The WebviewController must be associated with a Web component. | - -**示例：** - -```ts -// xxx.ets -import { webview } from '@kit.ArkWeb'; -import { BusinessError } from '@kit.BasicServicesKit'; - -@Entry -@Component -struct WebComponent { - controller: webview.WebviewController = new webview.WebviewController(); - avoidHeight: number = 100; - - build() { - Column() { - Button('avoid') - .onClick(() => { - try { - this.controller.avoidVisibleViewportBottom(this.avoidHeight); - } catch (error) { - console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); - } - }) - Button('reset') - .onClick(() => { - try { - this.controller.avoidVisibleViewportBottom(0); - } catch (error) { - console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); - } - }) - Web({ src: 'www.example.com', controller: this.controller }) - } - } -} -``` +``` \ No newline at end of file