Class (WebController)

WebController是ArkWeb组件的控制器类，用于控制Web组件的各种行为。一个WebController对象只能与一个Web组件绑定，绑定后开发者可通过该控制器对Web组件进行页面导航（前进/后退/加载）、焦点控制、缩放调整、页面刷新与停止、Cookie管理、JavaScript注入与执行等操作。

WebController适用于需要在应用侧对嵌入式Web组件进行主动控制的场景，例如实现浏览器式的前进后退导航、在应用侧与网页侧之间建立JavaScript交互通道、动态加载网页内容或管理Cookie数据。

该组件从API version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
本Class从API version 8开始支持。
该组件从API version 9开始废弃，建议使用WebviewController代替。
示例效果请以真机运行为准。

创建对象

let webController: WebController = new WebController()

constructor^(deprecated)

constructor()

WebController的构造函数。

从API version 8开始支持，从API version 9开始废弃，建议使用constructor¹¹⁺代替。

系统能力： SystemCapability.Web.Webview.Core

getCookieManager^(deprecated)

getCookieManager(): WebCookie

获取Web组件cookie管理对象。

从API version 9开始支持，从API version 9开始废弃，建议使用getCookie代替。

系统能力： SystemCapability.Web.Webview.Core

返回值：

类型	说明
WebCookie	Web组件cookie管理对象，参考WebCookie定义。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()

  build() {
    Column() {
      Button('getCookieManager')
        .onClick(() => {
          let cookieManager = this.controller.getCookieManager()
        })
      Web({ src: 'www.example.com', controller: this.controller })
    }
  }
}

requestFocus^(deprecated)

requestFocus()

使当前Web页面获取焦点。

从API version 8开始支持，从API version 9开始废弃，建议使用requestFocus⁹⁺代替。

系统能力： SystemCapability.Web.Webview.Core

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()

  build() {
    Column() {
      Button('requestFocus')
        .onClick(() => {
          this.controller.requestFocus()
        })
      Web({ src: 'www.example.com', controller: this.controller })
    }
  }
}

accessBackward^(deprecated)

accessBackward(): boolean

当前页面是否可后退，即当前页面是否有返回历史记录。

从API version 8开始支持，从API version 9开始废弃，建议使用accessBackward⁹⁺代替。

系统能力： SystemCapability.Web.Webview.Core

返回值：

类型	说明
boolean	可以后退返回true，否则返回false。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()

  build() {
    Column() {
      Button('accessBackward')
        .onClick(() => {
          let result = this.controller.accessBackward()
          console.info('result:' + result)
        })
      Web({ src: 'www.example.com', controller: this.controller })
    }
  }
}

accessForward^(deprecated)

accessForward(): boolean

当前页面是否可前进，即当前页面是否有前进历史记录。

从API version 8开始支持，从API version 9开始废弃，建议使用accessForward⁹⁺代替。

系统能力： SystemCapability.Web.Webview.Core

返回值：

类型	说明
boolean	返回true表示当前页面可以前进，返回false表示当前页面不可以前进。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()

  build() {
    Column() {
      Button('accessForward')
        .onClick(() => {
          let result = this.controller.accessForward()
          console.info('result:' + result)
        })
      Web({ src: 'www.example.com', controller: this.controller })
    }
  }
}

accessStep^(deprecated)

accessStep(step: number): boolean

检查当前页面是否可前进或者后退给定的step步。

从API version 8开始支持，从API version 9开始废弃，建议使用accessStep⁹⁺代替。

系统能力： SystemCapability.Web.Webview.Core

参数：

参数名	类型	必填	说明
step	number	是	要跳转的步数，正数代表前进，负数代表后退。

返回值：

类型	说明
boolean	页面是否可以前进或后退给定的step步。true表示可以，false为不可以。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()
  @State steps: number = 2

  build() {
    Column() {
      Button('accessStep')
        .onClick(() => {
          let result = this.controller.accessStep(this.steps)
          console.info('result:' + result)
        })
      Web({ src: 'www.example.com', controller: this.controller })
    }
  }
}

backward^(deprecated)

backward()

按照历史栈，后退一个页面。建议在调用backward前先调用accessBackward⁹⁺检查当前页面是否可后退。

从API version 8开始支持，从API version 9开始废弃，建议使用backward⁹⁺代替。

