[关闭]
@xxtouch 2017-11-15T16:03:48.000000Z 字数 10710 阅读 2159

XXTouch UI (XUI) 界面库使用手册

XXTouch XXTouchApp XUI


此文档是为测试版编写的, 暂不适用于线上正式版本.

在阅读本文前, 您需要对 Lua 语法有所了解, 并能理解 数值/布尔型/字符串/数组/字典 等基本数据类型.


目录


前言

XUI 用于在 XXTouch 上提供配置界面, 采用 iOS 系统原生组件. 本手册提供了 XUI 界面布局的规范. XUI 是 XPP 脚本包的一部分, 用来为脚本包创建配置, 不能独立使用, 无法在脚本运行的时候启动 XUI 界面.

如需使用 XUI, 您需要创建指定格式的 xui / json / plist 文件, 在脚本包中激活. 保存的配置项, 可以通过 plist 库进行读取.


示例

A-Script-Bundle.xpp.zip1006.2kB

1510761795.png-1.9kB

脚本开发者可以下载示例包, 在 XXTouch 中解压并运行.

IMG_0716.JPG-152.2kB


创建

xui 是一种特定格式的 lua 文件, 使用这种格式创建 XUI 界面, 需要使 lua 执行后返回一个包含各组件及属性的表.

您也可以使用 json 或 plist 格式, 来创建 XUI 界面.


XUI 配置的根(顶层)为字典.

类型 描述 条件
title 字符串 导航栏标题 可选, 可本地化
header 字符串 主标题 可选, 可本地化
subheader 字符串 副标题 可选, 可本地化
items 包含字典的数组 组件列表 -
theme 字典 界面主题样式 可选

items 是组件列表数组, 所有的 组件字典 按顺序存放在该数组中, 即可在界面上显示. 关于 组件字典 的说明, 参见本文后续内容.

  1. return {
  2. subheader = "Elegant App UI provided by XXTouchApp.";
  3. header = "Example";
  4. title = "Demo";
  5. theme = {
  6. "tintColor" = "#FFFFFF";
  7. };
  8. items = {};
  9. };

主题样式

在根层级设置 theme 属性, 能为界面配置统一的样式.

组件

类型 描述
tintColor 颜色 前景颜色
backgroundColor 颜色 背景颜色
disclosureIndicatorColor 颜色 指示器颜色
selectedColor 颜色 选中颜色
highlightedColor 颜色 高亮颜色
labelColor 颜色 标题文字颜色
valueColor 颜色 值文字颜色

导航栏

类型 描述
navigationBarColor 颜色 导航栏背景颜色
navigationTitleColor 颜色 导航栏标题颜色

状态

类型 描述
dangerColor 颜色 错误颜色
warningColor 颜色 警告颜色
successColor 颜色 成功颜色

在组件层级设置 theme 属性, 每个组件单独设置样式, 参见每个组件的 主题键 表格.

类型 颜色, 即十六进制 RGB (RGBA) 字符串形式, 如 #FF0000 代表红色.

CFE17DA4-C299-4533-A0E9-E1E2F9734C8D.png-32.9kB


通用属性

各组件均可使用如下通用属性, 为组件添加标题, 图标, 指定配置保存位置等.

类型 描述 条件
cell 字符串 组件类型 -
label 字符串 显示标签 可选, 可本地化
defaults 字符串 配置标识符 -
key 字符串 配置键名 defaults != nil
default 字符串 配置默认值 -
value 基本类型 配置值 可选
icon 字符串 图标文件名 可选
readonly 布尔型 组件是否只读 可选
height 数值 组件的高度 可选

cell 为组件类型, 不同类型代表不同组件.

label 为组件标题, 显示在组件左侧.

default 为组件默认值, 若 value 为 nil, 则使用 default 的值填充 value.

icon 为图标, 显示在 label 左侧. 若设置为 "res/16.png", 建议同时准备 "res/16@2x.png" 和 "res/16@3x.png", 实际尺寸须分别为原来的 2 倍和 3 倍.

readonly 如果为 true, 则组件的值只读, 不能被修改和置空. 也不能链接到子界面.


读取配置

