OpenHarmony应用开发-基础组件 Web（上篇）

素年锦时静待君丶

发布于 2023-4-14 15:48

浏览

0收藏

版本：v3.2 Release

提供具有网页显示能力的Web组件，@ohos.web.webview提供web控制能力。

说明：
该组件从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
示例效果请以真机运行为准，当前IDE预览器不支持。

需要权限

访问在线网页时需添加网络权限：ohos.permission.INTERNET，具体申请方式请参考权限申请声明。

子组件

无

接口

Web(options: { src: ResourceStr, controller: WebviewController | WebController})

说明：
不支持转场动画。同一页面的多个web组件，必须绑定不同的WebviewController。

参数：

参数名	参数类型	必填	参数描述
src	ResourceStr	是	网页资源地址。如果加载应用包外沙箱路径的本地资源文件，请使用file://沙箱文件路径。
controller	WebviewController⁹⁺ \| WebController	是	控制器。从API Version 9开始，WebController不在维护，建议使用WebviewController替代。

示例：

加载在线网页

// xxx.ets
import web_webview from '@ohos.web.webview'

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
    }
  }
}

加载本地网页

// xxx.ets
import web_webview from '@ohos.web.webview'

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  build() {
    Column() {
      Web({ src: $rawfile("index.html"), controller: this.controller })
    }
  }
}

加载沙箱路径下的本地资源文件

1.通过globalthis获取沙箱路径。

// xxx.ets
import web_webview from '@ohos.web.webview'
let url = 'file://' + globalThis.filesDir + '/xxx.html'

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  build() {
    Column() {
      // 加载沙箱路径文件。
      Web({ src: url, controller: this.controller })
    }
  }
}

2.修改MainAbility.ts。以filesDir为例，获取沙箱路径。若想获取其他路径，请参考应用开发路径。

// xxx.ts
import UIAbility from '@ohos.app.ability.UIAbility';
import web_webview from '@ohos.web.webview';

export default class EntryAbility extends UIAbility {
    onCreate(want, launchParam) {
        // 通过在globalThis对象上绑定filesDir，可以实现UIAbility组件与UI之间的数据同步。
        globalThis.filesDir = this.context.filesDir
        console.log("Sandbox path is " + globalThis.filesDir)
    }
}

<!-- index.html -->
<!DOCTYPE html>
<html>
    <body>
        <p>Hello World</p>
    </body>
</html>

属性

通用属性仅支持width、height、padding、margin、border。

domStorageAccess

domStorageAccess(domStorageAccess: boolean)

设置是否开启文档对象模型存储接口（DOM Storage API）权限，默认未开启。

参数：

参数名	参数类型	必填	默认值	参数描述
domStorageAccess	boolean	是	false	设置是否开启文档对象模型存储接口（DOM Storage API）权限。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .domStorageAccess(true)
    }
  }
}

fileAccess

fileAccess(fileAccess: boolean)

设置是否开启应用中文件系统的访问，默认启用。$rawfile(filepath/filename)中rawfile路径的文件不受该属性影响而限制访问。

参数：

参数名	参数类型	必填	默认值	参数描述
fileAccess	boolean	是	true	设置是否开启应用中文件系统的访问，默认启用。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .fileAccess(true)
    }
  }
}

imageAccess

imageAccess(imageAccess: boolean)

设置是否允许自动加载图片资源，默认允许。

参数：

参数名	参数类型	必填	默认值	参数描述
imageAccess	boolean	是	true	设置是否允许自动加载图片资源。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .imageAccess(true)
    }
  }
}

javaScriptProxy

javaScriptProxy(javaScriptProxy: { object: object, name: string, methodList: Array<string>, controller: WebviewController | WebController})

注入JavaScript对象到window对象中，并在window对象中调用该对象的方法。所有参数不支持更新。

参数：

参数名	参数类型	必填	默认值	参数描述
object	object	是	-	参与注册的对象。只能声明方法，不能声明属性。
name	string	是	-	注册对象的名称，与window中调用的对象名一致。
methodList	Array<string>	是	-	参与注册的应用侧JavaScript对象的方法。
controller	WebviewController⁹⁺ \| WebController	是	-	控制器。从API Version 9开始，WebController不在维护，建议使用WebviewController替代。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  testObj = {
    test: (data1, data2, data3) => {
      console.log("data1:" + data1)
      console.log("data2:" + data2)
      console.log("data3:" + data3)
      return "AceString"
    },
    toString: () => {
      console.log('toString' + "interface instead.")
    }
  }
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .javaScriptAccess(true)
        .javaScriptProxy({
          object: this.testObj,
          name: "objName",
          methodList: ["test", "toString"],
          controller: this.controller,
      })
    }
  }
}

javaScriptAccess

javaScriptAccess(javaScriptAccess: boolean)

设置是否允许执行JavaScript脚本，默认允许执行。

参数：

参数名	参数类型	必填	默认值	参数描述
javaScriptAccess	boolean	是	true	是否允许执行JavaScript脚本。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .javaScriptAccess(true)
    }
  }
}

mixedMode

mixedMode(mixedMode: MixedMode)

设置是否允许加载超文本传输协议（HTTP）和超文本传输安全协议（HTTPS）混合内容，默认不允许加载HTTP和HTTPS混合内容。

参数：

参数名	参数类型	必填	默认值	参数描述
mixedMode	MixedMode	是	MixedMode.None	要设置的混合内容。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  @State mode: MixedMode = MixedMode.All
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .mixedMode(this.mode)
    }
  }
}

onlineImageAccess

onlineImageAccess(onlineImageAccess: boolean)

设置是否允许从网络加载图片资源（通过HTTP和HTTPS访问的资源），默认允许访问。

参数：

参数名	参数类型	必填	默认值	参数描述
onlineImageAccess	boolean	是	true	设置是否允许从网络加载图片资源。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .onlineImageAccess(true)
    }
  }
}

zoomAccess

zoomAccess(zoomAccess: boolean)

设置是否支持手势进行缩放，默认允许执行缩放。

参数：

参数名	参数类型	必填	默认值	参数描述
zoomAccess	boolean	是	true	设置是否支持手势进行缩放。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .zoomAccess(true)
    }
  }
}

overviewModeAccess

overviewModeAccess(overviewModeAccess: boolean)

设置是否使用概览模式加载网页，默认使用该方式。

参数：

参数名	参数类型	必填	默认值	参数描述
overviewModeAccess	boolean	是	true	设置是否使用概览模式加载网页。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .overviewModeAccess(true)
    }
  }
}