系统能力： SystemCapability.Web.Webview.Core

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()

  build() {
    Column() {
      Button('backward')
        .onClick(() => {
          this.controller.backward()
        })
      Web({ src: 'www.example.com', controller: this.controller })
    }
  }
}

forward^(deprecated)

forward()

按照历史栈，前进一个页面。建议在调用forward前先调用accessForward⁹⁺检查当前页面是否可前进。

从API version 8开始支持，从API version 9开始废弃，建议使用forward⁹⁺代替。

系统能力： SystemCapability.Web.Webview.Core

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()

  build() {
    Column() {
      Button('forward')
        .onClick(() => {
          this.controller.forward()
        })
      Web({ src: 'www.example.com', controller: this.controller })
    }
  }
}

deleteJavaScriptRegister^(deprecated)

deleteJavaScriptRegister(name: string)

删除通过registerJavaScriptProxy注册到window上的指定name的应用侧JavaScript对象。删除后立即生效，无须调用refresh接口。

从API version 8开始支持，从API version 9开始废弃，建议使用deleteJavaScriptRegister⁹⁺代替。

系统能力： SystemCapability.Web.Webview.Core

参数：

参数名	类型	必填	说明
name	string	是	注册对象的名称，可在网页侧JavaScript中通过此名称调用应用侧JavaScript对象。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()
  @State name: string = 'Object'

  build() {
    Column() {
      Button('deleteJavaScriptRegister')
        .onClick(() => {
          this.controller.deleteJavaScriptRegister(this.name)
        })
      Web({ src: 'www.example.com', controller: this.controller })
    }
  }
}

getHitTest^(deprecated)

getHitTest(): HitTestType

获取当前被点击区域的元素类型。

从API version 8开始支持，从API version 9开始废弃。建议使用getHitTest^(deprecated)替代。

系统能力： SystemCapability.Web.Webview.Core

返回值：

类型	说明
HitTestType	被点击区域的元素类型。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()

  build() {
    Column() {
      Button('getHitTest')
        .onClick(() => {
          let hitType = this.controller.getHitTest()
          console.info("hitType: " + hitType)
        })
      Web({ src: 'www.example.com', controller: this.controller })
    }
  }
}

loadData^(deprecated)

loadData(options: { data: string, mimeType: string, encoding: string, baseUrl?: string, historyUrl?: string })

baseUrl为空时，通过“data”协议加载指定的一段字符串。

当baseUrl为“data”协议时，编码后的data字符串将被Web组件作为“data”协议加载。

当baseUrl为“http/https”协议时，编码后的data字符串将被Web组件以类似loadUrl的方式以非编码字符串处理。

从API version 8开始支持，从API version 9开始废弃，建议使用loadData⁹⁺代替。

系统能力： SystemCapability.Web.Webview.Core

参数：

参数名	类型	必填	说明
data	string	是	加载的字符串数据。处理方式与baseUrl协议相关：baseUrl为空或“data”协议时，按“Base64”或“URL”编码进行解码加载；为“http/https”协议时，作为未编码的普通HTML字符串直接加载。
mimeType	string	是	媒体类型（MIME）。
encoding	string	是	编码类型，支持“Base64”、“URL”或字符集编码（如“UTF-8”）。当data参数为未编码的HTML字符串时，应使用字符集编码；当data参数为已编码的字符串时，应使用“Base64”或“URL”。
baseUrl	string	否	指定的一个URL路径（“http”/“https”/“data”协议），并由Web组件赋值给window.origin。为空时通过“data”协议加载字符串。默认值为空字符串。
historyUrl	string	否	历史记录URL。默认值为空字符串。非空时，可被历史记录管理，实现前进后退功能。当baseUrl为空时，此属性无效。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()

  build() {
    Column() {
      Button('loadData')
        .onClick(() => {
          this.controller.loadData({
            data: "<html><body bgcolor=\"white\">Source:<pre>source</pre></body></html>",
            mimeType: "text/html",
            encoding: "UTF-8"
          })
        })
      Web({ src: 'www.example.com', controller: this.controller })
    }
  }
}

loadUrl^(deprecated)

loadUrl(options: { url: string | Resource, headers?: Array<Header> })

使用指定的HTTP头加载指定的URL。