配置完成后, 在 defaults 指定的保存位置, 读取 plist 中键 key == "switch1" 的值, 即为开关 "switch1" 的状态.

  1. function read_xui_conf(bid)
  2. local plist = require("plist")
  3. return plist.read("/var/mobile/Media/1ferver/uicfg/"..bid..".plist") or {}
  4. end
  5. local conf = read_xui_conf('com.yourcompany.A-Script-Bundle')
  6. sys.alert(json.encode(conf))
  7. local enabled = conf.enabled

Group 分组

此组件在界面上显示一个分组区域 Section, 包含到下一个相同组件类型之间的所有组件.

类型 描述 条件
footerText 字符串 在当前组之后添加一行小字 可选, 可本地化

此组件不支持 label/icon/height

  1. {
  2. items = {
  3. {
  4. cell = "Group";
  5. label = "Switch";
  6. };
  7. {
  8. defaults = "com.yourcompany.yourscript";
  9. default = true;
  10. label = "Enabled";
  11. cell = "Switch";
  12. key = "switch1";
  13. icon = "res/16.png";
  14. };
  15. {
  16. cell = "Group";
  17. label = "Button";
  18. };
  19. {
  20. url = "https://www.xxtouch.com";
  21. cell = "Link";
  22. label = "Open XXTouch.com";
  23. };
  24. {
  25. cell = "Button";
  26. action = "OpenURL:";
  27. label = "Contact i.82@me.com";
  28. args = {
  29. url = "mailto://i.82@me.com";
  30. };
  31. };
  32. };
  33. };

QQ20170914-191445.png-44.5kB


此组件在界面上显示一个子菜单项, 用于链接子界面.

类型 描述 条件
url 字符串 子界面文件名 -

url 可以为普通文件名、XUI 文件名或网络地址. 普通文件将使用默认打开方式打开, XUI 文件将作为子界面打开, 网络地址将使用内置浏览器打开.

  1. {
  2. url = "sub/xui-sub.xui";
  3. cell = "Link";
  4. label = "Load another pane";
  5. };

QQ20170914-191746.png-51.9kB


Switch 开关

此组件在界面上显示一个开关.

类型 描述 条件
negate 布尔型 反转开关显示情况 可选
trueValue 基本类型 当结果为 true 时保存的值
若不填则保存 true
可选
falseValue 基本类型 当结果为 false 时保存的值
若不填则保存 false
可选
主题键 描述
tintColor 开关底色
返回类型 描述
基本类型 与开关状态一致, 但若 negate 为真, 配置值为开关状态取反.
若存在, 配置值会被 trueValuefalseValue 代替.
  1. {
  2. defaults = "com.yourcompany.yourscript";
  3. default = true;
  4. label = "Enabled";
  5. cell = "Switch";
  6. key = "switch1";
  7. icon = "res/16.png";
  8. };

CFC04C38-FFBE-46B9-BE86-AE8470342DAD.png-19.2kB


Button 动作按钮

此组件在界面上显示一个按钮, 用于执行某些动作.

类型 描述 条件
alignment 字符串 对齐方式 -
action 选择器 指定按钮的操作类型 -
args 字典 传递给选择器的参数 -
alignment 描述
Left 左对齐
Center 居中
Right 右对齐
Natural 自然对齐
Justified 两边对齐
action 描述
LaunchScript: 运行服务脚本
OpenURL: 在第三方应用中打开URL
ScanQRCode: 调起相机, 扫描二维码
SendMail: 在应用中, 发送邮件

不同的 action 需要携带不同的参数字典 args, 现对参数字典 args 中包含的参数说明如下:

LaunchScript:

参数 类型 描述 条件
path 字符串 服务脚本路径 -

无返回值

OpenURL:

参数 类型 描述 条件
url 字符串 欲打开的URL -

无返回值

ScanQRCode:

无参数

返回值类型 描述
字符串 二维码扫描结果

SendMail:

参数 类型 描述 条件
subject 字符串 邮件主题 可选
toRecipients 包含字符串的数组 收件邮箱地址数组 可选
ccRecipients 包含字符串的数组 抄送邮箱地址数组 可选
bccRecipients 包含字符串的数组 密送邮箱地址数组 可选
attachments 包含字符串的数组 携带附件的路径数组 可选

