webview
Webview模块管理应用窗口界面,实现多窗口的逻辑控制管理操作。通过plus.webview可获取应用界面管理对象。
属性:
- isRecovery: 当前Webview窗口是否由于内核崩溃自动恢复
方法:
- all: 获取所有Webview窗口
- close: 关闭Webview窗口
- create: 创建新的Webview窗口
- currentWebview: 获取当前窗口的WebviewObject对象
- getDisplayWebview: 获取屏幕所有可视的Webview窗口
- getWebviewById: 查找指定标识的WebviewObject窗口
- getLaunchWebview: 获取应用首页WebviewObject窗口对象
- getSecondWebview: 获取应用第二个首页WebviewObject窗口对象
- getTopWebview: 获取应用显示栈顶的WebviewObject窗口对象
- hide: 隐藏Webview窗口
- open: 创建并打开Webview窗口
- prefetchURL: 预载网络页面
- prefetchURLs: 预载网络页面(多个地址)
- show: 显示Webview窗口
- startAnimation: Webview窗口组合动画
- defaultHardwareAccelerated: 获取Webview默认是否开启硬件加速
对象:
- AnimationTypeShow: 一组用于定义页面或控件显示动画效果
- AnimationTypeClose: 一组用于定义页面或控件关闭的动画效果
- WebviewObject: Webview窗口对象,用于操作加载HTML页面的窗口
- WebviewAnimationOptions: Webview窗口动画参数
- WebviewAnimationStyles: Webview窗口动画样式
- WebviewBounceStyle: Webview窗口回弹样式
- WebviewContentAnimationOptions: Webview窗口内容动画参数
- WebviewDock: 原生控件在窗口中停靠的方式
- WebviewDragEvent: Webview窗口滑动事件数据
- WebviewDragOptions: 窗口手势操作参数
- WebviewDragOtherViewOptions: 手势操作关联对象参数
- WebviewDrawOptions: 截屏绘制操作参数
- WebviewFavoriteOptions: 窗口收藏参数
- WebviewLoadDataOptions: 创建加载HTML数据参数
- WebviewShareOptions: 窗口的分享参数
- WebviewSubNViewStyles: 窗口原生子View控件样式
- WebviewTitleNViewStyles: 窗口标题栏控件样式
- WebviewTitleNViewButtonStyles: 窗口标题栏自定义按钮样式
- WebviewTitleNViewSearchInputStyles: 窗口标题栏搜索框样式
- WebviewProgressStyles: 标题栏控件的进度条样式
- WebviewSplitLineStyles: 窗口标题栏控件的分割线样式
- WebviewEvent: Webview窗口事件
- WebviewExtraOptions: JSON对象,原生窗口扩展参数
- WebviewPosition: 原生控件在窗口中显示的位置
- WebviewPullToRefreshStyles: Webview窗口下拉刷新样式
- WebviewRenderedEventOptions: Webview窗口rendered事件参数
- WebviewReplaceWebApiOptions: 替换H5标准API配置信息
- WebviewStatusbarStyles: JSON对象,Webview窗口的系统状态栏区域样式
- WebviewStyles: JSON对象,Webview窗口对象的样式
- WebviewTransform: 一组用于定义页面或控件变形的属性
- WebviewTransition: 一组用于定义页面或控件转换效果的属性
- WebviewOverrideResourceOptions: 拦截Webview窗口资源请求的参数
- WebviewOverrideUrlOptions: 拦截Webview窗口URL请求的属性
- WebviewListenResourceOptions: 监听Webview窗口资源加载的属性
回调方法:
- BounceEventCallback: Webview窗口回弹事件的回调函数
- EventCallback: Webview窗口事件的回调函数
- PopGestureCallback: Webview窗口侧滑事件的回调函数
- HistoryQueryCallback: 历史记录查询的回调函数
- ListenResourceLoadingCallback: Webview窗口加载资源事件的回调函数
- OverrideUrlLoadingCallback: Webview窗口拦截URL链接跳转的回调函数
- TitleUpdateCallback: Webview窗口加载页面标题更新的回调函数
- WebviewAnimationCallback: Webview窗口组合动画回调函数
- WebviewDragCallback: Webview窗口滑屏操作事件回调函数
- WebviewCustomButtonCallback: Webview窗口标题栏上自定义按钮点击事件回调函数
- SuccessCallback: Webview窗口操作成功回调函数
- ErrorCallback: Webview窗口操作失败回调函数
权限:
5+功能模块(permissions)
{ // ... "permissions":{ // ... "Webview": { "description": "窗口管理" } } }
AnimationTypeShow
一组用于定义页面或控件显示动画效果
常量:
- "auto": (String
类型
)自动选择动画效果
自动选择动画效果,使用上次显示窗口设置的动画效果,如果是第一次显示则默认动画效果“none”。
- "none": (String
类型
)无动画效果
立即显示页面,无任何动画效果,页面显示默认的动画效果。 此效果忽略动画时间参数,立即显示。 对应关闭动画"none"。
- "slide-in-right": (String
类型
)从右侧横向滑动效果
页面从屏幕右侧外向内横向滑动显示。 对应关闭动画"slide-out-right"。
- "slide-in-left": (String
类型
)从左侧横向滑动效果
页面从屏幕左侧向右横向滑动显示。 对应关闭动画"slide-out-left"。
- "slide-in-top": (String
类型
)从上侧竖向滑动效果
页面从屏幕上侧向下竖向滑动显示。 对应关闭动画"slide-out-top"。
- "slide-in-bottom": (String
类型
)从下侧竖向滑动效果
页面从屏幕下侧向上竖向滑动显示。 对应关闭动画"slide-out-bottom"。
- "fade-in": (String
类型
)从透明到不透明逐渐显示效果
页面从完全透明到不透明逐渐显示。 对应关闭动画"fade-out"。
- "zoom-out": (String
类型
)从小到大逐渐放大显示效果
页面在屏幕中间从小到大逐渐放大显示。 对应关闭动画"zoom-in"。
- "zoom-fade-out": (String
类型
)从小到大逐渐放大并且从透明到不透明逐渐显示效果
页面在屏幕中间从小到大逐渐放大并且从透明到不透明逐渐显示。 对应关闭动画"zoom-fade-in"。
- "pop-in": (String
类型
)从右侧平移入栈动画效果
页面从屏幕右侧滑入显示,同时上一个页面带阴影效果从屏幕左侧滑出隐藏。 对应关闭动画"pop-out"。
AnimationTypeClose
一组用于定义页面或控件关闭的动画效果
常量:
- "auto": (String
类型
)自动选择动画效果
自动选择显示窗口相对于的动画效果。
- "none": (String
类型
)无动画
立即关闭页面,无任何动画效果。 此效果忽略动画时间参数,立即关闭。
- "slide-out-right": (String
类型
)横向向右侧滑出屏幕动画
页面从屏幕中横向向右侧滑动到屏幕外关闭。
- "slide-out-left": (String
类型
)横向向左侧滑出屏幕动画
页面从屏幕中横向向左侧滑动到屏幕外关闭。
- "slide-out-top": (String
类型
)竖向向上侧滑出屏幕动画
页面从屏幕中竖向向上侧滑动到屏幕外关闭。
- "slide-out-bottom": (String
类型
)竖向向下侧滑出屏幕动画
页面从屏幕中竖向向下侧滑动到屏幕外关闭。
- "fade-out": (String
类型
)从不透明到透明逐渐隐藏动画
页面从不透明到透明逐渐隐藏关闭。
- "zoom-in": (String
类型
)从大逐渐缩小关闭动画
页面逐渐向页面中心缩小关闭。
- "zoom-fade-in": (String
类型
)从大逐渐缩小并且从不透明到透明逐渐隐藏关闭动画
页面逐渐向页面中心缩小并且从不透明到透明逐渐隐藏关闭。
- "pop-out": (String
类型
)从右侧平移出栈动画效果
页面从屏幕右侧滑出消失,同时上一个页面带阴影效果从屏幕左侧滑入显示。
WebviewObject
Webview窗口对象,用于操作加载HTML页面的窗口
属性:
- id: Webview窗口的标识
方法:
- addEventListener: 添加事件监听器
- append: 在Webview窗口中添加子窗口
- appendJsFile: 添加Webview窗口预加载js文件
- animate: Webview窗口内容动画
- back: 后退到上次加载的页面
- beginPullToRefresh: 开始Webview窗口的下拉刷新
- canBack: 查询Webview窗口是否可后退
- canForward: 查询Webview窗口是否可前进
- checkRenderedContent: 检测Webview窗口是否渲染完成
- children: 获取Webview窗口的所有子Webview窗口
- clear: 清空原生Webview窗口加载的内容
- close: 关闭Webview窗口
- drag: 设置Webview窗口的滑屏操作手势
- draw: 截屏绘制
- endPullToRefresh: 结束Webview窗口的下拉刷新
- evalJS: 在Webview窗口中执行JS脚本
- forward: 前进到上次加载的页面
- getFavoriteOptions: 获取Webview窗口的收藏参数
- getSafeAreaInsets: 获取页面的安全区域
- getShareOptions: 获取Webview窗口的分享参数
- getStyle: 获取Webview窗口的样式
- getSubNViews: 获取Webview窗口的原生子View控件对象
- getTitle: 获取Webview窗口加载HTML页面的标题
- getTitleNView: 获取Webview窗口的标题栏控件对象
- getTitleNViewSearchInputText: 获取标题栏上输入框的内容
- getURL: 获取Webview窗口加载HTML页面的地址
- hide: 隐藏Webview窗口
- hideTitleNViewButtonRedDot: 隐藏标题栏上按钮的红点
- interceptTouchEvent: 是否拦截Webview窗口的触屏事件
- isHardwareAccelerated: 查询Webview窗口是否开启硬件加速
- isPause: 查询Webview窗口是否暂停
- isVisible: 查询Webview窗口是否可见
- listenResourceLoading: 监听页面开始加载资源
- loadData: 加载新HTML数据
- loadURL: 加载新URL页面
- nativeInstanceObject: 获取Webview窗口对象的原生(Native.JS)实例对象
- opened: 获取在当前Webview窗口中创建的所有窗口
- opener: 获取当前Webview窗口的创建者
- overrideResourceRequest: 拦截Webview窗口的资源加载
- overrideUrlLoading: 拦截Webview窗口的URL请求
- parent: 获取当前Webview窗口的父窗口
- pause: 暂停当前Webview窗口
- reload: 重新加载Webview窗口显示的HTML页面
- resetBounce: 重置Webview窗口的回弹位置
- restore: 恢复Webview控件显示内容
- remove: 移除子Webview窗口
- removeEventListener: 移除Webview窗口事件监听器
- removeFromParent: 从父窗口中移除
- removeTitleNViewButtonBadge: 移除标题栏上按钮的角标
- resume: 恢复当前Webview窗口
- setBounce: 设置Webview窗口的回弹效果
- setBlockNetworkImage: 设置Webview窗口是否阻塞加载页面中使用的网络图片
- setContentVisible: 设置HTML内容是否可见
- setCssFile: 设置预加载的CSS文件
- setCssText: 设置预加载的CSS内容
- setFavoriteOptions: 设置Webview窗口的收藏参数
- setFixBottom: 设置Webview窗口底部修复区域高度
- setJsFile: 设置预加载的JS文件
- setPullToRefresh: 设置Webview窗口的下拉刷新效果
- setRenderedEventOptions: 设置Webview窗口rendered事件参数
- setSoftinputTemporary: 临时设置弹出系统软键盘样式
- setStyle: 设置Webview窗口的样式
- setShareOptions: 设置Webview窗口的分享参数
- setTitleNViewButtonBadge: 设置标题栏上按钮的角标
- setTitleNViewButtonStyle: 设置标题栏上按钮的样式
- setTitleNViewSearchInputFocus: 设置标题栏上输入框是否获取输入焦点
- setTitleNViewSearchInputText: 设置标题栏上输入框的内容
- setVisible: 设置Webview窗口是否可见
- show: 显示Webview窗口
- showBehind: 在指定Webview窗口后显示
- showTitleNViewButtonRedDot: 设置标题栏上按钮的红点
- stop: 停止加载HTML页面内容
- updateSubNViews: 更新Webview窗口的原生子View控件对象
事件:
- onclose: Webview窗口关闭事件
- onerror: Webview窗口错误事件
- onloaded: Webview窗口页面加载完成事件
- onloading: Webview窗口页面开始加载事件
WebviewAnimationOptions
Webview窗口动画参数
interface WebviewAnimationOptions { attribute WebviewObject view; attribute WebviewAnimationStyles styles; attribute String action; }
说明:
用于指定动画目标窗口,起始位置、目标位置等信息。
属性:
- view: (WebviewObject
类型
)执行动画的窗口对象
可取值Webview窗口对象、Webview窗口的id(String类型)、原生View窗口对象(plus.nativeObj.View)。
- styles: (WebviewAnimationStyles
类型
)动画样式
用于指定动画窗口的起始位置,目标位置等。
- action: (String
类型
)窗口动画完成后的行为
可取值: "none" - 动画完成后不做任何操作; "hide" - 动画完成后隐藏窗口; "close" - 动画完成后关闭窗口。 默认值为"none"。
WebviewAnimationStyles
Webview窗口动画样式
interface WebviewAnimationStyles { attribute String fromLeft; attribute String toLeft; }
说明:
用于指定动画窗口的起始位置、目标位置等信息。
属性:
- fromLeft: (String
类型
)画窗口的起始左侧位置
支持百分比、像素值,默认值为当前窗口的位置。
- toLeft: (String
类型
)画窗口的目标左侧位置
持百分比、像素值。 注意:如果设置的位置与起始位置一直,则无动画效果。
WebviewBounceStyle
Webview窗口回弹样式
属性:
- position: (JSON
类型
)Webview窗口支持回弹效果的方向
可通过此参数设置开启Webview哪个方向支持回弹效果。 支持以下属性: top:表示窗口顶部支持回弹效果; left:表示窗口左侧支持回弹效果; right:表示窗口右侧支持回弹效果; bottom:表示窗口底部支持回弹效果。 **目前仅支持top属性** 属性值:用于指定可拖拽的范围,可取百分比,如"10%";像素值,如"100px";自动计算值,如"auto";无回弹效果值,如"none";
- changeoffset: (JSON
类型
)Webview窗口回弹时停靠的位置
开启窗口回弹效果后,当窗口中展现的内容滚动到头(顶部或底部)时,再拖拽时窗口整体内容将跟随移动,拖拽过程中将触发"dragBounce"事件,松开后自动回弹到停靠位置。 支持以下属性: top:表示窗口顶部回弹时停靠的位置。 属性值:用于指定窗口回弹的位置,可取百分比,如"5%";像素值,如"100px";自动计算值,如"auto",默认为可拖拽的范围值的一半;
- slideoffset: (JSON
类型
)Webview窗口侧滑时停靠的位置
开启窗口回弹效果后,当窗口中展现的内容滚动到头(左侧或右侧)时,在拖拽时窗口整体内容将跟随移动,松开后自动停靠的侧滑位置,并触发"slideBounce"事件。 支持以下属性: left:表示窗口左侧侧滑的位置; right:表示窗口右侧侧滑的位置。 属性值:用于指定滑动后停靠的距离,可取百分比(left/right相对于窗口的宽度,top/bottom相对于窗口的高度),如"30%";像素值,如"100px";自动计算值,为可拖拽范围,如"auto"。
- offset: (JSON
类型
)Webview窗口拖拽偏移的位置
开启窗口回弹效果后,可以通过此属性值来主动设置拖拽的偏移位置,与手动操作拖拽至此偏移位置松开后的逻辑一致。 支持以下属性: top:表示窗口顶部偏移的位置; left:表示窗口左侧偏移的位置; right:表示窗口右侧偏移的位置; bottom:表示窗口底部偏移的位置。 属性值:用于指定偏移的位置,可取百分比,如"5%";像素值,如"100px";有效值范围为0到position属性定义的位置。
- preventTouchEvent: (Boolean
类型
)Webview窗口是否阻止touch事件传递给DOM元素
设置为true表示阻止touch事件,设置为false表示不阻止touch事件。当开启侧滑功能(左侧滑和右侧滑)时默认值为true,否则为false。
WebviewContentAnimationOptions
Webview窗口内容动画参数
interface WebviewAnimationOptions { attribute String type; attribute Number duration; attribute Number frames; attribute Rect region; }
说明:
指定动画的类型、持续时间等信息。
属性:
- type: (String
类型
)动画类型
可取值:"shrink" - 从上到下分块收缩清除窗口动画。
- duration: (Number
类型
)动画持续时间
单位为毫秒,默认值为200ms。
- frames: (Number
类型
)动画帧数
必须为大于0的整数,默认值为12。
- region: (json
类型
)动画作用区域
支持以下属性: top - 区域距离控件顶部的偏移量,属性值可取像素值(如"100px"),百分比(如"10%",相对于控件的高度),默认值为'0px'; bottom - 区域距离控件底部的偏移量,属性值可取像素值(如"100px"),百分比(如"10%",相对于控件的高度),默认值为'0px'; left - 区域距离控件左侧的偏移量,属性值可取像素值(如"100px"),百分比(如"10%",相对于控件的宽度),默认值为'0px'; right - 区域距离控件右侧的偏移量,属性值可取像素值(如"100px"),百分比(如"10%",相对于控件的宽度),默认值为'0px'。 如“{top:'44px',bottom:'48px'}”。
WebviewDock
原生控件在窗口中停靠的方式
常量:
- "top": (String
类型
)控件停靠则页面顶部
- "bottom": (String
类型
)控件停靠在页面底部
- "right": (String
类型
)控件停靠在页面右侧
- "left": (String
类型
)控件停靠在页面左侧
WebviewDragEvent
Webview窗口滑动事件数据
属性:
- direction: (String
类型
)手势类型
可取值: "rtl" - 从右向左滑动手势; "left" - 向左滑动手势,与rtl一致; "ltr" - 从左向右滑动手势; "right" - 向右滑动手势,与ltr一致。
- type: (String
类型
)窗口滑动类型
可取值: "start" - 表示开始滑动操作; "move" - 表示正在滑动; "end" - 表示滑动操作结束。
- result: (String
类型
)窗口滑动结果
可取值: "true" - 表示滑动操作成功; "false" - 表示滑动操作失败(恢复到滑动前的状态); "undefined" - 无状态值(当type值为"end"时返回此值)。
- id: (String
类型
)当前操作窗口标识
当type值为"start"/"move"时,保存当前操作窗口(或View控件)的标识; 当type值为"end"时保存滑动操作后显示窗口(或View控件)的标识(即result值为"true"则认为关联窗口显示,result值为false则认为主窗口显示)。
- otherId: (String
类型
)关联窗口标识
滑动操作关联窗口(或View控件)的标识。
- targetId: (String
类型
)主窗口标识
滑动操作主窗口(或View控件)的标识。
- progress: (Number
类型
)滑动进度
滑动进度位置信息,取值范围为0-100,如20表示滑动了总距离的20%: 当type值为"start"时progress值为0; 当type值为"end"时如果result为true则progress值为0,如果result为false则progress值为100; 当type值为"move"时,保存当前滑动的进度信息(注:多次触发move事件)。
WebviewDragOptions
窗口手势操作参数
属性:
- callbackStep: (Number
类型
)滑屏操作回调事件触发步长
用于设置滑屏回调事件触发频率,取值范围为1-100,值越小触发频率越高,值越大触发频率越小,默认值为20。 如设置值为20,则表示滑屏操作移动距离超过可移动范围的20%则触发一次回调事件,可通过回调函数参数(WebviewDragEvent)的progress属性获取。 注意:触发频率过大会影响效率,开发者需谨慎设置此值。
- direction: (String
类型
)设置的手势类型
可取值: 可取值: "rtl" - 从右向左滑动手势; "left" - 向左滑动手势,与rtl一致; "ltr" - 从左向右滑动手势; "right" - 向右滑动手势,与ltr一致。
- moveMode: (String
类型
)滑动手势模式
可取值: "followFinger" - 当前Webview窗口跟随手指滑动; "silent" - 当前Webview窗口不跟随手指滑动; "bounce" - 当前Webview窗口自动回弹(松手后窗口恢复到拖动前的位置),通常可通过设置此模式来实现Tab项无法继续滑动切换自动回弹效果。
WebviewDragOtherViewOptions
手势操作关联对象参数
属性:
- view: (String
类型
)手势关联对象
可取值Webview窗口的id(String类型)、Webview窗口对象、原生View窗口对象(plus.nativeObj.View)。
- moveMode: (String
类型
)滑动模式
可取值: "follow" - 同步跟随主Webview窗口滑动; "silent" - 不跟随主Webview窗口滑动。
WebviewDrawOptions
截屏绘制操作参数
属性:
- bit: (String
类型
)截屏图片的位深
可取值: "RGB565" - RGB565彩色模式,一个像素占两个字节; "ARGB" - ARGB彩色模式,保存透明度信息。
- check: (Boolean
类型
)是否检测截屏图片是否为空白
可取值: true - 表示检测到截屏到空白图片时认为操作失败(触发错误回调函数); false - 表示不检测,即使为空白图片仍然返回成功。 默认值为false。
- clip: (plus.nativeObj
类型
)设置截屏区域
相对于Webview窗口的区域信息,默认值为{top:'0px',left:'0px',width:'100%',height:'100%'}。
- checkKeyboard: (Boolean
类型
)是否检测当前是否弹出软键盘
可取值: true - 表示检测到弹出软键盘是认为截屏操作失败(触发错误回调函数); false - 表示不检测软键盘状态,直接截屏。 默认值为false。
WebviewFavoriteOptions
窗口收藏参数
说明:
在流应用环境中调用收藏功能时使用的参数。
属性:
- icon: (String
类型
)收藏时显示的图标
在收藏列表中显示的图标,默认使用应用图标。
- title: (String
类型
)收藏时显示的标题
在收藏列表中显示的标题字符串。
- href: (String
类型
)收藏的页面地址
必须是网络地址。
WebviewLoadDataOptions
创建加载HTML数据参数
属性:
- baseURL: (String
类型
)页面的Base URL
- mimeType: (String
类型
)HTML数据的数据类型
默认值为"text/html"。
- encoding: (String
类型
)HTML数据的编码类型
默认值为"utf-8"。
WebviewShareOptions
窗口的分享参数
说明:
在流应用环境中调用分享功能时使用的参数。
属性:
- icon: (String
类型
)分享时使用的图标
默认使用应用图标。
- title: (String
类型
)分享时使用的标题
- href: (String
类型
)分享时使用的链接地址
必须是网络地址。
WebviewSubNViewStyles
窗口原生子View控件样式
说明:
可设置原生控件的标识、大小、位置以及绘制的内容等。
属性:
- id: (String
类型
)原生子View控件的标识
可通过plus.nativeObj.View.getViewById(id)方法传入此标识来获取子View控件对象。
- type: (String
类型
)原生子View控件类型
可取值: "NView" - 原生子View控件(plus.nativeObj.NView); "ImageSlider" - 原生图片轮播控件(plus.nativeObj.ImageSlider)。 默认值为"NView"。
- styles: (ViewStyles
类型
)原生子View控件的样式
可设置原生控件的位置、大小等信息。
- tags: (Array[
ViewDrawTagStyles
]
类型
)原生子View控件初始绘制内容
可设置绘制图片、矩形区域、文本等内容。
WebviewTitleNViewStyles
窗口标题栏控件样式
说明:
标题栏控件固定高度为44px,可通过Webview窗口对象的getTitleNView方法获取标题栏原生控件对象plus.nativeObj.View,调用其方法绘制自定义内容。 可以通过WebviewObject对象的setStyle方法传入titleNView属性更新样式,如wobj.setStyle({titleNView:{titleColor:'#FF0000'}})。
属性:
- autoBackButton: (Boolean
类型
)标题栏控件是否显示左侧返回按钮
可取值: "true" - 显示返回按钮; "false" - 不显示返回按钮。 默认值为"false"。 返回按钮的颜色为窗口标题文字颜色,按下时颜色自动调整透明度为0.3。 点击返回按钮的逻辑与按下系统返回键逻辑一致。
- backgroundColor: (String
类型
)标题栏控件的背景颜色
颜色值格式为"#RRGGBB",如"#FF0000"表示为红色背景; "rgba(R,G,B,A)",如rgba(255,0,0,0.5)表示半透明红色背景。 默认值为"#F7F7F7"。
- blurEffect: (String
类型
)模糊(毛玻璃)效果
此效果将会高斯模糊显示标题栏后的内容,仅在type为"transparent"或"float"时有效。 可取值: "dark" - 暗风格模糊,对应iOS原生UIBlurEffectStyleDark效果; "extralight" - 高亮风格模糊,对应iOS原生UIBlurEffectStyleExtraLight效果; "light" - 亮风格模糊,对应iOS原生UIBlurEffectStyleLight效果; "none" - 无模糊效果。 HBuilderX2.4.3+版本支持,默认值为"none"。 注意:使用模糊效果时应避免设置背景颜色,设置背景颜色可能覆盖模糊效果。
- buttons: (Array[
WebviewTitleNViewButtonStyles
]
类型
)标题栏上的自定义按钮
创建的自定义按钮数目不限制,实际应用中建议最多设置4个按钮(包括左侧返回按钮)。 注意:此属性不支持动态修改,仅在创建titleNView时设置有效。
- coverage: (String
类型
)标题栏控件变化作用范围
仅在type值为transparent时有效,页面滚动时标题栏背景透明度将发生变化。 当页面滚动到指定偏移量时标题栏背景变为完全不透明。 支持百分比、像素值,默认为'132px'。
- homeButton: (Boolean
类型
)标题栏控件是否显示Home按钮
可取值: "true" - 显示Home按钮; "false" - 不显示Home按钮。 默认值为"false"。 Home按钮的颜色为窗口标题文字颜色,按下时颜色自动调整透明度为0.3。 点击Home按钮的逻辑为关闭所有非首页窗口,显示首页窗口。
- padding: (String
类型
)内边距
标题栏左右的内边距,单位为px(逻辑像素值),如"10px"表示10逻辑像素值。 默认值为"0px"。
- padding-right: (String
类型
)右内边距
标题栏右侧内边距,单位为px(逻辑像素值),如"10px"表示10逻辑像素值。 默认值为"0px",优先级padding-right > padding。
- padding-left: (String
类型
)左内边距
标题栏左侧内边距,单位为px(逻辑像素值),如"10px"表示10逻辑像素值。 默认值为"0px",优先级padding-left > padding。
- progress: (WebviewProgressStyles
类型
)标题栏控件的进度条样式
设置此属性则在标题栏控件的底部显示进度条,可配置进度条颜色值即高度。 设置此属性值为undefined或null则隐藏进度条。 默认不显示底部进度条。 注意:此属性将废弃,推荐使用WebviewStyles的progress。
- searchInput: (WebviewTitleNViewSearchInputStyles
类型
)标题栏上的搜索框样式
- splitLine: (WebviewSplitLineStyles
类型
)标题栏控件的底部分割线
设置此属性则在标题栏控件的底部显示分割线,可配置颜色值及高度。 设置此属性值为undefined或null则隐藏分割线。 默认不显示底部分割线。
- tags: (Array[
ViewDrawTagStyles
]
类型
)标题栏上初始自定义绘制内容
可用于设置自定义绘制图片、矩形区域、文本等内容。 注意:此属性不支持动态修改,仅在创建titleNView时设置有效,如果需要更新绘制内容可根据tags的id调用draw方法操作。
- titleColor: (String
类型
)标题栏控件的标题文字颜色
颜色值格式为"#RRGGBB"和"rgba(R,G,B,A)",如"#FF0000"表示标题文字颜色为红色。 type=transparent时默认值为"#FFFFFF",其它情况默认值为"#000000"。
- titleOverflow: (String
类型
)标题栏控件的标题文字超出显示区域时处理方式
可取值: "clip" - 超出显示区域时内容裁剪; "ellipsis" - 超出显示区域时尾部显示省略标记(...)。 默认值为"ellipsis"。
- titleText: (String
类型
)标题栏控件的标题文字内容
在标题栏控件居中(水平和垂直)显示,左右边距为88px,如果文本过长则尾部裁剪(加三个点"...")显示。 当不设置titleText属性或属性值为undefined/null时,使用当前Webview窗口加载页面的标题,并自动同步更新页面的标题。
- titleSize: (String
类型
)标题栏控件的标题文字字体大小
字体大小单位为像素,如"20px"表示字体大小为20像素,默认值为17像素。
- type: (String
类型
)标题栏控件样式
可取值: "default" - 默认样式,顶部停靠显示,挤压Webview页面内容显示区域; "transparent" - 透明样式,顶部沉浸式显示覆盖Webview页面内容,标题栏上内容(除按钮外)全部透明,当页面滚动时透明度逐渐变化,直到不透明显示; "float" - 悬浮样式,顶部悬浮显示,标题栏覆盖在Webview上,此时应该设置标题栏背景颜色(backgroundColor)为半透明才能透视到覆盖Webview的内容。 默认值为"default"。 注意:此属性不支持动态更新。
WebviewTitleNViewButtonStyles
窗口标题栏自定义按钮样式
属性:
- type: (String
类型
)按钮样式
运行环境中内置按钮样式直接使用,内置样式忽略fontSrc和text属性。 可取值: "forward" - 前进按钮; "back" - 后退按钮; "share" - 分享按钮; "favorite" - 收藏按钮; "home" - 主页按钮; "menu" - 菜单按钮; "close" - 关闭按钮; "none" - 无样式。 默认值为无样式("none"),需通过text属性设置按钮上显示的内容、通过fontSrc属性设置使用的字体库。
- background: (String
类型
)按钮的背景颜色
仅在标题栏type=transparent时生效,当标题栏透明时按钮显示的背景颜色。 可取值#RRGGBB和rgba格式颜色字符串,默认值为灰色半透明。
- badgeText: (String
类型
)按钮上显示的角标文本
最多显示3个字符,超过则显示为...。
- color: (String
类型
)按钮上文字颜色
可取值: "#RRGGBB"格式字符串,如"#FF0000"表示绘制红色返回键; "rgba(R,G,B,A)",其中R/G/B分别代表红色值/绿色值/蓝色值,正整数类型,取值范围为0-255,A为透明度,浮点数类型,取值范围为0-1(0为全透明,1为不透明),如"rgba(255,0,0,0.5)",表示红色半透明。 默认值为窗口标题栏控件的标题文字颜色。
- colorPressed: (String
类型
)按下状态按钮文字颜色
可取值: "#RRGGBB"格式字符串,如"#FF0000"表示绘制红色返回键; "rgba(R,G,B,A)",其中R/G/B分别代表红色值/绿色值/蓝色值,正整数类型,取值范围为0-255,A为透明度,浮点数类型,取值范围为0-1(0为全透明,1为不透明),如"rgba(255,0,0,0.5)",表示红色半透明。 默认值为color属性值自动调整透明度为0.3。
- float: (String
类型
)按钮在标题栏上的显示位置
可取值: "right" - 在标题栏中靠右排列显示; "left" - 在标题栏中靠左侧排列显示(在返回键后)。 默认值为"right"。
- fontWeight: (String
类型
)按钮上文字的粗细
可取值: "normal" - 标准字体; "bold" - 加粗字体。 默认值为"normal"。
- fontSize: (String
类型
)按钮上文字大小
可取值:字体高度像素值,数字加"px"格式字符串,如"22px"。 窗口标题栏为透明样式(type="transparent")时,默认值为"22px"; 窗口标题栏为默认样式(type="default")时,默认值为"27px"。
- fontSrc: (String
类型
)按钮上文字使用的字体文件路径
字体文件路径支持以下类型: 相对路径 - 相对于当前页面的host位置,如"a.ttf",注意当前页面为网络地址则不支持; 绝对路径 - 系统绝对路径,如Android平台"/sdcard/a.ttf",此类路径通常通过其它5+ API获取的; 扩展相对路径URL(RelativeURL) - 以"_"开头的相对路径,如"_www/a.ttf"; 本地路径URL - 以“file://”开头,后面跟随系统绝对路径。
- onclick: (WebviewCustomButtonCallback
类型
)按钮点击后触发的回调函数
回调函数中将返回此JSON对象。
- redDot: (Boolean
类型
)按钮上是否显示红点
设置为true则显示红点,false则不显示红点。默认值为false。 注意:当设置了角标文本时红点不显示。
- select: (Boolean
类型
)是否显示选择指示图标
设置为true则显示选择指示图标(向下箭头),颜色与文字颜色一致; false则不显示。默认值为false。
- text: (String
类型
)按钮上显示的文字
推荐使用一个字符,超过一个字符可能无法正常显示,使用字体图标时unicode字符表示必须'\u'开头,如"\ue123"(注意不能写成"\e123")。
- width: (String
类型
)按钮的宽度
可取值: "*px" - 逻辑像素值,如"10px"表示10逻辑像素值,按钮的内容居中显示; "auto" - 自定计算宽度,根据内容自动调整按钮宽度。 默认值为"44px"(适合字体图标)。
WebviewTitleNViewSearchInputStyles
窗口标题栏搜索框样式
说明:
搜索输入框输入内容变化时触发"titleNViewSearchInputChanged"事件; 用户点击软键盘上的“搜索”按钮时触发"titleNViewSearchInputConfirmed"事件。
属性:
- autoFocus: (Boolean
类型
)是否自动获取焦点
设置为true表示自动获取焦点,当窗口显示时搜索编辑框自动获取输入焦点(弹出软键盘)。 默认值为false。
- align: (String
类型
)非输入状态下文本的对齐方式
可取值: "left" - 居左对齐; "right" - 居右对齐; "center" - 居中对齐。 默认值为"center"(居中对齐)。
- backgroundColor: (String
类型
)背景颜色
颜色值格式为"#RRGGBB"和"rgba(R,G,B,A)",如"#FF0000"表示背景颜色为红色。 默认值为白色半透明"rgba(255,255,255,0.5)"。
- borderRadius: (String
类型
)输入框的圆角半径
取值格式为"XXpx",其中XX为像素值(逻辑像素),如"10px"表示10像素半径圆角。 默认值为无圆角。
- placeholder: (String
类型
)提示文本
输入框未获取输入焦点时显示的文本内容,输入框获取输入焦点时内容为空时显示的文本内容。
- placeholderColor: (String
类型
)提示文本颜色
颜色值格式为"#RRGGBB"和"rgba(R,G,B,A)",如"#FF0000"表示提示文本颜色为红色。 默认值为"#CCCCCC"。
- disabled: (Boolean
类型
)是否可输入
编辑框可输入时,点击编辑框可获取输入焦点(弹出软键盘); 编辑框不可输入时,点击编辑框触发"titleNViewSearchInputClicked"事件。 默认值为false。
WebviewProgressStyles
标题栏控件的进度条样式
说明:
显示在标题栏控件底部。
属性:
- color: (String
类型
)进度条颜色
可取值: "#RRGGBB"格式字符串,如"#FF0000"表示绘制红色分割线; "rgba(R,G,B,A)",其中R/G/B分别代表红色值/绿色值/蓝色值,正整数类型,取值范围为0-255,A为透明度,浮点数类型,取值范围为0-1(0为全透明,1为不透明),如"rgba(255,0,0,0.5)",表示红色半透明。 默认值为"#00FF00"。
- height: (String
类型
)进度条高度
可取值:像素值(逻辑像素),支持小数点,如"1px"表示1像素高;百分比,如"1%",相对于标题栏控件的高度。 默认值为"2px"。
WebviewSplitLineStyles
窗口标题栏控件的分割线样式
说明:
显示在标题栏控件底部。
属性:
- color: (String
类型
)底部分割线颜色
可取值: "#RRGGBB"格式字符串,如"#FF0000"表示绘制红色分割线; "rgba(R,G,B,A)",其中R/G/B分别代表红色值/绿色值/蓝色值,正整数类型,取值范围为0-255,A为透明度,浮点数类型,取值范围为0-1(0为全透明,1为不透明),如"rgba(255,0,0,0.5)",表示红色半透明。 默认值为"#CCCCCC"。
- height: (String
类型
)底部分割线高度
可取值:像素值(逻辑像素),支持小数点,如"1px"表示1像素高;百分比,如"1%",相对于标题栏控件的高度。 默认值为"1px"。
WebviewEvent
Webview窗口事件
常量:
- "close": (String
类型
)Webview窗口关闭事件
通过WebviewObject对象的addEventListener方法添加事件监听函数,当Webview窗口关闭时触发此事件,回调函数类型为EventCallback。
- "dragBounce": (String
类型
)Webview窗口回弹事件
通过WebviewObject对象的setBounce方法开启回弹效果设置顶部下拉回弹changeoffset属性后,当用户向下拖拽窗口时触发发此事件,回调函数类型为BounceEventCallback。
- "slideBounce": (String
类型
)Webview窗口回弹事件
通过WebviewObject对象的setBounce方法开启回弹效果设置左右侧侧滑slideoffset属性后,当用户向左右侧拖拽窗口侧滑时触发发此事件,回调函数类型为BounceEventCallback。
- "error": (String
类型
)Webview窗口加载错误事件
通过WebviewObject对象的addEventListener方法添加事件监听函数,当Webview窗口加载错误时触发此事件,回调函数类型为EventCallback。
- "hide": (String
类型
)Webview窗口隐藏事件
通过WebviewObject对象的addEventListener方法添加事件监听函数,当Webview窗口隐藏(窗口动画完成后)时触发此事件,回调函数类型为EventCallback。
- "loading": (String
类型
)Webview窗口页面开始加载事件
通过WebviewObject对象的addEventListener方法添加事件监听函数,当Webview窗口开始加载新页面时触发此事件,回调函数类型为EventCallback。
- "loaded": (String
类型
)Webview窗口页面加载完成事件
通过WebviewObject对象的addEventListener方法添加事件监听函数,当Webview窗口页面加载完成时触发此事件,回调函数类型为EventCallback。
- "maskClick": (String
类型
)Webview窗口显示遮罩层时点击事件
通过WebviewObject对象的addEventListener方法添加事件监听函数,当Webview窗口通过mask属性设置显示遮罩层并且点击时触发此事件,回调函数类型为EventCallback。
- "recovery": (String
类型
)Webview内核崩溃事件
iOS平台使用WKWebview时,当系统内存不足时可能会导致WKWebview内核崩溃(页面白屏)。 此时会触发recovery事件。
- "rendering": (String
类型
)Webview窗口开始渲染事件
通过WebviewObject对象的addEventListener方法添加事件监听函数,当Webview窗口开始渲染内容时触发此事件,回调函数类型为EventCallback。
- "rendered": (String
类型
)Webview窗口渲染完成事件
通过WebviewObject对象的addEventListener方法添加事件监听函数,当Webview窗口渲染完成时触发此事件,回调函数类型为EventCallback。
- "show": (String
类型
)Webview窗口显示事件
通过WebviewObject对象的addEventListener方法添加事件监听函数,当Webview窗口显示(窗口动画完成后)时触发此事件,回调函数类型为EventCallback。
- "titleNViewSearchInputChanged": (String
类型
)Webview标题栏搜索框输入内容更新事件
当页面配置原生标题栏显示搜索框,在搜索框获取焦点输入的内容发生变化时触发。
- "titleNViewSearchInputConfirmed": (String
类型
)Webview标题栏搜索框输入确认事件
当页面配置原生标题栏显示搜索框,在搜索框获取完成(用户点击软键盘的“搜索”按钮)时触发。
- "titleNViewSearchInputClicked": (String
类型
)Webview标题栏搜索框点击事件
当页面配置原生标题栏显示搜索框并设置disabled为true,点击搜索输入框时触发。
- "titleNViewSearchInputFocusChanged": (String
类型
)Webview标题栏搜索框焦点变化事件
当页面配置原生标题栏显示搜索框,搜索框的输入焦点发生变化时触发。 回调函数中的focus属性值为true表示获取焦点,false表示失去焦点。
- "titleUpdate": (String
类型
)Webview加载页面标题更新事件
通过WebviewObject对象的addEventListener方法添加事件监听函数,当Webview窗口加载新页面更新标题时触发此事件,回调函数类型为SuccessCallback。 注意:此事件会先于loaded事件触发,通常在加载网络页面时通过此事件可更快获取到页面的标题。
- "touchstart": (String
类型
)Webview窗口接收到触屏事件
通过WebviewObject对象的addEventListener方法添加事件监听函数,当用户操作按下到Webview窗口时触发此事件,回调函数类型为SuccessCallback。 注意:每按下屏幕触发一次此事件。
- "popGesture": (String
类型
)Webview窗口侧滑返回事件
通过WebviewObject对象的addEventListener方法添加事件监听函数,当Webview窗口侧滑返回时触发此事件,回调函数类型为PopGestureCallback。
- "progressChanged": (String
类型
)Webview窗口加载进度变化事件
通过WebviewObject对象的addEventListener方法添加事件监听函数,当Webview窗口加载页面进度变化时触发此事件。 回调函数原型为void PorgressCandedCallback(Event e),可通过e.progress获取窗口加载进度,取值范围为0-100。
- "pullToRefresh": (String
类型
)Webview窗口下拉刷新事件
Webview窗口打开下拉刷新功能后,用户操作下拉刷新时或调用beginPullToRefresh方法时触发,用于通知业务逻辑可以开始执行刷新操作。 更新操作完成后调用窗口的endPullToRefresh方法结束下拉刷新。
- "webPause": (String
类型
)Webview窗口暂停事件
Webview窗口被暂停(pause)时触发。
- "webResume": (String
类型
)Webview窗口恢复事件
Webview窗口从暂停(pause)状态恢复(resume)时触发。
WebviewExtraOptions
JSON对象,原生窗口扩展参数
属性:
- acceleration: (String
类型
)窗口动画加速
开启窗口动画加速功能可优化窗口动画效果,提升动画流程度,可避免部分设备上打开(关闭)窗口闪屏的问题。 可取值: "auto" - 自动优化窗口动画; "none" - 关闭窗口动画加速功能; "capture" - 使用截屏方式加速窗口动画。 默认值为"auto"。
- capture: (Bitmap
类型
)窗口动画加速时使用的图片
当使用截屏方式加速窗口动画时,可设置已经创建好的截屏图片,此时不会进行实时截屏操作,加速窗口动画响应时间,提升用户体验。 如果未指定截屏图片,则实时截取当前Webview窗口对象的图片进行动画操作。 如果窗口未使用截屏方式加速动画,则忽略此参数。
- otherCapture: (Bitmap
类型
)关联窗口动画使用的图片
当使用截屏方式加速窗口动画时,可设置已经创建好的截屏图片,此时不会进行实时截屏操作,加速关联窗口动画响应时间,提升用户体验。 如果未指定截屏图片,则实时截取关联Webview窗口对象的图片进行动画操作。 如果窗口未使用截屏方式加速动画,则忽略此参数。
WebviewPosition
原生控件在窗口中显示的位置
常量:
- "static": (String
类型
)控件在页面中正常定位,如果页面存在滚动条则随窗口内容滚动
- "absolute": (String
类型
)控件在页面中绝对定位,如果页面存在滚动条不随窗口内容滚动
- "dock": (String
类型
)控件在页面中停靠,停靠的位置通过dock属性进行定义
WebviewPullToRefreshStyles
Webview窗口下拉刷新样式
属性:
- support: (Boolean
类型
)是否开启Webview窗口的下拉刷新功能
true表示开启窗口的下拉刷新功能; false表示关闭窗口的下拉刷新功能。
- color: (String
类型
)下拉刷新控件颜色
颜色值格式为"#RRGGBB",如"#FF0000"为设置下拉属性控件为红色,默认值为"#2BD009"。
- style: (String
类型
)下拉刷新样式
用于定义下拉刷新风格样式,可取值: "default" - 经典下拉刷新样式(下拉拖动时页面内容跟随); "circle" - 圆圈样式下拉刷新控件样式(下拉拖动时仅刷新控件跟随)。 默认值为"default"。
- height: (String
类型
)窗口的下拉刷新控件进入刷新状态的拉拽高度
支持百分比,如"10%";像素值,如"50px"。
- range: (String
类型
)窗口可下拉拖拽的范围
支持百分比,如"10%";像素值,如"50px"。
- offset: (String
类型
)下拉刷新控件的起始位置
仅对"circle"样式下拉刷新控件有效,用于定义刷新控件下拉时的起始位置。 相对于Webview的顶部偏移量,支持百分比,如"10%";像素值,如"50px"。 默认值为"0px"。
- contentdown: (JSON
类型
)在下拉可刷新状态时显示的内容
支持以下属性: caption:在下拉可刷新状态时下拉刷新控件上显示的标题内容。
- contentover: (JSON
类型
)在释放可刷新状态时显示的内容
支持以下属性: caption:在释放可刷新状态时下拉刷新控件上显示的标题内容。
- contentrefresh: (JSON
类型
)在正在刷新状态时显示的内容
支持以下属性: caption:在正在刷新状态时下拉刷新控件上显示的标题内容。
WebviewRenderedEventOptions
Webview窗口rendered事件参数
属性:
- type: (String
类型
)判断窗口渲染完成类型
可取值: "top"-从顶部向下偏移22px横线截屏检测渲染是否完成; "bottom"-从底部向上偏移25px横线检测渲染是否完成; "center"-从中间横线检测渲染是否完成; "auto"为全屏检测(左、中、右三条竖线)。 默认值为"auto"。
- interval: (Number
类型
)判断窗口渲染完成间隔时间
单位为ms(毫秒),默认值为150ms。
WebviewReplaceWebApiOptions
替换H5标准API配置信息
说明:
目前仅支持替换H5标准定位接口
属性:
- geolocation: (String
类型
)替换H5标准定位接口(navigator.geolocation.*)
由于网络原因,在部分手机上可能无法调用标准H5定位接口(navigator.geolocation.*)获取定位数据,此时可以通过此属性配置使用原生定位模块替换标准H5定位接口,可取值: "alldevice" - 在所有设备上替换标准H5定位接口(navigator.geolocation.*); "auto" - 自动替换H5标准定位接口,仅在调用标准H5定位接口无法获取数据的设备上替换; "none" - 不替换H5标准定位接口(navigator.geolocation.*)。 默认值为"none"。 注意:替换H5标准定位接口,会导致页面加载速度延迟100ms左右,推荐使用"auto"模式。
WebviewStatusbarStyles
JSON对象,Webview窗口的系统状态栏区域样式
说明:
仅在应用设置为沉浸式状态栏样式下有效,非沉浸式状态栏样式下忽略此属性。
属性:
- background: (String
类型
)系统状态栏区域背景颜色
颜色值格式为"#RRGGBB",如"#FF0000"表示为红色背景。 默认值为应用manifest.json中plus->statusbar->background属性配置的值,如果未配置此属性值,则使用系统默认状态栏的背景颜色。
WebviewStyles
JSON对象,Webview窗口对象的样式
属性:
- additionalHttpHeaders: (JSON
类型
)窗口加载页面时额外添加的HTTP请求头数据
仅在Webview窗口第一次加载页面时使用,如用户点击的触发的链接跳转则不再添加此额外请求头数据。 如果Webview窗口非第一次加载页面时也需要额外添加HTTP请求头数据,可通过loadURL()方法的参数设置。 如果HTTP请求头中已经包含需要额外添加的头数据,则添加的请求数据覆盖默认值。
- animationOptimization: (String
类型
)窗口动画优化方式
可取值: "auto" - 如果窗口中存在titleNView或subNViews,窗口动画时真实Webview控件从动画窗口中移除加速(避免真实Webview渲染影响动画效率); "none" - 窗口动画不使用优化。 默认值为"auto"。
- cachemode: (String
类型
)窗口的缓存模式
可取值: "default" - 根据cache-control决定是否使用缓存数据,如果存在缓存并且没有过期则使用本地缓存资源,否则从网络获取; "cacheElseNetwork" - 只要存在缓存(即使过期)数据则使用,否则从网络获取; "noCache" - 不使用缓存数据,全部从网络获取; "cacheOnly" - 仅使用缓存数据,不从网络获取(注:如果没有缓存数据则会导致加载失败)。 默认使用"default"。
- backButtonAutoControl: (String
类型
)Webview窗口自动处理返回键逻辑
当Webview窗口在显示栈顶,并且Webview窗口中没有调用JS监听返回键(plus.key.addEventListener('backbutton',...))时按下返回键响应行为。 可取值: "hide" - 隐藏Webview窗口,隐藏动画与上一次调用显示时设置的动画类型相对应(如“slide-in-right”对应的关闭动画为“slid-out-right”); "close" - 关闭Webview窗口,关闭动画与上一次调用显示时设置的动画类型相对应(如“slide-in-right”对应的关闭动画为“slid-out-right”) ; "none" - 不做操作,将返回键传递给下一Webview窗口处理; "quit" - 退出应用。
- background: (String
类型
)窗口的背景颜色
窗口空白区域的背景模式,设置background为颜色值(参考CSS Color Names,可取值/十六进制值/rgb值/rgba值),窗口为独占模式显示(占整个屏幕区域); 设置background为“transparent”,则表示窗口背景透明,为非独占模式。
- backgroundColorTop: (String
类型
)窗口顶部背景颜色值
窗口内容滚动到顶部下拉时可见。 可取值: "#RRGGBB"格式字符串,如"#FF0000"表示红色; "rgba(R,G,B,A)",其中R/G/B分别代表红色值/绿色值/蓝色值,正整数类型,取值范围为0-255,A为透明度,浮点数类型,取值范围为0-1(0为全透明,1为不透明),如"rgba(255,0,0,0.5)",表示红色半透明。 默认值为透明。
- backgroundColorBottom: (String
类型
)窗口底部背景颜色
窗口内容滚动到底部上拉时可见。 可取值: "#RRGGBB"格式字符串,如"#FF0000"表示红色; "rgba(R,G,B,A)",其中R/G/B分别代表红色值/绿色值/蓝色值,正整数类型,取值范围为0-255,A为透明度,浮点数类型,取值范围为0-1(0为全透明,1为不透明),如"rgba(255,0,0,0.5)",表示红色半透明。 默认值为透明。
- blockNetworkImage: (Boolean
类型
)是否阻塞网络图片的加载
布尔类型,true表示阻塞,false表示不阻塞,默认值为false。 阻塞后Webview窗口将不加载页面中使用的所有网络图片,可通过Webview窗口对象的setBlockNetWorkImage()方法动态修改此状态。
- bottom: (String
类型
)窗口垂直向上的偏移量
支持百分比、像素值,默认值无值(根据top和height属性值来自动计算)。 当同时设置了top和height值时,忽略此属性值; 当未设置height值时,可通过top和bottom属性值来确定窗口的高度。
- bounce: (String
类型
)窗口遇到边框是否有反弹效果
可取值: "none" - 表示没有反弹效果; "vertical" - 表示垂直方向有反弹效果; "horizontal" - 表示水平方向有反弹效果; "all" - 表示垂直和水平方向都有反弹效果。 默认值为"none"。
- bounceBackground: (String
类型
)窗口回弹效果区域的背景
窗口回弹效果区域背景可支持颜色值或图片: 颜色值格式为"#RRGGBB",如"#FFFFFF"为设置白色背景; 背景图为"url(%image path%)",如"url(./icon.png)"为设置icon.png为背景图,图片采用平铺模式绘制。
- decelerationRate: (Number
类型
)窗口内容停止滑动的减速度
当Webview加载的内容超过其高度时,可以拖拽滑动内容,decelerationRate属性控制手指松开后页面滑动的速度。 设置值越大手指松开后的滑动速度越快(滑动距离越长),其值域范围为0.0-1.0,默认值为0.989。
- dock: (WebviewDock
类型
)窗口的停靠方式
当Webview窗口添加到另外一个窗口中时,停靠方式才会生效,采用停靠方式添加会导致原Webview窗口自动调整其大小避免其内容被子窗口盖住。 可取值:"top",控件停靠则页面顶部;"bottom",控件停靠在页面底部;"right",控件停靠在页面右侧;"left",控件停靠在页面左侧。 默认值为"bottom"。
- errorPage: (String
类型
)窗口加载错误时跳转的页面地址
当Webview窗口无法加载指定的url地址时(如本地页面不存在,或者无法访问的网络地址),此时会自动跳转到指定的错误页面地址(仅支持本地页面地址)。 设置为“none”则关闭跳转到错误页面功能,此时页面显示Webview默认的错误页面内容。默认使用5+ Runtime内置的错误页面。
- replacewebapi: (WebviewReplaceWebApiOptions
类型
)替换H5标准API
用于解决在部分设备上调用H5标准定位接口可能无法获取定位数据的问题。
- hardwareAccelerated: (Boolean
类型
)窗口是否开启硬件加速
布尔类型,true表示开启硬件加速,false表示不开启硬件加速,默认情况5+ Runtime会根据设备实际支持情况自动选择是否开启硬件加速,可以通过plus.webview.defaultHardwareAccelerated()方法获取默认Webview是否开启硬件加速。 由于不同设备对硬件加速的支持情况存在差异,开启硬件加速能加速HTML页面的渲染,但也会消耗更多的系统资源,从而导致在部分设备上可能出现闪屏、发虚、分块渲染等问题,因此在特定设备的特定页面如果出现以上问题需要手动设置关闭硬件加速来避免。
- height: (String
类型
)窗口的高度
支持百分比、像素值,默认为100%。 当未设置height属性值时,优先通过top和bottom属性值来计算窗口的高度。
- kernel: (String
类型
)窗口使用的内核
可取值: "WKWebview" - 在iOS8.0及以上系统使用WKWebview内核,低版本下仍然使用UIWebview内核; "UIWebview" - 在所有版本上都使用UIWebview内核。 默认值为"UIWebview"。 WKWebview内核的优势是: 1. 滚动时懒加载的图片也可以实时渲染,UIWebview在滚动停止后才能渲染; 2. WKWebview的video支持AirPlay。 但WKWebview也有些限制和不足,目前已知的问题有: 1. 不支持跨域设置cookie,即plus.navigator.setCookie()API无法使用; 2. 本地的HTML页面中的XHR不支持跨域访问,需使用plus.net.XMLHttpRequest来替换; 3. 不支持使用WebSQL,需使用indexDB来替换; 4. 不支持js原生混淆功能,需使用前端js混淆来替换; 5. 内存不足时会白屏。 首页的Webview的kernel在manifest中配置(plus->kernel->ios)。
- kernelRecovery: (String
类型
)Webview内核崩溃后的恢复处理逻辑
仅iOS平台非uni-app项目使用WKWebview时生效,uni-app项目可自动恢复(推荐转换为uni-app项目) 当前WKWebview崩溃后,Webview页面的JS上下文将丢失,也无法渲染DOM内容(白屏) 可配置以下值: "restart" - 重启应用,关闭所有页面重新打开应用首页,可通过(plus.runtime.isRecovery)来判断应用是否恢复重启; "reload" - 重新加载当前WKWebview(崩溃的WKWebview)页面,页面中JS上下文中所有数据丢失,在当前Webview中可通过plus.webview.isRecovery判断是否恢复重新加载,在其它Webview中可监听recovery事件来判断; "none" - 不做任何操作。 默认为manifest.json中plus -> kernel -> recovery配置的值。
- left: (String
类型
)窗口水平向右的偏移量
支持百分比、像素值,默认值为0px。 未设置left属性值时,优先通过right和width属性值来计算窗口的left位置。
- margin: (String
类型
)窗口的边距
用于定位窗口的位置,支持auto,auto表示居中。若设置了left、right、top、bottom则对应的边距值失效。
- mask: (String
类型
)窗口的遮罩
用于设置Webview窗口的遮罩层样式,遮罩层会覆盖Webview中所有内容,包括子webview,并且截获webview的所有触屏事件,此时Webview窗口的点击操作会触发maskClick事件。 字符串类型,可取值: rgba格式字符串,定义纯色遮罩层样式,如"rgba(0,0,0,0.5)",表示黑色半透明; "none",表示不使用遮罩层; 默认值为"none",即无遮罩层。
- opacity: (Number
类型
)窗口的不透明度
0为全透明,1为不透明,默认值为1,即不透明。
- plusrequire: (String
类型
)控制Webview注入5+ API时机
可取值: "ahead" - 尽量提前注入,拦截页面中网络js请求实现提前注入,如果没有拦截到js请求则在页面loaded时注入; "normal" - 页面loaded时注入; "later" - 较晚在注入,在loaded事件发生后2s再注入,plusready事件同样延迟触发; "none" - 不注入,页面无法调用5+ API,不触发plusready事件。 默认值为"normal"。
- progress: (WebviewProgressStyles
类型
)窗口的进度条样式
设置此属性则在Webview窗口的顶部显示进度条,可配置进度条颜色及高度。 设置此属性值为undefined或null则隐藏进度条。 默认不显示进度条。
- popGesture: (String
类型
)窗口的侧滑返回功能
可取值: "none"-无侧滑返回功能; "close"-侧滑返回关闭Webview窗口; "hide"-侧滑返回隐藏webview窗口。
- pullToRefresh: (WebviewPullToRefreshStyles
类型
)窗口下拉刷新配置
设置窗口是否开启下拉刷新功能及样式。 开启下拉刷新后可通过监听窗口的"pullToRefresh"事件处理下拉刷新业务逻辑,更新操作完成后调用窗口的endPullToRefresh方法结束下拉刷新。
- render: (String
类型
)窗口渲染模式
支持以下属性值: "onscreen" - Webview窗口在屏幕区可见时渲染,不可见时不进行渲染,此时能减少内存使用量; "always" - Webview在任何时候都渲染,在内存较大的设备上使用,被遮挡的窗口在此中模式下显示的时候会有更流畅的效果。 默认值为"onscreen"。 仅Android平台支持。
- right: (String
类型
)窗口水平向左的偏移量
支持百分比、像素值,默认无值(根据left和width属性值来自动计算)。 当设置了left和width值时,忽略此属性值; 当未设置width值时,可通过left和bottom属性值来确定窗口的宽度。
- scalable: (Boolean
类型
)窗口是否可缩放
窗口设置为可缩放(scalable:true)时,用户可通过双指操作放大或缩小页面,此时html页面可通过meta节点设置“name="viewport" content="user-scalable=no"”来限制页面不可缩放。 窗口设置为不可缩放(scalable:false)时,用户不可通过双指操作放大或缩小页面,即使页面中的meta节点也无法开启可缩放功能。 默认值为false,即不可缩放。
- scrollIndicator: (String
类型
)窗口是否显示滚动条
用于控制窗口滚动条样式,可取值: "all":垂直和水平滚动条都显示; "vertical":仅显示垂直滚动条; "horizontal":仅显示水平滚动条; "none":垂直和水平滚动条都不显示。 默认值为"all",即垂直和水平滚动条都显示。 注意:显示滚动条的前提条件是窗口中的内容超过窗口显示的宽或高。
- scrollsToTop: (Boolean
类型
)点击设备的状态栏时是否滚动返回至顶部
true表示点击设备的状态栏可以滚动返回至顶部,false表示点击设备的状态栏不可以,默认值为true。 此功能仅iOS平台支持,在iPhone上有且只有一个Webview窗口的scrollsToTop属性值为true时才生效,所以在显示和关闭Webview窗口时需动态更新所有Webview的scrollsToTop值,已确保此功能生效。
- shareable: (Boolean
类型
)是否可分享窗口加载的链接地址
在流应用环境(流应用/5+浏览器)中可通过分享按钮分享页面链接地址, 可取值: true - 可分享窗口加载页面链接地址; false - 不可分享窗口加载的页面链接地址,此时分享的是应用。 默认值值为true。
- softinputMode: (String
类型
)弹出系统软键盘模式
可选值: "adjustPan" - 弹出软键盘时Webview窗口自动上移,以保证当前输入框可见; "adjustResize" - 自动调整Webview窗口大小(屏幕区域减去软键盘区域),同时自动滚动Webview保证输入框可见; "nothing" - 不做任何调整(软键盘可能覆盖输入框)。 默认值为"adjustPan"。
- softinputNavBar: (String
类型
)软键盘上导航条的显示模式
可选值:"auto" - 表示系统默认值,即软键盘上显示导航条; "none" - 表示软键盘上不显示导航条。 默认值为"auto"。
- statusbar: (WebviewStatusbarStyles
类型
)窗口状态栏样式
仅在应用设置为沉浸式状态栏样式下有效,设置此属性后将自动保留系统状态栏区域不被Webview窗口占用(即Webview窗口非沉浸式样式显示)。
- subNViews: (Array[
WebviewSubNViewStyles
]
类型
)定义窗口的原生子View控件
数组类型,可通过配置项设置原生子View控件,每个配置项对应添加一个原生子View控件。 通过Webview窗口的getSubNViews()方法可获取原生子View控件对象数组。
- titleNView: (WebviewTitleNViewStyles
类型
)定义窗口的标题栏控件样式
设置此属性值则表明创建Webview窗口的标题栏控件,并可通过其属性值设置背景颜色、文本内容、文本颜色等。 通过Webview窗口的getTitleNView()方法可获取标题栏控件对象。
- top: (String
类型
)窗口垂直向下的偏移量
支持百分比、像素值,默认值为0px。 未设置top属性值时,优先通过bottom和height属性值来计算窗口的top位置。
- transition: (WebviewTransition
类型
)窗口定义窗口变换的动画效果
- transform: (WebviewTransform
类型
)窗口定义窗口变形效果
- position: (WebviewPosition
类型
)Webview窗口的排版位置
当Webview窗口添加到另外一个窗口中时,排版位置才会生效,排版位置决定子窗口在父窗口中的定位方式。 可取值:"static",控件在页面中正常定位,如果页面存在滚动条则随窗口内容滚动;"absolute",控件在页面中绝对定位,如果页面存在滚动条不随窗口内容滚动;"dock",控件在页面中停靠,停靠的位置由dock属性值决定。 默认值为"absolute"。
- userSelect: (Boolean
类型
)用户是否可选择内容
可取值: true - 表示可选择内容,用户可通过长按来选择页面内容,如文本内容选择后可以弹出系统复制粘贴菜单; false - 表示不可选择内容,用户不可通过长按来选择页面内容。 默认值为true。 注意:在Web页面中可通过CSS的user-select对单个页面元素进行控制,前提是Webview对象的userSelect设置为true,否则CSS设置的user-select失效。
- videoFullscreen: (String
类型
)视频全屏播放时的显示方向
可取值: "auto": 自动适配,如果当前页面竖屏显示,则视频全屏时竖屏显示;如果当前页面横屏显示,则视频全屏时横屏显示;如果当前页面自动感应,则视频全屏时自动感应横竖屏切换。 "portrait-primary": 竖屏正方向; "portrait-secondary": 竖屏反方向,屏幕正方向按顺时针旋转180°; "landscape-primary": 横屏正方向,屏幕正方向按顺时针旋转90°; "landscape-secondary": 横屏方向,屏幕正方向按顺时针旋转270°; "landscape": 横屏正方向或反方向,根据设备重力感应器自动调整; 默认值为“auto”。
- width: (String
类型
)窗口的宽度
支持百分比、像素值,默认为100%。未设置width属性值时,可同时设置left和right属性值改变窗口的默认宽度。
- zindex: (Number
类型
)窗口的堆叠顺序值
拥有更高堆叠顺序的窗口总是会处于堆叠顺序较低的窗口的前面,拥有相同堆叠顺序的窗口后调用show方法则在前面。
WebviewTransform
一组用于定义页面或控件变形的属性
WebviewTransition
一组用于定义页面或控件转换效果的属性
属性:
- property: (String
类型
)产生变换效果的属性
默认值为"all",暂不支持其它值。
- duration: (String
类型
)变换持续的时间
默认值为0,即无动画效果。
- timingfunction: (String
类型
)窗口变换效果
可取值: "linear":匀速变化,匀速动画效果; "ease-in":匀加速变化,逐渐变快的动画效果; "ease-out":匀减速变化,逐渐变慢的动画效果; "ease-in-out":先加速后减速变化,先变快后变慢的动画效果。 默认值为"ease-in-out"。
WebviewOverrideResourceOptions
拦截Webview窗口资源请求的参数
属性:
- match: (String
类型
)区配需要拦截请求资源的URL地址
支持正则表达式,默认值为空字符串(即不拦截)。
- redirect: (String
类型
)拦截重定向的资源地址
仅支持本地资源地址,如"_www"、"_doc"、"_downloads"、"_documents"等开头的路径。
- mime: (String
类型
)重定向的资源数据类型
RFC2045/RFC2046/RFC2047/RFC2048/RFC2049规范中定义的数据类型。 如普通文本(text/plain)、PNG图像(image/png)、GIF图形(image/gif)、JPEG图形(image/jpeg)。 如果未指定mime类型,则根据重定向资源路径自动区配。
- encoding: (String
类型
)重定向的资源数据编码
如未设置,则使用默认值"UTF-8"。
- header: (JSON
类型
)设置重定向资源数据的http头数据
可设置标注http头数据(如Content-type),也可设置自定义数据。 通常可通过此属性来设置拦截资源的缓存策略(如Cache-control)。
WebviewOverrideUrlOptions
拦截Webview窗口URL请求的属性
属性:
- effect: (String
类型
)拦截URL请求生效时机
可取值: "instant" - 表示立即生效,即调用overrideUrlLoading方法后立即生效; "touchstart" - 表示用户操作Webview窗口(触发touchstart事件)后生效,如果用户没有操作Webview窗口则不对URL请求操作进行拦截处理。 默认值为"instant"。
- mode: (String
类型
)拦截模式
可取值: "allow"表示满足match属性定义的条件时不拦截url继续加载,不满足match属性定义的条件时拦截url跳转并触发callback回调; "reject"表示满足match属性定义的提交时拦截url跳转并触发callback回调,不满足match属性定义的条件时不拦截url继续加载。 默认值为"reject"。
- match: (String
类型
)区配是否需要处理的URL请求
支持正则表达式,默认值为对所有URL地址生效(相当于正则表达式“.*”)。 如果mode值为"allow"则允许区配的URL请求跳转,mode值为"reject"则拦截区配的URL请求。
- exclude: (String
类型
)排除拦截处理请求类型
不拦截处理指定类型的URL请求,直接使用系统默认处理逻辑。 可取值: "none"表示不排除任何URL请求(即拦截处理所有URL请求); "redirect"表示排除拦截处理301/302跳转的请求(谨慎使用,非a标签的href触发的URL请求可能会误判断为302跳转)。 默认值为"none"。
WebviewListenResourceOptions
监听Webview窗口资源加载的属性
属性:
- match: (String
类型
)区配是否需要处理的URL资源
支持正则表达式,默认值为对所有URL资源请求生效(相当于正则表达式“.*”)。 如果Webview加载的资源区配条件,则触发回调事件。
BounceEventCallback
Webview窗口回弹事件的回调函数
void onEvent( Event event ){ // Event handled code. }
参数:
- event:
(
Event
)
必选 Webview窗口回弹事件触发时事件数据
Event对象包含以下属性: status - 表示回弹位置状态,设置顶部下拉回弹changeoffset属性后可取值:"beforeChangeOffset"表示可继续拖拽,此时松开拖拽窗口会回弹到其初始位置; "afterChangeOffset"表示回弹可停靠,此时松开拖拽窗口会回弹到停靠位置; "dragEndAfterChangeOffset"表示已进松开拖拽,并且窗口回弹到停靠位置。 设置左右侧侧滑slideoffset属性后可取值:"beforeSlide"表示未侧滑状态;"afterSlide"表示已侧滑状态。 offset - 表示回弹方向,可取值:"left"表示左侧滑动,"right"表示右侧滑动,"top"表示上侧下拉滑动。 target - 保存触发回弹此事件的Webview窗口对象。
返回值:
void : 无EventCallback
Webview窗口事件的回调函数
void onEvent(Event event){ // Event handled code. }
参数:
- event:
(
Event
)
必选 Webview窗口事件触发时事件数据
Event对象包含以下属性: target:保存触发此事件的Webview窗口对象; progress:保存窗口页面加载进度,仅"progressChanged"事件时有此属性。
返回值:
void : 无PopGestureCallback
Webview窗口侧滑事件的回调函数
void onEvent( PopGestureEvent event ){ // Event handled code. }
参数:
- event:
(
PopGestureEvent
)
必选 Webview窗口事件触发时事件数据
PopGestureEvent对象包含以下属性: target:保存侧滑操作的Webview窗口对象。 type:保存侧滑事件类型,"start"表示开始侧滑返回,用户按下滑动时触发; “end”表示结束侧滑返回,用户松手时触发; “move"表示侧滑返回动作结束,用户移动侧滑时触发。 result:保存操作结果,仅在e.type为end时有效,boolean类型, true表示侧滑返回执行,false表示侧滑返回取消;否则为undefined。 progress:保存侧滑位置,Number类型,可带小数点,范围为0-100。
返回值:
void : 无HistoryQueryCallback
历史记录查询的回调函数
void onHistoryQuery( Event event ) { // Event handled code. var canBack = event.canBack; var canForward = event.canForward; }
参数:
- event:
(
Event
)
必选 查询Webview窗口历史记录操作事件数据
可通过event的canBack属性获取Webview窗口是否可后退,通过event的canForward属性获取Webview窗口是否可前进。
返回值:
void : 无ListenResourceLoadingCallback
Webview窗口加载资源事件的回调函数
void onLoadingResource( Event event ) { // Event handled code. var url = event.url; }
参数:
- event:
(
Event
)
必选 Webview窗口加载资源事件数据
可通过event的url属性获取要加载的资源URL地址。
返回值:
void : 无OverrideUrlLoadingCallback
Webview窗口拦截URL链接跳转的回调函数
void onOverride( Event event ) { // Event handled code. var url = event.url; }
参数:
- event:
(
Event
)
必选 Webview窗口拦截URL跳转事件数据
可通过event的url属性获取拦截的URL地址。
返回值:
void : 无TitleUpdateCallback
Webview窗口加载页面标题更新的回调函数
void onQuery( Event event ) { // Event handled code. }
参数:
- event:
(
Event
)
必选 Webview窗口加载页面标题更新事件数据
可通过event的title属性获取Webview窗口的标题。
返回值:
void : 无WebviewAnimationCallback
Webview窗口组合动画回调函数
void onAnimationFinished( Event event ) { // Event handled code. }
参数:
- event:
(
Event
)
必选 Webview窗口动画完成事件数据
可通过event的id属性获取对应Webview窗口的标识,如果操作的窗口未设置id,则返回空字符串; 可通过event的target属性获取对应Webview窗口对象。
返回值:
void : 无WebviewDragCallback
Webview窗口滑屏操作事件回调函数
void onDrag( Event event ) { // Event handled code. }
说明:
在窗口开始滑动、滑动过程、滑动结束时触发,其中滑动过程中会触发多次,滑动过程中触发次数由WebviewDragOptions对象的callbackStep决定。
参数:
- event:
(
WebviewDragEvent
)
必选 Webview窗口滑动操作事件数据
返回值:
void : 无WebviewCustomButtonCallback
Webview窗口标题栏上自定义按钮点击事件回调函数
void onClicked(Event event){ // Event handled code. }
说明:
用户点击自定义按钮时触发。
参数:
- event:
(
Event
)
必选 点击事件触发时的数据
Event对象包含以下属性: target:触发此事件的WebviewBackButtonStyles对象。
返回值:
void : 无SuccessCallback
Webview窗口操作成功回调函数
void onSuccess(){ // Success code. }
说明:
Webview窗口业务操作成功后触发回调函数。
参数:
无
返回值:
void : 无ErrorCallback
Webview窗口操作失败回调函数
void onError(error){ // Handle the error var code = error.code; // 错误编码 var message = error.message; // 错误描述信息 }
参数:
- error:
(
Exception
)
可选 Webview窗口操作错误信息
可通过error.code(Number类型)获取错误编码; 可通过error.message(String类型)获取错误描述信息。