# nativeUI

nativeUI管理系统原生界面，可用于弹出系统原生提示对话框窗口、时间日期选择对话框、等待对话框等。

## 方法：

- actionSheet: 弹出系统选择按钮框
- alert: 弹出系统提示对话框
- confirm: 弹出系统确认对话框
- closeWaiting: 关闭系统等待对话框
- closeToast: 关闭自动消失的提示消息
- previewImage: 预览图片
- showWaiting: 显示系统等待对话框
- pickDate: 弹出系统日期选择对话框
- pickTime: 弹出系统时间选择对话框
- prompt: 弹出系统输入对话框
- toast: 显示自动消失的提示消息

## 对象：

- ActionButtonStyles: JSON对象，原生选择按钮框上按钮的样式参数
- ActionSheetStyles: JSON对象，原生选择按钮框的样式参数
- ConfirmStyles: 确认对话框的参数
- PreviewImageStyles: JSON对象，图片预览的参数
- PickDateStyles: 日期选择对话框的参数
- PickTimeStyles: JSON对象，时间选择对话框的参数
- NativeUIObj: 系统原生界面基类对象
- WaitingObj: 系统等待对话框对象
- WaitingStyles: JSON对象，原生等待对话框的参数
- WaitingLoadingStyles: JSON对象，原生等待对话框上loading图标自定义样式
- ToastStyles: JSON对象，系统提示消息框要设置的参数

## 回调方法：

- ActionSheetCallback: 系统选择按钮框的回调函数
- AlertCallback: 系统提示框确认的回调函数
- ConfirmCallback: 关闭确认对话框的回调函数
- PromptCallback: 系统输入对话框关闭后的回调函数
- PickDatetimeSuccessCallback: 选择日期或时间操作成功的回调函数
- PickDatetimeErrorCallback: 选择日期或时间操作取消或失败的回调函数
- PreviewImageLongPressCallback: 图片预览长按事件

## 权限：

5+功能模块（permissions）

    {
    // ...
    "permissions":{
    	// ...
    	"NativeUI": {
    		"description": "原生UI控件"
    	}
    }
    }

# ActionButtonStyles

JSON对象，原生选择按钮框上按钮的样式参数

## 属性：

- 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)"，表示红色半透明。

- title: (String 类型 )按钮上显示的文字内容
- style: (String 类型 )按钮的样式

  可取值： "destructive" - 表示警示按钮样式，默认文字颜色为红色； "default" - 表示默认按钮样式。 默认值为"default"。

# ActionSheetStyles

JSON对象，原生选择按钮框的样式参数

## 属性：

- title: (String 类型 )选择按钮框的标题
- cancel: (String 类型 )取消按钮上显示的文字内容

  不设置此属性，则不显示取消按钮。

- buttons: (Array[ ActionButtonStyles ] 类型 )选择框上的按钮，ActionButtonStyles对象数组

# ConfirmStyles

确认对话框的参数

## 属性：

- title: (String 类型 )确认对话框显示的标题

  如果不设置此属性值，则不显示标题。

- buttons: (Array[ String ] 类型 )确认对话框上显示的按钮

  字符串数组，每项对应在确认对话框上显示一个按钮，用户点击后通过confirmCB返回用户点击按钮的在数组中的索引值。

- verticalAlign: (String 类型 )对话框在屏幕中的垂直分享对齐方式

  可取值： "top" - 表示垂直居顶对齐； "center" - 表示垂直居中对齐； "bottom" - 表示垂直居底对齐。 默认值为"center"（垂直居中对齐）。

# PreviewImageStyles

JSON对象，图片预览的参数

## 属性：

- background: (String 类型 )图片预览的背景颜色

  颜色值格式为"#RRGGBB"，如"#FF0000"表示为红色背景。 默认值为黑色（"#000000"）。

- current: (Number 类型 )默认显示图片的索引值

  索引值从0开始，默认值为0。

- indicator: (String 类型 )图片指示器样式

  可取值： "default" - 默认指示器（底部圆点样式）； "number" - 顶部数字指示器（顶部居中显示，文字为%当前图片索引值（从1开始）%/%图片总数%）； "none" - 不显示指示器。 默认值为"default"。

- loop: (Boolean 类型 )是否可循环预览

  可取值： "true" - 支持循环预览； "false" - 不支持循环预览。 默认值为"false"。