databaseAccess

databaseAccess(databaseAccess: boolean)

设置是否开启数据库存储API权限，默认不开启。

参数：

参数名	参数类型	必填	默认值	参数描述
databaseAccess	boolean	是	false	设置是否开启数据库存储API权限。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .databaseAccess(true)
    }
  }
}

geolocationAccess

geolocationAccess(geolocationAccess: boolean)

设置是否开启获取地理位置权限，默认开启。

参数：

参数名	参数类型	必填	默认值	参数描述
geolocationAccess	boolean	是	true	设置是否开启获取地理位置权限。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .geolocationAccess(true)
    }
  }
}

mediaPlayGestureAccess

mediaPlayGestureAccess(access: boolean)

设置有声视频播放是否需要用户手动点击，静音视频播放不受该接口管控，默认需要。

参数：

参数名	参数类型	必填	默认值	参数描述
access	boolean	是	true	设置有声视频播放是否需要用户手动点击。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  @State access: boolean = true
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .mediaPlayGestureAccess(this.access)
    }
  }
}

multiWindowAccess⁹⁺

multiWindowAccess(multiWindow: boolean)

设置是否开启多窗口权限，默认不开启。使能多窗口权限时，需要实现onWindowNew事件，示例代码参考onWindowNew事件。

参数：

参数名	参数类型	必填	默认值	参数描述
multiWindow	boolean	是	false	设置是否开启多窗口权限。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
      .multiWindowAccess(false)
    }
  }
}

horizontalScrollBarAccess⁹⁺

horizontalScrollBarAccess(horizontalScrollBar: boolean)

设置是否显示横向滚动条，包括系统默认滚动条和用户自定义滚动条。默认显示。

参数：

参数名	参数类型	必填	默认值	参数描述
horizontalScrollBar	boolean	是	true	设置是否显示横向滚动条。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
      .horizontalScrollBarAccess(true)
    }
  }
}

<!--xxx.html-->
<!DOCTYPE html>
<html>
<head>
    <title>Demo</title>
    <style>
      body {
        width:3000px;
        height:3000px;
        padding-right:170px;
        padding-left:170px;
        border:5px solid blueviolet
      }
    </style>
</head>
<body>
Scroll Test
</body>
</html>

verticalScrollBarAccess⁹⁺

verticalScrollBarAccess(verticalScrollBar: boolean)

设置是否显示纵向滚动条，包括系统默认滚动条和用户自定义滚动条。默认显示。

参数：

参数名	参数类型	必填	默认值	参数描述
verticalScrollBarAccess	boolean	是	true	设置是否显示纵向滚动条。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
      .verticalScrollBarAccess(true)
    }
  }
}

<!--xxx.html-->
<!DOCTYPE html>
<html>
<head>
    <title>Demo</title>
    <style>
      body {
        width:3000px;
        height:3000px;
        padding-right:170px;
        padding-left:170px;
        border:5px solid blueviolet
      }
    </style>
</head>
<body>
Scroll Test
</body>
</html>

cacheMode

cacheMode(cacheMode: CacheMode)

设置缓存模式。

参数：

参数名	参数类型	必填	默认值	参数描述
cacheMode	CacheMode	是	CacheMode.Default	要设置的缓存模式。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  @State mode: CacheMode = CacheMode.None
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .cacheMode(this.mode)
    }
  }
}

textZoomRatio⁹⁺

textZoomRatio(textZoomRatio: number)

设置页面的文本缩放百分比，默认为100%。

参数：

参数名	参数类型	必填	默认值	参数描述
textZoomRatio	number	是	100	要设置的页面的文本缩放百分比。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  @State atio: number = 150
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .textZoomRatio(this.atio)
    }
  }
}

initialScale⁹⁺

initialScale(percent: number)

设置整体页面的缩放百分比，默认为100%。

参数：

参数名	参数类型	必填	默认值	参数描述
percent	number	是	100	要设置的整体页面的缩放百分比。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  @State percent: number = 100
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .initialScale(this.percent)
    }
  }
}

userAgent

userAgent(userAgent: string)

设置用户代理。

参数：

参数名	参数类型	必填	默认值	参数描述
userAgent	string	是	-	要设置的用户代理。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  @State userAgent:string = 'Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/39.0.2171.71 Safari/537.36'
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .userAgent(this.userAgent)
    }
  }
}

blockNetwork⁹⁺

blockNetwork(block: boolean)

设置Web组件是否阻止从网络加载资源。

参数：

参数名	参数类型	必填	默认值	参数描述
block	boolean	是	false	设置Web组件是否阻止从网络加载资源。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  @State block: boolean = true
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .blockNetwork(this.block)
    }
  }
}

defaultFixedFontSize⁹⁺

defaultFixedFontSize(size: number)

设置网页的默认等宽字体大小。

参数：

参数名	参数类型	必填	默认值	参数描述
size	number	是	13	设置网页的默认等宽字体大小，单位px。输入值的范围为-2^31到2^31-1，实际渲染时超过72的值按照72进行渲染，低于1的值按照1进行渲染。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  @State fontSize: number = 16
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .defaultFixedFontSize(this.fontSize)
    }
  }
}

defaultFontSize⁹⁺

defaultFontSize(size: number)

设置网页的默认字体大小。

参数：

参数名	参数类型	必填	默认值	参数描述
size	number	是	16	设置网页的默认字体大小，单位px。输入值的范围为-2^31到2^31-1，实际渲染时超过72的值按照72进行渲染，低于1的值按照1进行渲染。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  @State fontSize: number = 13
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .defaultFontSize(this.fontSize)
    }
  }
}

minFontSize⁹⁺

minFontSize(size: number)

设置网页字体大小最小值。

参数：

参数名	参数类型	必填	默认值	参数描述
size	number	是	8	设置网页字体大小最小值，单位px。输入值的范围为-2^31到2^31-1，实际渲染时超过72的值按照72进行渲染，低于1的值按照1进行渲染。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  @State fontSize: number = 13
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .minFontSize(this.fontSize)
    }
  }
}

minLogicalFontSize⁹⁺

minLogicalFontSize(size: number)

设置网页逻辑字体大小最小值。

参数：

参数名	参数类型	必填	默认值	参数描述
size	number	是	8	设置网页逻辑字体大小最小值，单位px。输入值的范围为-2^31到2^31-1，实际渲染时超过72的值按照72进行渲染，低于1的值按照1进行渲染。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  @State fontSize: number = 13
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .minLogicalFontSize(this.fontSize)
    }
  }
}