无返回值

  1. {
  2. cell = "Button";
  3. action = "OpenURL:";
  4. label = "Contact i.82@me.com";
  5. args = {
  6. url = "mailto://i.82@me.com";
  7. };
  8. };

QQ20170914-191854.png-23kB


TextField 单行文本框

此组件在界面上显示一个文本框, 用于字符串输入.

类型 描述 条件
alignment 字符串 对齐方式 可选
keyboard 字符串 键盘类型 可选
placeholder 字符串 文本框占位符 可选
isSecure 布尔型 字符是否显示为小圆点 可选

此组件不支持 icon

alignment 描述
Left 左对齐
Center 居中
Right 右对齐
Natural 自然对齐
Justified 两边对齐
keyboard 描述
Default 默认
Alphabet 标准 ASCII
ASCIICapable 标准 ASCII
NumbersAndPunctuation 数字与标点
URL 网址
NumberPad 数字
PhonePad 电话号码
NamePhonePad 姓名与电话号码
EmailAddress 电子邮箱
DecimalPad 带小数点的数字
返回类型 描述
字符串 文本框内容
  1. {
  2. defaults = "com.yourcompany.yourscript";
  3. default = "";
  4. cell = "TextField";
  5. key = "username";
  6. keyboard = "Alphabet";
  7. placeholder = "Enter the username";
  8. };
  9. {
  10. defaults = "com.yourcompany.yourscript";
  11. default = "";
  12. cell = "SecureTextField";
  13. key = "password";
  14. keyboard = "Alphabet";
  15. placeholder = "Enter the password";
  16. };

QQ20170914-192018.png-30kB


Radio / Checkbox 单选框 / 复选框组

此组件在界面上显示若干单选框 / 复选框.

点选单选框会选中当前选择的单选框, 取消同组其它单选框的选中状态.
点选复选框会切换其选中 / 未选状态.

类型 描述 条件
alignment 字符串 对齐方式 可选
options 包含字典的数组 选项列表数组 -
minCount 整数 最少选择项目数 复选框有效
maxCount 整数 最多选择项目数 复选框有效
alignment 描述
Left 左对齐
Center 居中
Right 右对齐
Natural 扩展空白部分使两边对齐
Justified 扩展标签宽度使两边对齐

options 包含若干 选项, 选项 为字典, 有如下属性:

类型 描述 条件
title 字符串 选项标题 可本地化
value 基本类型 选项配置值
若不填, 则与 title 一致.
可选

此组件不支持 label/icon/height

主题键 描述
tagTextColor 标签文字颜色
tagSelectedTextColor 选中标签文字颜色
tagBackgroundColor 标签背景颜色
tagSelectedBackgroundColor 选中标签背景颜色
tagBorderColor 标签边框颜色
tagSelectedBorderColor 选中标签边框颜色
返回类型 描述
包含字符串的数组 包含所有选中项 value 的数组
  1. {
  2. defaults = "com.yourcompany.yourscript";
  3. default = {
  4. "Red";
  5. "Green";
  6. };
  7. cell = "Checkbox";
  8. key = "checkbox";
  9. maxCount = 4;
  10. options = {
  11. {
  12. title = "Red";
  13. };
  14. {
  15. title = "Green";
  16. };
  17. {
  18. title = "Blue";
  19. };
  20. {
  21. title = "Yellow";
  22. };
  23. {
  24. title = "Purple";
  25. };
  26. {
  27. title = "Black";
  28. };
  29. {
  30. title = "White";
  31. };
  32. };
  33. };
  34. {
  35. defaults = "com.yourcompany.yourscript";
  36. default = "Fifth; please!";
  37. cell = "Radio";
  38. key = "radio";
  39. options = {
  40. {
  41. title = "First";
  42. };
  43. {
  44. title = "Second";
  45. };
  46. {
  47. title = "Third";
  48. };
  49. {
  50. title = "Fourth";
  51. };
  52. {
  53. title = "Fifth; please!";
  54. };
  55. {
  56. title = "Zero";
  57. };
  58. };
  59. };

QQ20170916-182221@2x.png-185.2kB


Segment 适合少量选项的单项选择

此组件在界面上显示一个选项组. 用于选择单个选项 (总选项数一般少于 6 个).