- onLongPress: (PreviewImageLongPressCallback 类型 )长按事件

  用户在图片预览界面长按时触发。 在回调中返回长按图片的信息（索引值、地址等）。 由于图片预览界面是层级非常高的窗口，此时只能调用plus.nativeUI.*显示的窗口覆盖在图片预览界面上（原生控件plus.nativeObj.View也无法显示）。 注意：HBuilderX1.9.5及以上版本支持。

# PickDateStyles

日期选择对话框的参数

## 属性：

- title: (String 类型 )日期选择对话框显示的标题

  如果未设置，则不显示标题。

- date: (Date 类型 )日期选择对话框默认显示的日期

  如果未设置，则显示当前的日期。

- minDate: (Date 类型 )日期选择对话框可选择的最小日期

  Date类型对象，如果未设置可选择的最小日期，则使用系统默认可选择的最小日期值。

- maxDate: (Date 类型 )日期选择对话框可选择的最大日期

  Date类型对象，如果未设置可选择的最大日期，则使用系统默认可选择的最大日期值。 其值必须大于minDate设置的值，否则使用系统默认可选择的最大日期值。

- popover: (JSON 类型 )时间选择对话框弹出指示区域

  JSON类型对象，格式如{top:10;left:10;width:200;height:200;}，所有值为像素值，其值为相对于容器Webview的位置。 如未设置此值，默认在屏幕居中显示。仅在iPad上有效，其它设备忽略此值。

# PickTimeStyles

JSON对象，时间选择对话框的参数

## 属性：

- time: (Date 类型 )时间选择对话框默认显示的时间

  如果未设置，则默认当前的时间。

- title: (String 类型 )时间选择对话框显示的标题

  如果未设置，则不显示标题。

- is24Hour: (Boolean 类型 )是否24小时制模式

  true表示使用24小时制模式显示，fale表示使用12小时制模式显示，默认值为true。

- popover: (JSON 类型 )日期选择对话框弹出指示区域

  JSON类型对象，格式如{top:10;left:10;width:200;height:200;}，所有值为像素值，其值相对于容器webview的位置。 如未设置此值，默认在屏幕居中显示。仅在iPad上有效，其它设备忽略此值。

# NativeUIObj

系统原生界面基类对象

    interface NativeUIObj{
    	function void close();
    }

## 方法：

- close: 关闭显示的系统原生界面

# WaitingObj

系统等待对话框对象

## 说明：

从NativeUIObj对象继承而来，通过plus.nativeUI.showWaiting方法创建时返回。 用于控制系统样式等待对话框的操作，如关闭、设置标题内容等。

## 方法：

- setTitle: 设置等待对话框上显示的文字内容
- close: 关闭显示的系统等待对话框

## 事件：

- onclose: 等待对话框关闭事件

# WaitingStyles

JSON对象，原生等待对话框的参数

## 属性：

- width: (String 类型 )等待框背景区域的宽度

  值支持像素值（"500px"）或百分比（"50%"），百分比相对于屏幕的宽计算，如果不设置则根据内容自动计算合适的宽度。

- height: (String 类型 )等待框背景区域的高度

  值支持像素绝对值（"500px"）或百分比（"50%"），如果不设置则根据内容自动计算合适的高度。

- color: (String 类型 )等待框中文字的颜色

  颜色值支持(参考CSS颜色规范)：颜色名称(参考CSS Color Names)/十六进制值/rgb值/rgba值，默认值为白色。

- size: (String 类型 )等待框中文字的字体大小

  如"14px"表示使用14像素高的文字，未设置则使用系统默认字体大小。

- textalign: (String 类型 )等待对话框中标题文字的水平对齐方式

  对齐方式可选值包括："left"：水平居左对齐显示，"center"：水平居中对齐显示，"right"：水平居右对齐显示。默认值为水平居中对齐显示，即"center"。

- padding: (String 类型 )等待对话框的内边距

  值支持像素值（"10px"）和百分比（"5%"），百分比相对于屏幕的宽计算，默认值为"3%"。

- background: (String 类型 )等待对话框显示区域的背景色

  背景色的值支持(参考CSS颜色规范)：颜色名称(参考CSS Color Names)/十六进制值/rgb值/rgba值，默认值为rgba(0,0,0,0.7)。