webFixedFont⁹⁺

webFixedFont(family: string)

设置网页的fixed font字体库。

参数：

参数名	参数类型	必填	默认值	参数描述
family	string	是	monospace	设置网页的fixed font字体库。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  @State family: string = "monospace"
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .webFixedFont(this.family)
    }
  }
}

webSansSerifFont⁹⁺

webSansSerifFont(family: string)

设置网页的sans serif font字体库。

参数：

参数名	参数类型	必填	默认值	参数描述
family	string	是	sans-serif	设置网页的sans serif font字体库。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  @State family: string = "sans-serif"
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .webSansSerifFont(this.family)
    }
  }
}

webSerifFont⁹⁺

webSerifFont(family: string)

设置网页的serif font字体库。

参数：

参数名	参数类型	必填	默认值	参数描述
family	string	是	serif	设置网页的serif font字体库。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  @State family: string = "serif"
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .webSerifFont(this.family)
    }
  }
}

webStandardFont⁹⁺

webStandardFont(family: string)

设置网页的standard font字体库。

参数：

参数名	参数类型	必填	默认值	参数描述
family	string	是	sans serif	设置网页的standard font字体库。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  @State family: string = "sans-serif"
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .webStandardFont(this.family)
    }
  }
}

webFantasyFont⁹⁺

webFantasyFont(family: string)

设置网页的fantasy font字体库。

参数：

参数名	参数类型	必填	默认值	参数描述
family	string	是	fantasy	设置网页的fantasy font字体库。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  @State family: string = "fantasy"
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .webFantasyFont(this.family)
    }
  }
}

webCursiveFont⁹⁺

webCursiveFont(family: string)

设置网页的cursive font字体库。

参数：

参数名	参数类型	必填	默认值	参数描述
family	string	是	cursive	设置网页的cursive font字体库。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  @State family: string = "cursive"
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .webCursiveFont(this.family)
    }
  }
}

darkMode⁹⁺

darkMode(mode: WebDarkMode)

设置Web深色模式，默认关闭。当深色模式开启时，Web将启用媒体查询prefer-color-scheme中网页所定义的深色样式，若网页未定义深色样式，则保持原状。如需开启强制深色模式，建议配合forceDarkAccess使用。

参数：

参数名	参数类型	必填	默认值	参数描述
mode	WebDarkMode	是	WebDarkMode.Off	设置Web的深色模式为关闭、开启或跟随系统。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  @State mode: WebDarkMode = WebDarkMode.On
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .darkMode(this.mode)
    }
  }
}

forceDarkAccess⁹⁺

forceDarkAccess(access: boolean)

设置网页是否开启强制深色模式。默认关闭。该属性仅在darkMode开启深色模式时生效。

参数：

参数名	参数类型	必填	默认值	参数描述
access	boolean	是	false	设置网页是否开启强制深色模式。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  @State mode: WebDarkMode = WebDarkMode.On
  @State access: boolean = true
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .darkMode(this.mode)
        .forceDarkAccess(this.access)
    }
  }
}

pinchSmooth⁹⁺

pinchSmooth(isEnabled: boolean)

设置网页是否开启捏合流畅模式，默认不开启。

参数：

参数名	参数类型	必填	默认值	参数描述
isEnabled	boolean	是	false	网页是否开启捏合流畅模式。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
controller: web_webview.WebviewController = new web_webview.WebviewController()
build() {
  Column() {
    Web({ src: 'www.example.com', controller: this.controller })
      .pinchSmooth(true)
  }
}
}

事件

不支持通用事件。

onAlert

onAlert(callback: (event?: { url: string; message: string; result: JsResult }) => boolean)

网页触发alert()告警弹窗时触发回调。

参数：

参数名	参数类型	参数描述
url	string	当前显示弹窗所在网页的URL。
message	string	弹窗中显示的信息。
result	JsResult	通知Web组件用户操作行为。

返回值：

类型	说明
boolean	当回调返回true时，应用可以调用系统弹窗能力（包括确认和取消），并且需要根据用户的确认或取消操作调用JsResult通知Web组件最终是否离开当前页面。当回调返回false时，web组件暂不支持触发默认弹窗。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .onAlert((event) => {
          AlertDialog.show({
            title: 'onAlert',
            message: 'text',
            primaryButton: {
              value: 'cancel',
              action: () => {
                event.result.handleCancel()
              }
            },
            secondaryButton: {
              value: 'ok',
              action: () => {
                event.result.handleConfirm()
              }
            },
            cancel: () => {
              event.result.handleCancel()
            }
          })
          return true
        })
    }
  }
}

onBeforeUnload

onBeforeUnload(callback: (event?: { url: string; message: string; result: JsResult }) => boolean)

刷新或关闭场景下，在即将离开当前页面时触发此回调。刷新或关闭当前页面应先通过点击等方式获取焦点，才会触发此回调。

参数：

参数名	参数类型	参数描述
url	string	当前显示弹窗所在网页的URL。
message	string	弹窗中显示的信息。
result	JsResult	通知Web组件用户操作行为。

返回值：

类型	说明
boolean	当回调返回true时，应用可以调用系统弹窗能力（包括确认和取消），并且需要根据用户的确认或取消操作调用JsResult通知Web组件最终是否离开当前页面。当回调返回false时，web组件暂不支持触发默认弹窗。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()

  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .onBeforeUnload((event) => {
          console.log("event.url:" + event.url)
          console.log("event.message:" + event.message)
          AlertDialog.show({
            title: 'onBeforeUnload',
            message: 'text',
            primaryButton: {
              value: 'cancel',
              action: () => {
                event.result.handleCancel()
              }
            },
            secondaryButton: {
              value: 'ok',
              action: () => {
                event.result.handleConfirm()
              }
            },
            cancel: () => {
              event.result.handleCancel()
            }
          })
          return true
        })
    }
  }
}

onConfirm

onConfirm(callback: (event?: { url: string; message: string; result: JsResult }) => boolean)

网页调用confirm()告警时触发此回调。

参数：

参数名	参数类型	参数描述
url	string	当前显示弹窗所在网页的URL。
message	string	弹窗中显示的信息。
result	JsResult	通知Web组件用户操作行为。

返回值：