类型 描述 条件
options 包含字典的数组 选项列表数组 -

options 包含若干 选项, 选项 为字典, 有如下属性:

类型 描述 条件
title 字符串 选项标题 可本地化
value 基本类型 选项配置值
若不填, 则与 title 一致.
可选

此组件不支持 label/icon

返回类型 描述
字符串 选中项的 value
  1. {
  2. defaults = "com.yourcompany.yourscript";
  3. default = "Green";
  4. label = "List of Options";
  5. cell = "Segment";
  6. key = "list-segment";
  7. options = {
  8. {
  9. title = "Red";
  10. };
  11. {
  12. title = "Green";
  13. };
  14. {
  15. title = "Blue";
  16. };
  17. };
  18. };

QQ20170914-192102.png-14.5kB


Option 单项选择列表

此组件在界面上显示一个子菜单项, 用于链接包含一些选项的子菜单.

类型 描述 条件
options 包含字典的数组 选项列表数组 -
footerText 字符串 显示在列表选项下方的小字 可选, 可本地化

options 包含若干 选项, 选项 为字典, 有如下属性:

类型 描述 条件
title 字符串 选项标题 可本地化
shortTitle 字符串 显示在父级菜单右侧的标题 可选, 可本地化
value 基本类型 选项配置值
若不填, 则与 title 一致.
可选
icon 字符串 选项图标文件名 可选
返回类型 描述
字符串 选中项的 value
  1. {
  2. defaults = "com.yourcompany.yourscript";
  3. default = {
  4. "Green; it's green!"
  5. };
  6. label = "List of Options";
  7. cell = "Option";
  8. key = "list-1";
  9. options = {
  10. {
  11. title = "Red; it's red!";
  12. shortTitle = "Red";
  13. };
  14. {
  15. title = "Green; it's green!";
  16. shortTitle = "Green";
  17. };
  18. {
  19. title = "Blue; great color!";
  20. shortTitle = "Blue";
  21. };
  22. };
  23. };

QQ20170916-182546@2x.png-23.3kB


MultipleOption 多项选择列表

此组件在界面上显示一个子菜单项, 用于链接包含一些选项的子菜单.

类型 描述 条件
options 包含字典的数组 选项列表数组 -
footerText 字符串 显示在列表选项下方的小字 可选, 可本地化
maxCount 整数 最多选择项目数 -

options 包含若干 选项, 选项 为字典, 有如下属性:

类型 描述 条件
title 字符串 选项标题 可本地化
value 基本类型 选项配置值
若不填, 则与 title 一致.
可选
icon 字符串 选项图标文件名 可选
返回类型 描述
包含字符串的数组 包含所有选中项 value 的数组
  1. {
  2. defaults = "com.yourcompany.yourscript";
  3. default = {
  4. "Red; it's red!"; "Green; it's green!"
  5. };
  6. label = "List of Multiple Options";
  7. cell = "MultipleOption";
  8. key = "list-2";
  9. maxCount = 2;
  10. options = {
  11. {
  12. title = "Red; it's red!";
  13. };
  14. {
  15. title = "Green; it's green!";
  16. };
  17. {
  18. title = "Blue; great color!";
  19. };
  20. };
  21. };

QQ20170916-182611@2x.png-25.2kB


OrderedOption 多项有序选择列表

此组件在界面上显示一个子菜单项, 用于链接包含一些选项的子菜单.

类型 描述 条件
options 包含字典的数组 选项列表数组 -
footerText 字符串 显示在列表选项下方的小字 可选, 可本地化
minCount 整数 最少选择项目数 -
maxCount 整数 最多选择项目数 -

options 包含若干 选项, 选项 为字典, 有如下属性:

类型 描述 条件
title 字符串 选项标题 可本地化
value 基本类型 选项配置值
若不填, 则与 title 一致.
可选
icon 字符串 选项图标文件名 可选
返回类型 描述
包含字符串的数组 包含所有选中项 value 的数组
  1. {
  2. defaults = "com.yourcompany.yourscript";
  3. default = {
  4. "Red";
  5. };
  6. label = "List of Ordered Options";
  7. cell = "OrderedOption";
  8. key = "list-3";
  9. maxCount = 2;
  10. minCount = 1;
  11. options = {
  12. {
  13. title = "Red";
  14. };
  15. {
  16. title = "Green";
  17. };
  18. {
  19. title = "Blue";
  20. };
  21. };
  22. };