- style: (String 类型 )等待对话框样式

  可取值"black"、"white"，black表示等待框为黑色雪花样式，通常在背景主色为浅色时使用；white表示等待框为白色雪花样式，通常在背景主色为深色时使用。 仅在iOS平台有效，其它平台忽略此值，未设置时默认值为white。

- modal: (Boolen 类型 )等待框是否模态显示

  模态显示时用户不可操作直到等待对话框关闭，否则用户在等待对话框显示时也可操作下面的内容，未设置时默认为true。

- round: (Number 类型 )等待框显示区域的圆角

  值支持像素值（"10px"），未设置时使用默认值"10px"。

- padlock: (Boolen 类型 )点击等待显示区域是否自动关闭

  true表示点击等待对话框显示区域时自动关闭，false则不关闭，未设置时默认值为false。

- back: (String 类型 )返回键处理方式

  可取值"none"表示截获处理返回键，但不做任何响应；"close"表示截获处理返回键并关闭等待框；"transmit"表示不截获返回键，向后传递给Webview窗口继续处理（与未显示等待框的情况一致）。

- loading: (WaitingLoadingStyles 类型 )自定义等待框上loading图标样式

# WaitingLoadingStyles

JSON对象，原生等待对话框上loading图标自定义样式

## 属性：

- display: (String 类型 )loading图标显示样式

  可取值： "block"表示图标与文字分开两行显示，上面显示loading图标，下面显示文字； "inline"表示loading图标与文字在同一行显示，左边显示loading图标，右边显示文字； "none"表示不显示loading图标；

- height: (String 类型 )loading图标高度

  设置loading图标的高度（宽度等比率缩放），取值类型：像素值，如"14px"表示14像素高。

- icon: (String 类型 )loading图标路径

  自定义loading图标的路径，png格式，并且必须是本地资源地址； loading图要求宽是高的整数倍，显示等待框时按照图片的高横向截取每帧刷新。

- interval: (Number 类型 )loading图每帧刷新间隔

  单位为ms（毫秒），默认值为100ms。

- type: (String 类型 )loading图标类型

  如果设置了icon属性，则优先使用icon自定义图标。 可取值： "circle" - 圆圈类型loading图标； "snow" - 雪花类型loading图标。 默认值为"circle"。

# ToastStyles

JSON对象，系统提示消息框要设置的参数

## 属性：

- align: (String 类型 )提示消息框在屏幕中的水平位置

  可选值为"left"、"center"、"right"，分别为水平居左、居中、居右，未设置时默认值为"center"。

- background: (String 类型 )提示消息框的背景色

  背景色的值支持(参考CSS颜色规范)：颜色名称(参考CSS Color Names)/十六进制值/rgb值/rgba值。

- duration: (String 类型 )提示消息框显示的时间

  可选值为"long"、"short"，值为"long"时显示时间约为3.5s，值为"short"时显示时间约为2s，未设置时默认值为"short"。

- icon: (String 类型 )提示消息框上显示的图标

  仅支持本地图片路径。

- iconWidth: (String 类型 )图标的宽度

  单位为px（逻辑像素值），默认值为图片的宽度。

- iconHeight: (String 类型 )图标的高度

  单位为px（逻辑像素值），默认值为图片的高度。

- style: (String 类型 )提示消息框上显示的样式

  可取值： "block"表示图标与文字分两行显示，上面显示图标，下面显示文字； "inline"表示图标与文字在同一行显示，左边显示图标，右边显示文字。 默认值为"block"。

- type: (String 类型 )提示消息框上显示的文本类型

  可取值： "text" - 显示的消息内容为文本字符串； "richtext" - 显示的消息内容为富文本内容。 默认值为"text"。 当type为"text"时，富文本使用html的部分标签，具体标签如下： 图片标签<img src="图片资源url地址" width="图片显示的宽度" height="图片显示的高度" onclick="console.log('clicked img')"></img>； 字体标签<font color="字体颜色"></font>，内容在一行显示不下时自动换行，行高默认为字体的1.2倍； 换行标签<br/>； 链接标签<a onclick="console.log('clicked a')">链接地址</a>。 如示例“<img onclick="console.log('clicked img')" src="http://img-cdn-qiniu.dcloud.net.cn/icon2.png"/><a onclick="console.log(clicked a)">链接地址</a>”。