类型	说明
boolean	当回调返回true时，应用可以调用系统弹窗能力（包括确认和取消），并且需要根据用户的确认或取消操作调用JsResult通知Web组件。当回调返回false时，web组件暂不支持触发默认弹窗。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()

  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .onConfirm((event) => {
          console.log("event.url:" + event.url)
          console.log("event.message:" + event.message)
          console.log("event.result:" + event.result)
          AlertDialog.show({
            title: 'onConfirm',
            message: 'text',
            primaryButton: {
              value: 'cancel',
              action: () => {
                event.result.handleCancel()
              }
            },
            secondaryButton: {
              value: 'ok',
              action: () => {
                event.result.handleConfirm()
              }
            },
            cancel: () => {
              event.result.handleCancel()
            }
          })
          return true
        })
    }
  }
}

onPrompt⁹⁺

onPrompt(callback: (event?: { url: string; message: string; value: string; result: JsResult }) => boolean)

参数：

参数名	参数类型	参数描述
url	string	当前显示弹窗所在网页的URL。
message	string	弹窗中显示的信息。
result	JsResult	通知Web组件用户操作行为。

返回值：

类型	说明
boolean	当回调返回true时，应用可以调用系统弹窗能力（包括确认和取消），并且需要根据用户的确认或取消操作调用JsResult通知Web组件。当回调返回false时，web组件暂不支持触发默认弹窗。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()

  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .onPrompt((event) => {
          console.log("url:" + event.url)
          console.log("message:" + event.message)
          console.log("value:" + event.value)
          AlertDialog.show({
            title: 'onPrompt',
            message: 'text',
            primaryButton: {
              value: 'cancel',
              action: () => {
                event.result.handleCancel()
              }
            },
            secondaryButton: {
              value: 'ok',
              action: () => {
                event.result.handleConfirm()
              }
            },
            cancel: () => {
              event.result.handleCancel()
            }
          })
          return true
        })
    }
  }
}

onConsole

onConsole(callback: (event?: { message: ConsoleMessage }) => boolean)

通知宿主应用JavaScript console消息。

参数：

参数名	参数类型	参数描述
message	ConsoleMessage	触发的控制台信息。

返回值：

类型	说明
boolean	当返回true时，该条消息将不会再打印至控制台，反之仍会打印至控制台。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()

  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .onConsole((event) => {
          console.log('getMessage:' + event.message.getMessage())
          console.log('getSourceId:' + event.message.getSourceId())
          console.log('getLineNumber:' + event.message.getLineNumber())
          console.log('getMessageLevel:' + event.message.getMessageLevel())
          return false
        })
    }
  }
}

onDownloadStart

onDownloadStart(callback: (event?: { url: string, userAgent: string, contentDisposition: string, mimetype: string, contentLength: number }) => void)

参数：

参数名	参数类型	参数描述
url	string	文件下载的URL。
contentDisposition	string	服务器返回的 Content-Disposition响应头，可能为空。
mimetype	string	服务器返回内容媒体类型（MIME）信息。
contentLength	contentLength	服务器返回文件的长度。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()

  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .onDownloadStart((event) => {
          console.log('url:' + event.url)
          console.log('userAgent:' + event.userAgent)
          console.log('contentDisposition:' + event.contentDisposition)
          console.log('contentLength:' + event.contentLength)
          console.log('mimetype:' + event.mimetype)
        })
    }
  }
}

onErrorReceive

onErrorReceive(callback: (event?: { request: WebResourceRequest, error: WebResourceError }) => void)

网页加载遇到错误时触发该回调。出于性能考虑，建议此回调中尽量执行简单逻辑。在无网络的情况下，触发此回调。

参数：

参数名	参数类型	参数描述
request	WebResourceRequest	网页请求的封装信息。
error	WebResourceError	网页加载资源错误的封装信息。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()

  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .onErrorReceive((event) => {
          console.log('getErrorInfo:' + event.error.getErrorInfo())
          console.log('getErrorCode:' + event.error.getErrorCode())
          console.log('url:' + event.request.getRequestUrl())
          console.log('isMainFrame:' + event.request.isMainFrame())
          console.log('isRedirect:' + event.request.isRedirect())
          console.log('isRequestGesture:' + event.request.isRequestGesture())
          console.log('getRequestHeader_headerKey:' + event.request.getRequestHeader().toString())
          let result = event.request.getRequestHeader()
          console.log('The request header result size is ' + result.length)
          for (let i of result) {
            console.log('The request header key is : ' + i.headerKey + ', value is : ' + i.headerValue)
          }
        })
    }
  }
}

onHttpErrorReceive

onHttpErrorReceive(callback: (event?: { request: WebResourceRequest, response: WebResourceResponse }) => void)

网页加载资源遇到的HTTP错误（响应码>=400)时触发该回调。

参数：

参数名	参数类型	参数描述
request	WebResourceRequest	网页请求的封装信息。
response	WebResourceResponse	资源响应的封装信息。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()

  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .onHttpErrorReceive((event) => {
          console.log('url:' + event.request.getRequestUrl())
          console.log('isMainFrame:' + event.request.isMainFrame())
          console.log('isRedirect:' + event.request.isRedirect())
          console.log('isRequestGesture:' + event.request.isRequestGesture())
          console.log('getResponseData:' + event.response.getResponseData())
          console.log('getResponseEncoding:' + event.response.getResponseEncoding())
          console.log('getResponseMimeType:' + event.response.getResponseMimeType())
          console.log('getResponseCode:' + event.response.getResponseCode())
          console.log('getReasonMessage:' + event.response.getReasonMessage())
          let result = event.request.getRequestHeader()
          console.log('The request header result size is ' + result.length)
          for (let i of result) {
            console.log('The request header key is : ' + i.headerKey + ' , value is : ' + i.headerValue)
          }
          let resph = event.response.getResponseHeader()
          console.log('The response header result size is ' + resph.length)
          for (let i of resph) {
            console.log('The response header key is : ' + i.headerKey + ' , value is : ' + i.headerValue)
          }
        })
    }
  }
}

onPageBegin

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

网页开始加载时触发该回调，且只在主frame触发，iframe或者frameset的内容加载时不会触发此回调。

参数：

参数名	参数类型	参数描述
url	string	页面的URL地址。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()

  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .onPageBegin((event) => {
          console.log('url:' + event.url)
        })
    }
  }
}

onPageEnd

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

网页加载完成时触发该回调，且只在主frame触发。

参数：

参数名	参数类型	参数描述
url	string	页面的URL地址。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()

  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .onPageEnd((event) => {
          console.log('url:' + event.url)
        })
    }
  }
}