QQ20170916-182729@2x.png-34kB


EditableList 可编辑列表

此组件在界面上显示一个子菜单项, 用于链接一个可编辑的字符串列表.

类型 描述 条件
footerText 字符串 显示在列表选项下方的小字 可选, 可本地化
maxCount 整数 最多选择项目数 -
返回类型 描述
包含字符串的数组 列表内容
  1. {
  2. maxCount = 10;
  3. defaults = "com.yourcompany.yourscript";
  4. cell = "EditableList";
  5. label = "Editable List";
  6. key = "list-4";
  7. default = {
  8. "Default";
  9. };
  10. };

QQ20171016-180741.png-157.3kB


Slider 数值拖拽滑块

此组件在界面上显示一个滑块, 用于数值的选择和调整.

类型 描述 条件
min 数值 滑块最小值 -
max 数值 滑块最大值 -
showValue 布尔型 是否显示当前滑块的值 可选

此组件不支持 label/icon

主题键 描述
tintColor 滑块进度底色
返回类型 描述
数值 组件数值
  1. {
  2. showValue = true;
  3. defaults = "com.yourcompany.yourscript";
  4. min = 1;
  5. default = 5;
  6. max = 10;
  7. label = "Slider";
  8. cell = "Slider";
  9. key = "slider";
  10. isSegmented = true;
  11. };

QQ20170914-192324.png-9.1kB


Stepper 数值调节按钮

此组件在界面上显示一个调节器, 用于数值的选择和调整.

类型 描述 条件
min 数值 调节最小值 -
max 数值 调节最大值 -
step 数值 调节歩长 -
isInteger 布尔型 值是否显示为整数 可选
autoRepeat 布尔型 长按是否连续调整 可选
返回类型 描述
数值 组件数值
  1. {
  2. defaults = "com.yourcompany.yourscript";
  3. min = 1;
  4. default = 5;
  5. max = 10;
  6. autoRepeat = true;
  7. label = "Stepper";
  8. cell = "Stepper";
  9. key = "stepper";
  10. isInteger = true;
  11. };

QQ20170914-192349.png-10.8kB


DateTime 时间日期选择器

此组件在界面上显示一个时间日期选择器, 用于日期、时间的选择及时间间隔的调整.

类型 描述 条件
min 数值 时间间隔最小值 可选
max 数值 时间间隔最大值 可选
minuteInterval 整数 时间间隔歩长, 单位分钟 可选
mode 字符串 选择器模式 可选

此组件不支持 label/icon

mode 描述
datetime 日期时间选择器
date 日期选择器
time 时间选择器
interval 时间间隔选择器
返回类型 描述
整数 组件所选时间的 Unix 时间戳, 或时间间隔的秒数
  1. {
  2. cell = "DateTime";
  3. key = "datetime1";
  4. defaults = "com.yourcompany.yourscript";
  5. };

QQ20170917-000929@2x.png-77.9kB


TitleValue 键值对显示; 代码片段选择器

此组件在界面上显示 key - value 对, 类似 设置 -> 通用 -> 关于中系统参数键值对的显示.

类型 描述 条件
value 基本类型 右侧显示值 可选
snippet 字符串 选择器脚本文件名 可选

此组件可以左划将已存的配置值置空, 但不能覆盖 XUI 中提供的 value.

如果为此组件设置了 defaultskey, 则此组件可用来显示配置项的实际值;同时设置 snippet 属性, 则能够为此组件增加 XUI 内选择器的功能, 激活选择器组, 并将返回结果存入此组件的配置项内.

  1. {
  2. default = true;
  3. cell = "Switch";
  4. key = "switch1";
  5. defaults = "com.yourcompany.yourscript";
  6. label = "Sosh!";
  7. };
  8. {
  9. cell = "TitleValue";
  10. label = "Version";
  11. value = "1.1.3";
  12. }; -- 显示固定值
  13. {
  14. cell = "TitleValue";
  15. label = "Dynamic";
  16. key = "switch1";
  17. defaults = "com.yourcompany.yourscript";
  18. }; -- 显示配置值
  19. {
  20. cell = "TitleValue";
  21. label = "Application";
  22. key = "applications";
  23. defaults = "com.yourcompany.yourscript";
  24. snippet = "snippets/app.snippet";
  25. }; -- 显示选择器组