- richTextStyle: (RichTextStyles 类型 )富文本样式

  当type属性值为"richtext"时有效，用于定义富文本的样式，如其文本对齐方式、使用的字体等。

- verticalAlign: (String 类型 )提示消息在屏幕中的垂直位置

  可选值为"top"、"center"、"bottom"，分别为垂直居顶、居中、居底，未设置时默认值为"bottom"。

# ActionSheetCallback

系统选择按钮框的回调函数

    void onActioned( Event event ){
    	// actionsheet handled code.
    	var index=event.index; // 用户关闭时点击按钮的索引值
    }

## 参数：

- event: ( Event ) 必选 用户操作选择按钮框关闭后返回的数据
  可通过event.index（Number类型）获取用户关闭时点击按钮的索引值，索引值从0开始； 0表示用户点击取消按钮，大于0值表示用户点击ActionSheetStyles中buttons属性定义的按钮，索引值从1开始（即1表示点击buttons中定义的第一个按钮）。 通过API（close()方法）关闭，则回调函数中event的index属性值为-1。

## 返回值：

void : 无

# AlertCallback

系统提示框确认的回调函数

    void onAlerted( Event event ){
    	// Alert handled code.
    	var index=event.index; // 用户关闭提示对话框点击按钮的索引值
    }

## 参数：

- event: ( Event ) 必选 用户操作确认对话框关闭后返回的数据
  可通过event.index（Number类型）获取用户关闭确认对话框点击按钮的索引值，点击确认键的索引值为0。 Android平台上通过返回按钮关闭时索引值为-1。

## 返回值：

void : 无

# ConfirmCallback

关闭确认对话框的回调函数

    void onConfirmed( Event event ) {
    	// Confirm handled code.
    	var index=event.index; // 用户关闭确认对话框点击按钮的索引值
    }

## 参数：

- event: ( Event ) 必选 用户操作确认对话框关闭后返回的数据
  可通过event.index（Number类型）获取用户关闭确认对话框点击按钮的索引值，索引值从0开始；

## 返回值：

void : 无

# PromptCallback

系统输入对话框关闭后的回调函数

    function void onPrompted( Event event ) {
    	// Prompt handled code.
    	var index=event.index; // 用户关闭输入对话框点击按钮的索引值
    	var value=event.value; // 用户输入的内容
    }

## 参数：

- event: ( Event ) 必选 用户操作输入对话框关闭后返回的数据
  可通过event.index（Number类型）获取用户关闭输入对话框点击按钮的索引值，索引值从0开始； 通过event.value（String类型）获取用户输入的内容，如果没有输入则返回空字符串。

## 返回值：

void : 无

# PickDatetimeSuccessCallback

选择日期或时间操作成功的回调函数

    function void onPickSuccess( Event event ) {
    	// Date picked code.
    	var date = event.date;// 用户选择的日期或时间
    }

## 参数：

- event: ( Event ) 必选 用户完成选择日期或时间后返回的数据
  可通过event.date（Date类型）获取选择的日期或时间值。 若调用的是日期选择操作则仅年、月、日信息有效，若调用的是时间选择操作则仅时、分信息有效。

## 返回值：

void : 无

# PickDatetimeErrorCallback

选择日期或时间操作取消或失败的回调函数

    function void onPickError( Exception error ) {
    	// Date picked error.
    	var code = error.code; // 错误编码
    	var message = error.message; // 错误描述信息
    }

## 参数：

- error: ( Exception ) 必选 用户选择操作失败信息
  可通过error.code（Number类型）获取错误编码； 可通过error.message（String类型）获取错误描述信息。

## 返回值：

void : 无

# PreviewImageLongPressCallback

图片预览长按事件

    function void onlongPress(event) {
    	// longpress event
    	var index = event.index; 			// 长按图片的索引
    	var url = event.url;					// 长按图片的url地址
    	var path = event.path;				// 长按图片的本地图片路径（系统绝对路径）
    }

## 说明：

在图片预览界面长按时触发。

## 参数：

- index: ( Number ) 必选 长按图片的索引值
  索引值从0开始。
- url: ( String ) 必选 长按图片的url地址
  与调用plus.nativeUI.previewImage传入的urls值一致。
- path: ( String ) 必选 长按图片的本地地址
  系统绝对路径。

## 返回值：

void : 无