onProgressChange

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

网页加载进度变化时触发该回调。

参数：

参数名	参数类型	参数描述
newProgress	number	新的加载进度，取值范围为0到100的整数。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()

  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .onProgressChange((event) => {
          console.log('newProgress:' + event.newProgress)
        })
    }
  }
}

onTitleReceive

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

网页document标题更改时触发该回调。

参数：

参数名	参数类型	参数描述
title	string	document标题内容。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()

  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .onTitleReceive((event) => {
          console.log('title:' + event.title)
        })
    }
  }
}

onRefreshAccessedHistory

onRefreshAccessedHistory(callback: (event?: { url: string, isRefreshed: boolean }) => void)

加载网页页面完成时触发该回调，用于应用更新其访问的历史链接。

参数：

参数名	参数类型	参数描述
url	string	访问的url。
isRefreshed	boolean	true表示该页面是被重新加载的（调用refresh⁹⁺接口），false表示该页面是新加载的。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()

  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .onRefreshAccessedHistory((event) => {
          console.log('url:' + event.url + ' isReload:' + event.isRefreshed)
        })
    }
  }
}

onRenderExited⁹⁺

onRenderExited(callback: (event?: { renderExitReason: RenderExitReason }) => void)

应用渲染进程异常退出时触发该回调。

参数：

参数名	参数类型	参数描述
renderExitReason	RenderExitReason	渲染进程进程异常退出的具体原因。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()

  build() {
    Column() {
      Web({ src: 'chrome://crash/', controller: this.controller })
        .onRenderExited((event) => {
          console.log('reason:' + event.renderExitReason)
        })
    }
  }
}

onShowFileSelector⁹⁺

onShowFileSelector(callback: (event?: { result: FileSelectorResult, fileSelector: FileSelectorParam }) => boolean)

调用此函数以处理具有“文件”输入类型的HTML表单，以响应用户按下的“选择文件”按钮。

参数：

参数名	参数类型	参数描述
result	FileSelectorResult	用于通知Web组件文件选择的结果。
fileSelector	FileSelectorParam	文件选择器的相关信息。

返回值：

类型	说明
boolean	当返回值为true时，用户可以调用系统提供的弹窗能力。当回调返回false时，web组件暂不支持触发默认弹窗。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()

  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .onShowFileSelector((event) => {
          AlertDialog.show({
            title: event.fileSelector.getTitle(),
            message: 'isCapture:' + event.fileSelector.isCapture() + " mode:" + event.fileSelector.getMode() + 'acceptType:' + event.fileSelector.getAcceptType(),
            confirm: {
              value: 'upload',
              action: () => {
                let fileList: Array<string> = [
                  '/data/storage/el2/base/test',
                ]
                event.result.handleFileList(fileList)
              }
            },
            cancel: () => {
              let fileList: Array<string> = []
              event.result.handleFileList(fileList)
            }
          })
          return true
        })
    }
  }
}
    ts

onResourceLoad⁹⁺

onResourceLoad(callback: (event: {url: string}) => void)

通知Web组件所加载的资源文件url信息。

参数：

参数名	参数类型	参数描述
url	string	所加载的资源文件url信息。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()

  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .onResourceLoad((event) => {
          console.log('onResourceLoad: ' + event.url)
        })
    }
  }
}

onScaleChange⁹⁺

onScaleChange(callback: (event: {oldScale: number, newScale: number}) => void)

当前页面显示比例的变化时触发该回调。

参数：

参数名	参数类型	参数描述
oldScale	number	变化前的显示比例百分比。
newScale	number	变化后的显示比例百分比。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()

  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .onScaleChange((event) => {
          console.log('onScaleChange changed from ' + event.oldScale + ' to ' + event.newScale)
        })
    }
  }
}

onUrlLoadIntercept

onUrlLoadIntercept(callback: (event?: { data:string | WebResourceRequest }) => boolean)

当Web组件加载url之前触发该回调，用于判断是否阻止此次访问。默认允许加载。

参数：

参数名	参数类型	参数描述
data	string / WebResourceRequest	url的相关信息。

返回值：

类型	说明
boolean	返回true表示阻止此次加载，否则允许此次加载。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()

  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .onUrlLoadIntercept((event) => {
          console.log('onUrlLoadIntercept ' + event.data.toString())
          return true
        })
    }
  }
}

onInterceptRequest⁹⁺

onInterceptRequest(callback: (event?: { request: WebResourceRequest}) => WebResourceResponse)

当Web组件加载url之前触发该回调，用于拦截url并返回响应数据。

参数：

参数名	参数类型	参数描述
request	WebResourceRequest	url请求的相关信息。

返回值：

类型	说明
WebResourceResponse	返回响应数据则按照响应数据加载，无响应数据则返回null表示按照原来的方式加载。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  responseweb: WebResourceResponse = new WebResourceResponse()
  heads:Header[] = new Array()
  @State webdata: string = "<!DOCTYPE html>\n" +
  "<html>\n"+
  "<head>\n"+
  "<title>intercept test</title>\n"+
  "</head>\n"+
  "<body>\n"+
  "<h1>intercept test</h1>\n"+
  "</body>\n"+
  "</html>"
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .onInterceptRequest((event) => {
          console.log('url:' + event.request.getRequestUrl())
          var head1:Header = {
            headerKey:"Connection",
            headerValue:"keep-alive"
          }
          var head2:Header = {
            headerKey:"Cache-Control",
            headerValue:"no-cache"
          }
          var length = this.heads.push(head1)
          length = this.heads.push(head2)
          this.responseweb.setResponseHeader(this.heads)
          this.responseweb.setResponseData(this.webdata)
          this.responseweb.setResponseEncoding('utf-8')
          this.responseweb.setResponseMimeType('text/html')
          this.responseweb.setResponseCode(200)
          this.responseweb.setReasonMessage('OK')
          return this.responseweb
        })
    }
  }
}

onHttpAuthRequest⁹⁺

onHttpAuthRequest(callback: (event?: { handler: HttpAuthHandler, host: string, realm: string}) => boolean)

通知收到http auth认证请求。

参数：

参数名	参数类型	参数描述
handler	HttpAuthHandler	通知Web组件用户操作行为。
host	string	HTTP身份验证凭据应用的主机。
realm	string	HTTP身份验证凭据应用的域。

返回值：