QQ20170914-192446.png-36.5kB


StaticText 静态文本框

此组件在界面上显示一段静态文本, 即其 label 属性中的文本.

类型 描述 条件
alignment 字符串 对齐方式 可选
selectable 布尔型 是否允许选择文本 可选
alignment 描述
Left 左对齐
Center 居中
Right 右对齐
Natural 自然对齐
Justified 两边对齐

暂不支持更改文本字体、尺寸等属性

此组件不支持 label/icon/height

  1. {
  2. cell = "StaticText";
  3. label = "This specifier uses the label key as text content. Dynamic height of this cell is enabled.";
  4. };

QQ20170914-192523.png-30.6kB


Textarea 多行文本域

此组件在界面上显示一个子菜单项, 用于链接到一个多行文本输入界面.

类型 描述 条件
maxLength 整数 最大文本长度 可选
keyboard 字符串 键盘类型 可选
autoCapitalization 字符串 自动大写模式 可选
autoCorrection 字符串 自动更正模式 可选
keyboard 描述
Default 默认
Alphabet 标准 ASCII
ASCIICapable 标准 ASCII
NumbersAndPunctuation 数字与标点
URL 网址
NumberPad 数字
PhonePad 电话号码
NamePhonePad 姓名与电话号码
EmailAddress 电子邮箱
DecimalPad 带小数点的数字
autoCapitalization 描述
None
Sentences 按句自动大写
Words 按单词自动大写
AllCharacters 全部大写
autoCorrection 描述
Default 默认
No 关闭自动更正
Yes 打开自动更正

暂不支持更改文本字体、尺寸等属性

返回类型 描述
字符串 文本内容
  1. {
  2. default = "You can enter any text here...";
  3. cell = "Textarea";
  4. key = "textarea";
  5. defaults = "com.yourcompany.yourscript";
  6. label = "Textarea Cell";
  7. };

Image / AnimatedImage 图片 / 动态图片

此组件在界面上显示图片.

类型 描述 条件
path 字符串 本地图片名称 -

此组件必须设定通用属性 height, 以确定图片高度, 宽度将保持比例自动适应.

AnimatedImage 组件支持 GIF 动态图.

  1. {
  2. cell = "Image";
  3. path = "res/bd_logo1_31bdc765.png";
  4. height = 128.0;
  5. };

QQ20170918-022558.png-31kB


File 文件选择器

此组件在界面上显示文件选择区域, 可显示文件类型图标、文件名称与文件修改时间, 点击可选择新文件.

类型 描述 条件
initialPath 字符串 文件选择初始顶层目录 可选
allowedExtensions 包含字符串的数组 允许的文件扩展名列表 可选

此组件可以左划将已存的配置值置空.

initialPath 若不填, 则为当前脚本包路径. allowedExtensions 中包含允许选择的文件名列表, 不符合扩展名要求的项目将不会被显示.

返回类型 描述
字符串 所选文件完整路径
  1. {
  2. cell = "File";
  3. key = "file1";
  4. defaults = "com.yourcompany.yourscript";
  5. allowedExtensions = { "lua"; "xxt"; "xpp" };
  6. };

QQ20170918-022520.png-31.5kB


About 关于

此组件在界面上显示一个关于区域, 其样式与 XXTouch 关于界面样式一致.

类型 描述 条件
imagePath 字符串 关于图标 可选

此组件需要设定通用属性 labelvalue, 分别显示在关于标题位置与副标题位置.

  1. {
  2. cell = "About";
  3. label = "XXTouch\nv1.2.0-1";
  4. value = "https://www.xxtouch.com\n2016-2017 (c) XXTouch Team.\nAll Rights Reserved.";
  5. };

A0EE71ED-F67B-4A88-9E57-30F2C581E3A3.png-91kB


添加新批注
在作者公开此批注前,只有你和作者可见。
回复批注