通过loadUrl注入的对象只在当前document有效，即通过loadUrl导航到新的页面会无效。

而通过registerJavaScriptProxy注入的对象，在loadUrl导航到新的页面也会有效。

从API version 8开始支持，从API version 9开始废弃，建议使用loadUrl⁹⁺代替。

系统能力： SystemCapability.Web.Webview.Core

参数：

参数名	类型	必填	说明
url	string \| Resource	是	需要加载的 URL。
headers	Array<Header>	否	URL的附加HTTP请求头，用于自定义请求行为（如设置身份验证信息、指定内容类型、添加用户代理等）。当需要在请求中携带额外信息时传入。不传入时使用默认值（空数组），不携带额外HTTP请求头。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()

  build() {
    Column() {
      Button('loadUrl')
        .onClick(() => {
          this.controller.loadUrl({ url: 'www.example.com' })
        })
      Web({ src: 'www.example.com', controller: this.controller })
    }
  }
}

onActive^(deprecated)

onActive(): void

调用此接口通知Web组件进入前台激活状态。

从API version 8开始支持，从API version 9开始废弃，建议使用onActive⁹⁺替代。

系统能力： SystemCapability.Web.Webview.Core

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()

  build() {
    Column() {
      Button('onActive')
        .onClick(() => {
          this.controller.onActive()
        })
      Web({ src: 'www.example.com', controller: this.controller })
    }
  }
}

onInactive^(deprecated)

onInactive(): void

调用此接口通知Web组件进入未激活状态。

从API version 8开始支持，从API version 9开始废弃，建议使用onInactive⁹⁺替代。

系统能力： SystemCapability.Web.Webview.Core

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()

  build() {
    Column() {
      Button('onInactive')
        .onClick(() => {
          this.controller.onInactive()
        })
      Web({ src: 'www.example.com', controller: this.controller })
    }
  }
}

zoom^(deprecated)

zoom(factor: number): void

调整当前网页的缩放比例。

从API version 8开始支持，从API version 9开始废弃。建议使用zoom⁹⁺替代。

系统能力： SystemCapability.Web.Webview.Core

参数：

参数名	类型	必填	说明
factor	number	是	缩放系数。1表示恢复默认加载网页的缩放比例；小于1为缩小，大于1为放大。取值范围(0, 100]。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()
  @State factor: number = 1

  build() {
    Column() {
      Button('zoom')
        .onClick(() => {
          this.controller.zoom(this.factor)
        })
      Web({ src: 'www.example.com', controller: this.controller })
    }
  }
}

refresh^(deprecated)

refresh()

调用此接口通知Web组件刷新网页。

从API version 8开始支持，从API version 9开始废弃，建议使用refresh⁹⁺代替。

系统能力： SystemCapability.Web.Webview.Core

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()

  build() {
    Column() {
      Button('refresh')
        .onClick(() => {
          this.controller.refresh()
        })
      Web({ src: 'www.example.com', controller: this.controller })
    }
  }
}

registerJavaScriptProxy^(deprecated)

registerJavaScriptProxy(options: { object: object, name: string, methodList: Array<string> })

注入JavaScript对象到window对象中，并在window对象中调用该对象的方法。注入的对象在页面下一次（重新）加载前不会出现在JavaScript中。

从API version 8开始支持，从API version 9开始废弃，建议使用registerJavaScriptProxy⁹⁺代替。

系统能力： SystemCapability.Web.Webview.Core

参数：

参数名	类型	必填	说明
object	object	是	参与注册的应用侧JavaScript对象。可以声明方法，也可以声明属性，但是不支持h5直接调用。其中方法的参数和返回类型只能为string、number、boolean。
name	string	是	注册对象的名称，与window中调用的对象名一致。注册后window对象可以通过此名字访问应用侧JavaScript对象。
methodList	Array<string>	是	参与注册的应用侧JavaScript对象的方法。

示例：

// xxx.ets
class TestObj {
  constructor() {
  }

  test(): string {
    return "ArkUI Web Component"
  }

  toString(): void {
    console.info('Web Component toString')
  }
}