类型	说明
boolean	返回false表示此次认证失败，否则成功。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  httpAuth: boolean = false

  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .onHttpAuthRequest((event) => {
          AlertDialog.show({
            title: 'onHttpAuthRequest',
            message: 'text',
            primaryButton: {
              value: 'cancel',
              action: () => {
                event.handler.cancel()
              }
            },
            secondaryButton: {
              value: 'ok',
              action: () => {
                this.httpAuth = event.handler.isHttpAuthInfoSaved()
                if (this.httpAuth == false) {
                  web_webview.WebDataBase.saveHttpAuthCredentials(
                    event.host,
                    event.realm,
                    "2222",
                    "2222"
                  )
                  event.handler.cancel()
                }
              }
            },
            cancel: () => {
              event.handler.cancel()
            }
          })
          return true
        })
    }
  }
}

onSslErrorEventReceive⁹⁺

onSslErrorEventReceive(callback: (event: { handler: SslErrorHandler, error: SslError }) => void)

通知用户加载资源时发生SSL错误。

参数：

参数名	参数类型	参数描述
handler	SslErrorHandler	通知Web组件用户操作行为。
error	SslError	错误码。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()

  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .onSslErrorEventReceive((event) => {
          AlertDialog.show({
            title: 'onSslErrorEventReceive',
            message: 'text',
            primaryButton: {
              value: 'confirm',
              action: () => {
                event.handler.handleConfirm()
              }
            },
            secondaryButton: {
              value: 'cancel',
              action: () => {
                event.handler.handleCancel()
              }
            },
            cancel: () => {
              event.handler.handleCancel()
            }
          })
          return true
        })
    }
  }
}

onClientAuthenticationRequest⁹⁺

onClientAuthenticationRequest(callback: (event: {handler : ClientAuthenticationHandler, host : string, port : number, keyTypes : Array, issuers : Array}) => void)

通知用户收到SSL客户端证书请求事件。

参数：

参数名	参数类型	参数描述
handler	ClientAuthenticationHandler	通知Web组件用户操作行为。
host	string	请求证书服务器的主机名。
port	number	请求证书服务器的端口号。
keyTypes	Array	可接受的非对称秘钥类型。
issuers	Array	与私钥匹配的证书可接受颁发者。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()

  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .onClientAuthenticationRequest((event) => {
          AlertDialog.show({
            title: 'onClientAuthenticationRequest',
            message: 'text',
            primaryButton: {
              value: 'confirm',
              action: () => {
                event.handler.confirm("/system/etc/user.pk8", "/system/etc/chain-user.pem")
              }
            },
            secondaryButton: {
              value: 'cancel',
              action: () => {
                event.handler.cancel()
              }
            },
            cancel: () => {
              event.handler.ignore()
            }
          })
          return true
        })
    }
  }
}

onPermissionRequest⁹⁺

onPermissionRequest(callback: (event?: { request: PermissionRequest }) => void)

通知收到获取权限请求。

参数：

参数名	参数类型	参数描述
request	PermissionRequest	通知Web组件用户操作行为。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .onPermissionRequest((event) => {
          AlertDialog.show({
            title: 'title',
            message: 'text',
            primaryButton: {
              value: 'deny',
              action: () => {
                event.request.deny()
              }
            },
            secondaryButton: {
              value: 'onConfirm',
              action: () => {
                event.request.grant(event.request.getAccessibleResource())
              }
            },
            cancel: () => {
              event.request.deny()
            }
          })
        })
    }
  }
}

onContextMenuShow⁹⁺

onContextMenuShow(callback: (event?: { param: WebContextMenuParam, result: WebContextMenuResult }) => boolean)

长按特定元素（例如图片，链接）或鼠标右键，跳出菜单。

参数：

参数名	参数类型	参数描述
param	WebContextMenuParam	菜单相关参数。
result	WebContextMenuResult	菜单相应事件传入内核。

返回值：

类型	说明
boolean	自定义菜单返回true，默认菜单返回false。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .onContextMenuShow((event) => {
          console.info("x coord = " + event.param.x())
          console.info("link url = " + event.param.getLinkUrl())
          return true
      })
    }
  }
}

onScroll⁹⁺

onScroll(callback: (event: {xOffset: number, yOffset: number}) => void)

通知网页滚动条滚动位置。

参数：

参数名	参数类型	参数描述
xOffset	number	以网页最左端为基准，水平滚动条滚动所在位置。
yOffset	number	以网页最上端为基准，竖直滚动条滚动所在位置。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
      .onScroll((event) => {
          console.info("x = " + event.xOffset)
          console.info("y = " + event.yOffset)
      })
    }
  }
}

onGeolocationShow

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

通知用户收到地理位置信息获取请求。

参数：

参数名	参数类型	参数描述
origin	string	指定源的字符串索引。
geolocation	JsGeolocation	通知Web组件用户操作行为。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  build() {
    Column() {
      Web({ src:'www.example.com', controller:this.controller })
      .geolocationAccess(true)
      .onGeolocationShow((event) => {
        AlertDialog.show({
          title: 'title',
          message: 'text',
          confirm: {
            value: 'onConfirm',
            action: () => {
              event.geolocation.invoke(event.origin, true, true)
            }
          },
          cancel: () => {
            event.geolocation.invoke(event.origin, false, true)
          }
        })
      })
    }
  }
}

onGeolocationHide

onGeolocationHide(callback: () => void)

通知用户先前被调用onGeolocationShow时收到地理位置信息获取请求已被取消。

参数：

参数名	参数类型	参数描述
callback	() => void	地理位置信息获取请求已被取消的回调函数。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  build() {
    Column() {
      Web({ src:'www.example.com', controller:this.controller })
      .geolocationAccess(true)
      .onGeolocationHide(() => {
        console.log("onGeolocationHide...")
      })
    }
  }
}

onFullScreenEnter⁹⁺

onFullScreenEnter(callback: (event: { handler: FullScreenExitHandler }) => void)

通知开发者web组件进入全屏模式。

参数：

参数名	参数类型	参数描述
handler	FullScreenExitHandler	用于退出全屏模式的函数句柄。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  handler: FullScreenExitHandler = null
  build() {
    Column() {
      Web({ src:'www.example.com', controller:this.controller })
      .onFullScreenEnter((event) => {
        console.log("onFullScreenEnter...")
        this.handler = event.handler
      })
    }
  }
}

onFullScreenExit⁹⁺

onFullScreenExit(callback: () => void)

通知开发者web组件退出全屏模式。

