Web
Note:
Currently in the beta phase.
Provides Web components with web display capabilities. @ohos.web.webview offers web control functionalities.
Importing Modules
import kit.ArkUI.*
Subcomponents
None
Creating Components
init(ResourceStr, WebviewController)
public init(
src!: ResourceStr,
controller!: WebviewController
)
Functionality: Creates a Web component.
Note:
- Transition animations are not supported.
- Multiple Web components on the same page must be bound to different WebviewControllers.
System Capability: SystemCapability.Web.Webview.Core
Since: 22
Parameters:
| Parameter | Type | Required | Default Value | Description |
|---|---|---|---|---|
| src | ResourceStr | Yes | - | Named parameter. The src cannot be dynamically changed via state variables (e.g., @State). |
| controller | WebviewController | Yes | - | Named parameter. Sets the Web controller. |
Universal Attributes/Events
Universal Attributes: Only supports aspectRatio, backdropBlur, backgroundColor, bindContentCover, bindContextMenu, bindMenu , bindSheet, borderColor, borderStyle, borderWidth, clip, constraintSize, defaultFocus, focusable, tabIndex, groupDefaultFocus, displayPriority, enabled, flexBasis, flexShrink, layoutWeight, id, height, touchable, margin, markAnchor, offset, width, zIndex, visibility, scale, translate, responseRegion, size, opacity, sharedTransition, transition, position, direction.
Universal Events: Only supports onAppear, onDisAppear, onBlur, onFocus, onHover, onMouse, onKeyEvent, onTouch, onVisibleAreaChange.
Component Attributes
func darkMode(?WebDarkMode)
public func darkMode(mode: ?WebDarkMode): This
Functionality: Sets the Web dark mode, which is disabled by default. When dark mode is enabled, the Web will apply the dark styles defined in the webpage's media query prefers-color-scheme. If no dark styles are defined, the original appearance is maintained. To enable forced dark mode, it is recommended to use it in conjunction with forceDarkAccess.
System Capability: SystemCapability.Web.Webview.Core
Since: 22
Parameters:
| Parameter | Type | Required | Default Value | Description |
|---|---|---|---|---|
| mode | ?WebDarkMode | Yes | - | The dark mode of the Web can be off, on, or follow the system. Initial value: WebDarkMode.Off. |
func domStorageAccess(?Bool)
public func domStorageAccess(domStorageAccess: ?Bool): This
Functionality: Sets whether to enable the Document Object Model Storage API (DOM Storage API) permission.
System Capability: SystemCapability.Web.Webview.Core
Since: 22
Parameters:
| Parameter | Type | Required | Default Value | Description |
|---|---|---|---|---|
| domStorageAccess | ?Bool | Yes | - | Whether to enable the Document Object Model Storage API (DOM Storage API) permission. true indicates enabled, false indicates disabled. Initial value: false. |
func fileAccess(?Bool)
public func fileAccess(fileAccess: ?Bool): This
Functionality: Sets whether to enable access to the file system within the application, which is enabled by default. Files in the rawfile path are not affected by this attribute and remain accessible.
System Capability: SystemCapability.Web.Webview.Core
Since: 22
Parameters:
| Parameter | Type | Required | Default Value | Description |
|---|---|---|---|---|
| fileAccess | ?Bool | Yes | - | Whether to enable access to the file system within the application, which is enabled by default. Initial value: false |
func forceDarkAccess(?Bool)
public func forceDarkAccess(access: ?Bool): This
Functionality: Sets whether to enable forced dark mode for webpages. Disabled by default. This attribute only takes effect when darkMode is enabled.
System Capability: SystemCapability.Web.Webview.Core
Since: 22
Parameters:
| Parameter | Type | Required | Default Value | Description |
|---|---|---|---|---|
| access | ?Bool | Yes | - | Sets whether to enable forced dark mode for webpages. true: enabled, false: disabled. Initial value: false. |
func geolocationAccess(?Bool)
public func geolocationAccess(geolocationAccess: ?Bool): This
Functionality: Sets whether to enable geolocation permission, which is disabled by default.
System Capability: SystemCapability.Web.Webview.Core
Since: 22
Parameters:
| Parameter | Type | Required | Default Value | Description |
|---|---|---|---|---|
| geolocationAccess | ?Bool | Yes | - | Sets whether to enable geolocation permission. Initial value: false. |
func imageAccess(?Bool)
public func imageAccess(imageAccess: ?Bool): This
Functionality: Sets whether to allow automatic loading of image resources, which is allowed by default.
System Capability: SystemCapability.Web.Webview.Core
Since: 22
Parameters:
| Parameter | Type | Required | Default Value | Description |
|---|---|---|---|---|
| imageAccess | ?Bool | Yes | - | Whether to allow automatic loading of image resources. Initial value: false. |
func javaScriptProxy(?Array<(String) -> String>, ?String, ?Array<String>, ?WebviewController)
public func javaScriptProxy(funcList!: ?Array<(String) -> String>, name!: ?String, methodList!: ?Array<String>,
controller!: ?WebviewController): This
Functionality: Injects a JavaScript object into the window object and calls the object's methods within the window object.
System Capability: SystemCapability.Web.Webview.Core
Since: 22
Parameters:
| Parameter | Type | Required | Default Value | Description |
|---|---|---|---|---|
| funcList | ?Array<(String)->String> | Yes | - | Named parameter. The synchronous methods of the application-side JavaScript object to be registered. Initial value: []. |
| name | ?String | Yes | - | Named parameter. The name of the registered object, which matches the object name called in the window. Initial value: "". |
| methodList | ?Array<String> | Yes | - | Named parameter. The asynchronous methods of the application-side JavaScript object to be registered. Initial value: []. |
| controller | ?WebviewController | Yes | - | Named parameter. Sets the Web controller. Initial value: WebviewController(). |
func mixedMode(?MixedMode)
public func mixedMode(mixedMode: ?MixedMode): This
Functionality: Sets whether to allow loading mixed content of Hypertext Transfer Protocol (HTTP) and Hypertext Transfer Protocol Secure (HTTPS), which is disallowed by default.
System Capability: SystemCapability.Web.Webview.Core
Since: 22
Parameters:
| Parameter | Type | Required | Default Value | Description |
|---|---|---|---|---|
| mixedMode | ?MixedMode | Yes | - | Mixed content. Initial value: MixedMode.None. Indicates that secure origins are not allowed to load content from insecure origins. |
func nestedScroll(?NestedScrollMode, ?NestedScrollMode)
public func nestedScroll(
scrollForward!: ?NestedScrollMode,
scrollBackward!: ?NestedScrollMode
): This
Functionality: Sets the nested scrolling modes for forward and backward directions to achieve scrolling linkage with parent components.
System Capability: SystemCapability.Web.Webview.Core
Since: 22
Parameters:
| Parameter | Type | Required | Default Value | Description |
|---|---|---|---|---|
| scrollForward | ?NestedScrollMode | Yes | - | Named parameter. Forward scrolling mode. Initial value: NestedScrollMode.SelfFirst. |
| scrollBackward | ?NestedScrollMode | Yes | - | Named parameter. Backward scrolling mode. Initial value: NestedScrollMode.SelfFirst. |
func onlineImageAccess(?Bool)
public func onlineImageAccess(onlineImageAccess: ?Bool): This
Functionality: Sets whether to allow loading image resources from the network (resources accessed via HTTP and HTTPS), which is disallowed by default.
System Capability: SystemCapability.Web.Webview.Core
Since: 22
Parameters:
| Parameter | Type | Required | Default Value | Description |
|---|---|---|---|---|
| onlineImageAccess | ?Bool | Yes | - | Whether to allow loading image resources from the network. true indicates allowed, false indicates disallowed. Initial value: false. |
func verticalScrollBarAccess(?Bool)
public func verticalScrollBarAccess(verticalScrollBar: ?Bool): This
Functionality: Sets whether to display vertical scroll bars, including system-default scroll bars and user-defined scroll bars. Not displayed by default.
System Capability: SystemCapability.Web.Webview.Core
Since: 22
Parameters:
| Parameter | Type | Required | Default Value | Description |
|---|---|---|---|---|
| verticalScrollBar | ?Bool | Yes | - | Whether to display vertical scroll bars. true indicates displayed, false indicates not displayed. Initial value: false. |
func zoomAccess(?Bool)
public func zoomAccess(zoomAccess: ?Bool): This
Functionality: Sets whether to support zooming via gestures, which is disallowed by default.
System Capability: SystemCapability.Web.Webview.Core
Since: 22
Parameters:
| Parameter | Type | Required | Default Value | Description |
|---|---|---|---|---|
| zoomAccess | ?Bool | Yes | - | Whether to support zooming via gestures. true indicates supported, false indicates not supported. Initial value: false. |
Component Events
func onLoadIntercept(?Callback<OnLoadInterceptEvent, Bool>)
public func onLoadIntercept(callback: ?Callback<OnLoadInterceptEvent, Bool>): This
Functionality: Triggered before the Web component loads a URL, used to determine whether to block this access. Allowed by default.
System Capability: SystemCapability.Web.Webview.Core
Since: 22
Parameters:
| Parameter | Type | Required | Default Value | Description |
|---|---|---|---|---|
| callback | ?Callback<OnLoadInterceptEvent, Bool> | Yes | - | Callback function triggered when resource loading is intercepted. Returns true to block the loading, otherwise allows it. Initial value: { _ => true}. |
func onPageBegin(?Callback<OnPageBeginEvent, Unit>)
public func onPageBegin(callback: ?Callback<OnPageBeginEvent, Unit>): This
Functionality: Triggered when a webpage starts loading, only for the main frame. Loading of iframe or frameset content does not trigger this callback.
System Capability: SystemCapability.Web.Webview.Core
Since: 22
Parameters:
| Parameter | Type | Required | Default Value | Description |
|---|---|---|---|---|
| callback | ?Callback<OnPageBeginEvent, Unit> | Yes | - | Callback function triggered when webpage loading starts. Initial value: { _ => }. |
func onPageEnd(?Callback<OnPageEndEvent, Unit>)
public func onPageEnd(callback: ?Callback<OnPageEndEvent, Unit>): This
Functionality: Triggered when a webpage finishes loading, only for the main frame.
System Capability: SystemCapability.Web.Webview.Core
Since: 22
Parameters:
| Parameter | Type | Required | Default Value | Description |
|---|---|---|---|---|
| callback | ?Callback<OnPageEndEvent, Unit> | Yes | - | Whether to allow loading image resources from the network. true indicates allowed, false indicates disallowed. Initial value: { _ => }. |
Basic Type Definitions
class Header
public class Header {
public var headerKey: ?String
public var headerValue: ?String
}
Functionality: Describes the request/response header object returned by the Web component.
System Capability: SystemCapability.Web.Webview.Core
Since: 22
var headerKey
public var headerKey: ?String
Functionality: The key of the request/response header.
Type: ?String
Read/Write: Read-Write
System Capability: SystemCapability.Web.Webview.Core
Since: 22
var headerValue
public var headerValue: ?String
Functionality: The value of the request/response header### class OnPageBeginEvent
public class OnPageBeginEvent {
public var url: String
public init(url: String)
}
Function: Defines the function triggered when webpage loading begins.
System Capability: SystemCapability.Web.Webview.Core
Since: 22
var url
public var url: String
Function: The URL of the currently loading page.
Type: String
Access: Read-Write
System Capability: SystemCapability.Web.Webview.Core
Since: 22
init(String)
public init(url: String)
Function: Creates an OnPageBeginEvent object.
System Capability: SystemCapability.Web.Webview.Core
Since: 22
Parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| url | String | Yes | - | The URL of the currently loading page. |
class OnPageEndEvent
public class OnPageEndEvent {
public var url: String
public init(url: String)
}
Function: Defines the function triggered when webpage loading completes.
System Capability: SystemCapability.Web.Webview.Core
Since: 22
var url
public var url: String
Function: The URL of the currently loading page.
Type: String
Access: Read-Write
System Capability: SystemCapability.Web.Webview.Core
Since: 22
init(String)
public init(url: String)
Function: Constructor for OnPageEndEvent.
System Capability: SystemCapability.Web.Webview.Core
Since: 22
Parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| url | String | Yes | - | The URL of the currently loading page. |
class PermissionRequest
public class PermissionRequest {}
Function: The object returned by Web component for granting or denying permission functionality. Example code reference onPermissionRequest event.
System Capability: SystemCapability.Web.Webview.Core
Since: 22
func deny()
public func deny(): Unit
Function: Denies the permission requested by the webpage.
System Capability: SystemCapability.Web.Webview.Core
Since: 22
func getAccessibleResource()
public func getAccessibleResource(): Array<String>
Function: Gets the list of permission resources requested by the webpage.
System Capability: SystemCapability.Web.Webview.Core
Since: 22
Return Value:
| Type | Description |
|---|---|
| Array<String> | The list of permission resources requested by the webpage. |
func getOrigin()
public func getOrigin(): String
Function: Gets the origin of the webpage.
System Capability: SystemCapability.Web.Webview.Core
Since: 22
Return Value:
| Type | Description |
|---|---|
| String | The origin of the webpage requesting permission. |
func grant(Array<String>)
public func grant(resources: Array<String>): Unit
Function: Grants permission for screen capture operations requested by the webpage.
System Capability: SystemCapability.Web.Webview.Core
Since: 22
Parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| resources | Array<String> | Yes | - | Screen capture configuration. |
class WebResourceRequest
public class WebResourceRequest {}
Function: Web component resource response object.
System Capability: SystemCapability.Web.Webview.Core
Since: 22
func getRequestHeader()
public func getRequestHeader(): Array<Header>
Function: Gets the resource request header information.
System Capability: SystemCapability.Web.Webview.Core
Since: 22
Return Value:
| Type | Description |
|---|---|
| Array<Header> | Returns the resource request header information. |
func getRequestMethod()
public func getRequestMethod(): String
Function: Gets the request method.
System Capability: SystemCapability.Web.Webview.Core
Since: 22
Return Value:
| Type | Description |
|---|---|
| String | Returns the request method. |
func getRequestUrl()
public func getRequestUrl(): String
Function: Gets the URL information of the resource request.
System Capability: SystemCapability.Web.Webview.Core
Since: 22
Return Value:
| Type | Description |
|---|---|
| String | Returns the URL information of the resource request. |
func isMainFrame()
public func isMainFrame(): Bool
Function: Determines whether the resource request is for the main frame.
System Capability: SystemCapability.Web.Webview.Core
Since: 22
Return Value:
| Type | Description |
|---|---|
| Bool | Returns whether the resource request is for the main frame. true indicates the request is for the main frame, false indicates it is not. |
func isRedirect()
public func isRedirect(): Bool
Function: Determines whether the resource request was redirected by the server.
System Capability: SystemCapability.Web.Webview.Core
Since: 22
Return Value:
| Type | Description |
|---|---|
| Bool | Returns whether the resource request was redirected by the server. true indicates the request was redirected, false indicates it was not. |
func isRequestGesture()
public func isRequestGesture(): Bool
Function: Gets whether the resource request is associated with a gesture (e.g., click).
System Capability: SystemCapability.Web.Webview.Core
Since: 22
Return Value:
| Type | Description |
|---|---|
| Bool | Returns whether the resource request is associated with a gesture (e.g., click). true indicates association, false indicates no association. |
class OnPermissionRequestEvent
public class OnPermissionRequestEvent {
public var request: PermissionRequest
public init(request: PermissionRequest)
}
Function: Describes the parameter structure for notifying receipt of a permission request.
System Capability: SystemCapability.Web.Webview.Core
Since: 22
var request
public var request: PermissionRequest
Function: The object returned by Web component for granting or denying permission functionality. Example code reference onPermissionRequest event.
Type: PermissionRequest
Access: Read-Write
System Capability: SystemCapability.Web.Webview.Core
Since: 22
init(PermissionRequest)
public init(request: PermissionRequest)
Function: Creates an OnPermissionRequestEvent object.
System Capability: SystemCapability.Web.Webview.Core
Since: 22
Parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| request | PermissionRequest | Yes | - | The object returned by Web component for granting or denying permission functionality. |
Example Code
package ohos_app_cangjie_entry
import kit.ArkUI.*
import ohos.arkui.state_macro_manage.*
import ohos.web.webview.*
import ohos.hilog.Hilog
@Entry
@Component
class EntryView {
let webController = WebviewController()
@State var url: String = "www.example.com"
func build() {
Column(space: 10) {
Button("refresh")
.onClick({
evt =>
Hilog.info(0, "AppLogCj", "refresh")
webController.reload()
}).width(400.px).height(150.px)
Button("loadUrl")
.onClick({
evt =>
Hilog.info(0, "AppLogCj", "loadUrl")
webController.loadUrl(this.url)
}).width(400.px).height(150.px)
Web(src: "www.example.com", controller: webController)
.onPageBegin({evt =>
Hilog.info(0, "AppLogCj", "page begin url: ${evt.url}")
})
.onPageEnd({evt =>
Hilog.info(0, "AppLogCj", "page end url: ${evt.url}")
})
}
}
}