,
controller: [WebController](#WebController)
} | - | 注入ArkUI对象到HTML中，并在HTML中调用该对象的方法，参数不支持更新。
-obj: 参与注册的对象。
-name: 注册对象的名称，与HTML中调用的对象名一致。
-methodList: 参与注册的方法。
-controller: 控制器。 |
>  **说明：**
>
> 通用属性仅支持width、height、padding、margin、border。
- MixedMode枚举说明
| 名称 | 描述 |
| ---------- | ---------------------------------------- |
| All | 允许加载HTTP和HTTPS混合内容。 |
| Compatible | 混合内容兼容性模式，一些不安全的内容可能被安全来源加载，其他类型的内容将被阻止。 |
| None | 不允许加载HTTP和HTTPS混合内容。 |
## 事件
通用事件仅支持onFocus。
| 名称 | 功能描述 |
| ------------------------------------------------------------ | ------------------------------------------------------------ |
| 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：标题内容。
|
| onErrorReceive(callback: (event?: { request: WebResourceRequest, error: WebResourceError }) => void) | 网页加载错误时触发该回调。
request：网页的请求信息。
error：网页的错误信息 。
|
| onHttpErrorReceive(callback: (event?: { request: WebResourceRequest, response: WebResourceResponse }) => void) | 网页加载出现网络错误时触发该回调。
request：网页的请求信息。
response：网页的响应信息
|
| onConsole(callback: (event?: { message: ConsoleMessage }) => boolean) | 向主应用报告JavaScript控制台消息时触发该回调。
message：触发的控制台信息。
|
| onAlert(callback: (event?: { url: string; message: string; result: JsResult }) => boolean) | 网页触发alert()告警弹窗时触发。
url：Web引擎返回的下载URL。
message：Web引擎返回的信息。
JsResult：Web引擎返回的弹窗确认或弹窗取消功能对象。
|
| onBeforeUnload(callback: (event?: { url: string; message: string; result: JsResult }) => boolean) | 网页重新加载或关闭时触发。
url：Web引擎返回的下载URL。
message：Web引擎返回的信息。
JsResult：Web引擎返回的弹窗确认或弹窗取消功能对象。
|
| onConfirm(callback: (event?: { url: string; message: string; result: JsResult }) => boolean) | 即将离开当前页面（刷新或关闭）时触发。
url：Web引擎返回的下载URL。
message：Web引擎返回的信息。
JsResult：Web引擎返回的弹窗确认或弹窗取消功能对象。
|
### JsResult 对象说明
Web引擎返回的弹窗确认或弹窗取消功能对象。
- 接口
| 接口名称 | 功能描述 |
| --------------------- | ----------------- |
| handleCancel(): void | 取消弹窗。
|
| handleConfirm(): void | 确认弹窗。
|
### JsGeolocation 对象说明
用于请求地理位置权限。
- 接口
| 接口名称 | 功能描述 |
| ------------------------------------------------------------ | ------------------------------------------------------------ |
| invoke(origin: string, allow: boolean, retain: boolean): void | 通知系统用户是否批准该应用使用地理位置权限。
origin：尝试获取地理位置的Web内容的来源。
allow：用户是否批准该应用使用地理位置权限。true: 允许访问，false: 不允许访问。
retain：是否允许将地理位置权限状态保存到系统中。true: 允许，false: 不允许。
|
### WebResourceRequest对象说明
- 接口
| 接口名称 | 功能描述 |
| --------------------------------- | ------------------------------------ |
| getRequestUrl(): string | 获取请求的url信息。 |
| isRequestGesture(): boolean | 获取请求是否与手势关联。 |
| isMainFrame(): boolean | 获取请求是否时为了获取主窗口的信息。 |
| isRedirect(): boolean | 获取请求是否重定向。 |
| getRequestHeader(): Array | 获取请求头信息。 |
### WebResourceError对象说明
- 接口
| 接口名称 | 功能描述 |
| ---------------------- | ------------------------ |
| getErrorInfo(): string | 获取加载资源的错误信息。 |
| getErrorCode(): number | 获取加载资源的错误码。 |
### WebResourceResponse对象说明
- 接口
| 接口名称 | 功能描述 |
| ---------------------------------- | ---------------------- |
| getResponseData(): string | 获取响应数据。 |
| getResponseEncoding(): string | 获取响应的编码。 |
| getResponseMimeType(): string | 获取响应的MIME类型。 |
| getResponseCode(): number | 获取响应的状态码。 |
| getReasonMessage(): string | 获取响应的状态码描述。 |
| getResponseHeader(): Array | 获取响应头信息。 |
### ConsoleMessage对象说明
- 接口
| 接口名称 | 功能描述 |
| ------------------------------- | ------------------------------ |
| getMessage(): string | 获取ConsoleMessage的日志信息。 |
| getSourceId(): string | 获取ConsoleMessage的源的Id。 |
| getLineNumber(): number | 获取ConsoleMessage的行数。 |
| getMessageLevel(): MessageLevel | 获取ConsoleMessage的信息级别。 |
- MessageLevel枚举说明
| 名称 | 描述 |
| ----- | :--------- |
| Debug | 调试级别。 |
| Error | 错误级别。 |
| Info | 消息级别。 |
| Log | 日志级别。 |
| Warn | 警告级别。 |
## WebController
Web 组件的控制器。
### 创建对象
```
webController: WebController = new WebController()
```
### accessBackward
accessBackward(): boolean
当前页面是否可后退。
### accessForward
accessForward(): boolean
当前页面是否可前进。
### accessStep
accessStep(step: number): boolean
当前页面是否可前进或者后退step步。
- 参数
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| ---- | ------ | ---- | ---- | --------------------- |
| step | number | 是 | - | 要跳转的步数，正数代表前进，负数代表后退。 |
### deleteJavaScriptRegister
deleteJavaScriptRegister(name: string): void
清空指定对象已注册的JavaScript方法。
- 参数
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| ---- | ------ | ---- | ---- | ----------------------- |
| 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(options:{ url: string, headers?: Array<{ key: string, value: string }> }): void
加载URL。
- options参数说明
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| --------------------- | ------------------------------------- | ---- | ---- | ---------- |
| 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(options: { script: string, callback?: (result: string) => void }): void
执行JavaScript脚本。
- options参数说明
| 参数名 | 参数类型 | 必填 | 默认值 | 参数描述 |
| -------- | ------------------------ | ---- | ---- | ------------------------------------ |
| script | string | 是 | - | JavaScript脚本。 |
| callback | (result: string) => void | 否 | - | 回调执行JavaScript脚本结果，默认result为null字符串。 |
### requestFocus
requestFocus(): void
Web组件获焦。
### stop
stop(): void
停止页面加载。
## 示例
```
// webComponent.ets
@Entry
@Component
struct WebComponent {
@State javaScriptAccess: boolean = true;
@State fileAccess: boolean = true;
controller: WebController = new WebController();
build() {
Column() {
Web({ src: $rawfile('index.html'), controller: this.controller })
.javaScriptAccess(this.javaScriptAccess)
.fileAccess(this.fileAccess)
.onPageEnd(e => {
// test() 在 index.html 中已定义
this.controller.runJavaScript('test()');
console.log("url: ", e.url);
})
}
}
}
```
```
Hello world!
```