参数：

参数名	参数类型	参数描述
callback	() => void	退出全屏模式时的回调函数。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  handler: FullScreenExitHandler = null
  build() {
    Column() {
      Web({ src:'www.example.com', controller:this.controller })
      .onFullScreenExit(() => {
        console.log("onFullScreenExit...")
        this.handler.exitFullScreen()
      })
      .onFullScreenEnter((event) => {
        this.handler = event.handler
      })
    }
  }
}

onWindowNew⁹⁺

onWindowNew(callback: (event: {isAlert: boolean, isUserTrigger: boolean, targetUrl: string, handler: ControllerHandler}) => void)

使能multiWindowAccess情况下，通知用户新建窗口请求。若不调用event.handler.setWebController接口，会造成render进程阻塞。如果不需要打开新窗口，在调用event.handler.setWebController接口时须设置成null。

参数：

参数名	参数类型	参数描述
isAlert	boolean	true代表请求创建对话框，false代表新标签页。
isUserTrigger	boolean	true代表用户触发，false代表非用户触发。
targetUrl	string	目标url。
handler	ControllerHandler	用于设置新建窗口的WebviewController实例。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'

//在同一page页有两个web组件。在WebComponent新开窗口时，会跳转到NewWebViewComp。
@CustomDialog
struct NewWebViewComp {
controller: CustomDialogController
webviewController1: web_webview.WebviewController
build() {
    Column() {
      Web({ src: "", controller: this.webviewController1 })
        .javaScriptAccess(true)
        .multiWindowAccess(false)
        .onWindowExit(()=> {
          console.info("NewWebViewComp onWindowExit")
          this.controller.close()
        })
      }
  }
}

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  dialogController: CustomDialogController = null
  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .javaScriptAccess(true)
        //需要使能multiWindowAccess
        .multiWindowAccess(true)
        .onWindowNew((event) => {
          if (this.dialogController) {
            this.dialogController.close()
          }
          let popController:web_webview.WebviewController = new web_webview.WebviewController()
          this.dialogController = new CustomDialogController({
            builder: NewWebViewComp({webviewController1: popController})
          })
          this.dialogController.open()
          //将新窗口对应WebviewController返回给Web内核。
          //如果不需要打开新窗口请调用event.handler.setWebController接口设置成null。
          //若不调用event.handler.setWebController接口，会造成render进程阻塞。
          event.handler.setWebController(popController)
        })
    }
  }
}

onWindowExit⁹⁺

onWindowExit(callback: () => void)

通知用户窗口关闭请求。

参数：

参数名	参数类型	参数描述
callback	() => void	窗口请求关闭的回调函数。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  build() {
    Column() {
      Web({ src:'www.example.com', controller: this.controller })
      .onWindowExit(() => {
        console.log("onWindowExit...")
      })
    }
  }
}

onSearchResultReceive⁹⁺

onSearchResultReceive(callback: (event?: {activeMatchOrdinal: number, numberOfMatches: number, isDoneCounting: boolean}) => void): WebAttribute

回调通知调用方网页页内查找的结果。

参数：

参数名	参数类型	参数描述
activeMatchOrdinal	number	当前匹配的查找项的序号（从0开始）。
numberOfMatches	number	所有匹配到的关键词的个数。
isDoneCounting	boolean	当次页内查找操作是否结束。该方法可能会回调多次，直到isDoneCounting为true为止。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'

@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()

  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
   	  .onSearchResultReceive(ret => {
          console.log("on search result receive:" + "[cur]" + ret.activeMatchOrdinal +
            "[total]" + ret.numberOfMatches + "[isDone]"+ ret.isDoneCounting)
        })
    }
  }
}

onDataResubmitted⁹⁺

onDataResubmitted(callback: (event: {handler: DataResubmissionHandler}) => void)

设置网页表单可以重新提交时触发的回调函数。

参数：

参数名	参数类型	参数描述
handler	DataResubmissionHandler	表单数据重新提交句柄。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  build() {
    Column() {
      Web({ src:'www.example.com', controller: this.controller })
       .onDataResubmitted((event) => {
        console.log('onDataResubmitted')
        event.handler.resend();
      })
    }
  }
}

onPageVisible⁹⁺

onPageVisible(callback: (event: {url: string}) => void)

设置旧页面不再呈现，新页面即将可见时触发的回调函数。

参数：

参数名	参数类型	参数描述
url	string	旧页面不再呈现，新页面即将可见时新页面的url地址。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  build() {
    Column() {
      Web({ src:'www.example.com', controller: this.controller })
       .onPageVisible((event) => {
        console.log('onPageVisible url:' + event.url)
      })
    }
  }
}

onInterceptKeyEvent⁹⁺

onInterceptKeyEvent(callback: (event: KeyEvent) => boolean)

设置键盘事件的回调函数，该回调在被Webview使用前触发。

参数：

参数名	参数类型	参数描述
event	KeyEvent	触发的KeyEvent事件。

返回值：

类型	说明
boolean	回调函数通过返回boolean类型值来决定是否继续将该KeyEvent传入Webview内核。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  build() {
    Column() {
      Web({ src:'www.example.com', controller: this.controller })
       .onInterceptKeyEvent((event) => {
        if (event.keyCode == 2017 || event.keyCode == 2018) {
          console.info(`onInterceptKeyEvent get event.keyCode ${event.keyCode}`)
          return true;
        }
        return false;
      })
    }
  }
}

onTouchIconUrlReceived⁹⁺

onTouchIconUrlReceived(callback: (event: {url: string, precomposed: boolean}) => void)

设置接收到apple-touch-icon url地址时的回调函数。

参数：

参数名	参数类型	参数描述
url	string	接收到的apple-touch-icon url地址。
precomposed	boolean	对应apple-touch-icon是否为预合成。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'
@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  build() {
    Column() {
      Web({ src:'www.baidu.com', controller: this.controller })
       .onTouchIconUrlReceived((event) => {
        console.log('onTouchIconUrlReceived:' + JSON.stringify(event))
      })
    }
  }
}

onFaviconReceived⁹⁺

onFaviconReceived(callback: (event: {favicon: image.PixelMap}) => void)

设置应用为当前页面接收到新的favicon时的回调函数。

参数：

参数名	参数类型	参数描述
favicon	PixelMap	接收到的favicon图标的PixelMap对象。

示例：