@Entry
@Component
struct Index {
  controller: WebController = new WebController()
  testObj = new TestObj();
  build() {
    Column() {
      Row() {
        Button('Register JavaScript To Window').onClick(() => {
          this.controller.registerJavaScriptProxy({
            object: this.testObj,
            name: "objName",
            methodList: ["test", "toString"],
          })
        })
      }
      Web({ src: $rawfile('index.html'), controller: this.controller })
        .javaScriptAccess(true)
    }
  }
}

加载的HTML文件。

<!-- index.html -->
<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8">
    </head>
    <body>
        Hello world!
        <script type="text/javascript">
            function htmlTest() {
                str = objName.test("test function")
                console.info('objName.test result:'+ str)
            }
        </script>
    </body>
</html>

runJavaScript^(deprecated)

runJavaScript(options: { script: string, callback?: (result: string) => void })

异步执行JavaScript脚本，并通过回调方式返回脚本执行的结果。runJavaScript需要在loadUrl完成后，比如onPageEnd中调用。

从API version 8开始支持，从API version 9开始废弃，建议使用runJavaScript⁹⁺代替。

系统能力： SystemCapability.Web.Webview.Core

参数：

参数名	类型	必填	说明
script	string	是	JavaScript脚本。
callback	(result: string) => void	否	回调执行JavaScript脚本结果。JavaScript脚本若执行失败或无返回值时，返回null。当callback参数不传入时不进行回调。

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()
  @State webResult: string = ''
  build() {
    Column() {
      Text(this.webResult).fontSize(20)
      Web({ src: $rawfile('index.html'), controller: this.controller })
      .javaScriptAccess(true)
      .onPageEnd((event) => {
        this.controller.runJavaScript({
          script: 'test()',
          callback: (result: string) => {
            this.webResult = result
            console.info(`The test() return value is: ${result}`)
          }})
        if (event) {
          console.info('url: ', event.url)
        }
      })
    }
  }
}

加载的HTML文件。

<!-- index.html -->
<!DOCTYPE html>
<html>
  <head>
      <meta charset="utf-8">
  </head>
  <body>
      Hello world!
      <script type="text/javascript">
          function test() {
              console.info('Ark WebComponent')
              return "This value is from index.html"
          }
      </script>
  </body>
</html>

stop^(deprecated)

stop()

停止页面加载。

从API version 8开始支持，从API version 9开始废弃，建议使用stop⁹⁺代替。

系统能力： SystemCapability.Web.Webview.Core

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()

  build() {
    Column() {
      Button('stop')
        .onClick(() => {
          this.controller.stop()
        })
      Web({ src: 'www.example.com', controller: this.controller })
    }
  }
}

clearHistory^(deprecated)

clearHistory(): void

删除所有前进后退记录。

从API version 8开始支持，从API version 9开始废弃，建议使用clearHistory⁹⁺代替。

系统能力： SystemCapability.Web.Webview.Core

示例：

// xxx.ets
@Entry
@Component
struct WebComponent {
  controller: WebController = new WebController()

  build() {
    Column() {
      Button('clearHistory')
        .onClick(() => {
          this.controller.clearHistory()
        })
      Web({ src: 'www.example.com', controller: this.controller })
    }
  }
}

目录

Class (WebController)

创建对象

constructor(deprecated)

getCookieManager(deprecated)

requestFocus(deprecated)

accessBackward(deprecated)

accessForward(deprecated)

accessStep(deprecated)

backward(deprecated)

forward(deprecated)

deleteJavaScriptRegister(deprecated)

getHitTest(deprecated)

loadData(deprecated)

loadUrl(deprecated)

onActive(deprecated)

onInactive(deprecated)

zoom(deprecated)

refresh(deprecated)

registerJavaScriptProxy(deprecated)

runJavaScript(deprecated)

stop(deprecated)

clearHistory(deprecated)

constructor^(deprecated)

getCookieManager^(deprecated)

requestFocus^(deprecated)

accessBackward^(deprecated)

accessForward^(deprecated)

accessStep^(deprecated)

backward^(deprecated)

forward^(deprecated)

deleteJavaScriptRegister^(deprecated)

getHitTest^(deprecated)

loadData^(deprecated)

loadUrl^(deprecated)

onActive^(deprecated)

onInactive^(deprecated)

zoom^(deprecated)

refresh^(deprecated)

registerJavaScriptProxy^(deprecated)

runJavaScript^(deprecated)

stop^(deprecated)

clearHistory^(deprecated)