// xxx.ets
import web_webview from '@ohos.web.webview'
import image from "@ohos.multimedia.image"
@Entry
@Component
struct WebComponent {
  controller: web_webview.WebviewController = new web_webview.WebviewController()
  @State icon: image.PixelMap = undefined;
  build() {
    Column() {
      Web({ src:'www.example.com', controller: this.controller })
       .onFaviconReceived((event) => {
        console.log('onFaviconReceived:' + JSON.stringify(event))
        this.icon = event.favicon;
      })
    }
  }
}

ConsoleMessage

Web组件获取控制台信息对象。示例代码参考onConsole事件。

getLineNumber

getLineNumber(): number

获取ConsoleMessage的行数。

返回值：

类型	说明
number	返回ConsoleMessage的行数。

getMessage

getMessage(): string

获取ConsoleMessage的日志信息。

返回值：

类型	说明
string	返回ConsoleMessage的日志信息。

getMessageLevel

getMessageLevel(): MessageLevel

获取ConsoleMessage的信息级别。

返回值：

类型	说明
MessageLevel	返回ConsoleMessage的信息级别。

getSourceId

getSourceId(): string

获取网页源文件路径和名字。

返回值：

类型	说明
string	返回网页源文件路径和名字。

JsResult

Web组件返回的弹窗确认或弹窗取消功能对象。示例代码参考onAlert事件。

handleCancel

handleCancel(): void

通知Web组件用户取消弹窗操作。

handleConfirm

handleConfirm(): void

通知Web组件用户确认弹窗操作。

handlePromptConfirm⁹⁺

handlePromptConfirm(result: string): void

通知Web组件用户确认弹窗操作及对话框内容。

参数：

参数名	参数类型	必填	默认值	参数描述
result	string	是	-	用户输入的对话框内容。

FullScreenExitHandler⁹⁺

通知开发者Web组件退出全屏。示例代码参考onFullScreenEnter事件。

exitFullScreen⁹⁺

exitFullScreen(): void

通知开发者Web组件退出全屏。

ControllerHandler⁹⁺

设置用户新建web组件的的WebviewController对象。示例代码参考onWindowNew事件。

setWebController⁹⁺

setWebController(controller: WebviewController): void

设置WebviewController对象，如果不需要打开新窗口请设置为null。

参数：

参数名	参数类型	必填	默认值	参数描述
controller	WebviewController	是	-	新建web组件的的WebviewController对象，如果不需要打开新窗口请设置为null。

WebResourceError

web组件资源管理错误信息对象。示例代码参考onErrorReceive事件。

getErrorCode

getErrorCode(): number

获取加载资源的错误码。

返回值：

类型	说明
number	返回加载资源的错误码。

getErrorInfo

getErrorInfo(): string

获取加载资源的错误信息。

返回值：

类型	说明
string	返回加载资源的错误信息。

文章转载自：https://docs.openharmony.cn/pages/v3.2/zh-cn/application-dev/reference/arkui-ts/ts-basic-components-web.md/

分类

标签

已于2023-4-14 15:48:23修改

51CTO

51CTO博客

51CTO学堂

OpenHarmony应用开发-基础组件 Web（上篇）

需要权限

子组件

接口

属性

domStorageAccess

fileAccess

imageAccess

javaScriptProxy

javaScriptAccess

mixedMode

onlineImageAccess

zoomAccess

overviewModeAccess

databaseAccess

geolocationAccess

mediaPlayGestureAccess

multiWindowAccess9+

horizontalScrollBarAccess9+

verticalScrollBarAccess9+

cacheMode

textZoomRatio9+

initialScale9+

userAgent

blockNetwork9+

defaultFixedFontSize9+

defaultFontSize9+

minFontSize9+

minLogicalFontSize9+

webFixedFont9+

webSansSerifFont9+

webSerifFont9+

webStandardFont9+

webFantasyFont9+

webCursiveFont9+

darkMode9+

forceDarkAccess9+

pinchSmooth9+

事件

onAlert

onBeforeUnload

onConfirm

onPrompt9+

onConsole

onDownloadStart

onErrorReceive

onHttpErrorReceive

onPageBegin

onPageEnd

onProgressChange

onTitleReceive

onRefreshAccessedHistory

onRenderExited9+

onShowFileSelector9+

onResourceLoad9+

onScaleChange9+

onUrlLoadIntercept

onInterceptRequest9+

onHttpAuthRequest9+

onSslErrorEventReceive9+

onClientAuthenticationRequest9+

onPermissionRequest9+

onContextMenuShow9+

onScroll9+

onGeolocationShow

onGeolocationHide

onFullScreenEnter9+

onFullScreenExit9+

onWindowNew9+

onWindowExit9+

onSearchResultReceive9+

onDataResubmitted9+

onPageVisible9+

onInterceptKeyEvent9+

onTouchIconUrlReceived9+

onFaviconReceived9+

ConsoleMessage

multiWindowAccess⁹⁺

horizontalScrollBarAccess⁹⁺

verticalScrollBarAccess⁹⁺

textZoomRatio⁹⁺

initialScale⁹⁺

blockNetwork⁹⁺

defaultFixedFontSize⁹⁺

defaultFontSize⁹⁺

minFontSize⁹⁺

minLogicalFontSize⁹⁺

webFixedFont⁹⁺

webSansSerifFont⁹⁺

webSerifFont⁹⁺

webStandardFont⁹⁺

webFantasyFont⁹⁺

webCursiveFont⁹⁺

darkMode⁹⁺

forceDarkAccess⁹⁺

pinchSmooth⁹⁺

onPrompt⁹⁺

onRenderExited⁹⁺

onShowFileSelector⁹⁺

onResourceLoad⁹⁺

onScaleChange⁹⁺

onInterceptRequest⁹⁺

onHttpAuthRequest⁹⁺

onSslErrorEventReceive⁹⁺

onClientAuthenticationRequest⁹⁺

onPermissionRequest⁹⁺

onContextMenuShow⁹⁺

onScroll⁹⁺

onFullScreenEnter⁹⁺

onFullScreenExit⁹⁺

onWindowNew⁹⁺

onWindowExit⁹⁺

onSearchResultReceive⁹⁺

onDataResubmitted⁹⁺

onPageVisible⁹⁺

onInterceptKeyEvent⁹⁺

onTouchIconUrlReceived⁹⁺

onFaviconReceived⁹⁺

handlePromptConfirm⁹⁺

FullScreenExitHandler⁹⁺

exitFullScreen⁹⁺

ControllerHandler⁹⁺

setWebController⁹⁺