13.1.13.4.2. 取值控件#

这些是保存设置的控件。每个控件都带有一个 value，保存时会将编辑后的 value 写回控件。下表是从控件到其所存储 JSON 类型的快速对照；随后的各节会说明每个键。

控件	保存内容
checkbox	布尔值，或整数 `0`/`1`/`2`
combobox	所选的值，或其索引
radio	所选的值，或其索引
spinbox	整数
doublespinbox	数字（浮点数）
slider	整数
lineedit	字符串

所有值控件也接受这些通用键（ name 、 label 、 tooltip 、 enabled ）；请参阅概览。 label 显示在控件旁边（对于 checkbox 则显示在框本身上）。

13.1.13.4.2.1. checkbox#

一个开/关开关。可选设为三态，用于具有“未设置”中间状态的设置。

{ "type": "checkbox", "name": "draw_overlays", "label": "Draw Overlays", "value": true }

参数：

label（字符串）-- 显示在方框旁边的文本。仅支持纯文本（不同于其他控件，其 label 支持富文本）。
tristate（布尔值，默认 false）-- 允许第三种部分勾选的状态。
value -- 初始状态。两态：布尔值。三态：\ 0（关）、\ 1（部分）或 2（开）。

保存内容：两态方框保存一个 布尔值；三态方框保存一个整数 0、1 或 2。

13.1.13.4.2.2. combobox#

一个包含多个选项的下拉菜单。

{
  "type": "combobox",
  "name": "resolution",
  "label": "Resolution",
  "options": ["QQVGA", "QVGA", "VGA"],
  "values": ["qqvga", "qvga", "vga"],
  "value": "qvga"
}

参数：

options（字符串数组）-- 显示在菜单中的项。
values*（数组）-- 一个可选的与之平行的待保存值数组，每个 *option 对应一个。有 values 时，菜单显示 options[i] 但保存 values[i] -- 因此用户看到的是 "QVGA"，而文件中存储的是 "qvga"。这些条目可以是任意 JSON 类型。没有 values 时，控件则改为保存所选项的索引。
value -- 初始选择。有 values 时，为等于某个 values 的条目。没有 values 时，为要选中项的索引（默认 0）。

保存内容：给定 values 时保存匹配的 values 条目（任意类型）；否则保存所选的索引（整数）。

13.1.13.4.2.3. radio#

一组单选按钮 -- 一次只能选中一项，类似 combobox，但会完整展开排列。

{
  "type": "radio",
  "name": "mode",
  "label": "Mode",
  "options": ["Idle", "Track", "Record"],
  "values": ["idle", "track", "record"],
  "value": "idle",
  "orientation": "horizontal"
}

参数：

options（字符串数组）-- 每个条目对应一个按钮。
values*（数组）-- 可选的待保存值，每个 *option 对应一个，与 combobox 完全相同。没有它时，控件保存所选的索引。
value -- 初始选择，与 values 匹配或用作索引，同 combobox。
orientation（字符串，默认 "vertical"）-- 使用 "horizontal" 可将按钮排成一行，否则排成一列。

保存内容：匹配的 values 条目（任意类型），或所选的索引。

13.1.13.4.2.4. spinbox#

一个用于整数的数字框，带有上/下箭头。

{
  "type": "spinbox",
  "name": "server_port",
  "label": "Port",
  "value": 8080,
  "min": 0,
  "max": 65535,
  "group_separator": true
}

参数：

value（整数，默认 0）-- 初始数值。
min*（整数，默认为 ``0`` 或 *value 中较小者）-- 允许的最小值。
max*（整数，默认为 ``100`` 或 *value 中较大者）-- 允许的最大值。
step（整数，默认 1）-- 上/下调整的增量。
prefix（字符串）-- 显示在数字前面的文本，例如 "0x"。
suffix（字符串）-- 显示在数字后面的文本，例如像 " px" 这样的单位。
base（整数，默认 10）-- 显示进制；设为 16 可以十六进制显示和编辑数字。
group_separator（布尔值，默认 false）-- 用千位分隔符对数字分组。
special_value_text*（字符串）-- 当数值处于 *min 时用来替代数字显示的文本，例如在 0 处显示“Off”。

保存内容：一个整数。

13.1.13.4.2.5. doublespinbox#

一个用于小数的数字框。

{
  "type": "doublespinbox",
  "name": "sensitivity",
  "label": "Sensitivity",
  "value": 50.0,
  "min": 0,
  "max": 100,
  "step": 0.5,
  "decimals": 1,
  "suffix": " %"
}

参数：

value（数字，默认 0）-- 初始数值。
min*（数字，默认为 ``0`` 或 *value 中较小者）-- 允许的最小值。
max*（数字，默认为 ``100`` 或 *value 中较大者）-- 允许的最大值。
decimals（整数，默认 2）-- 小数点后显示多少位数字。
step（数字，默认 1.0）-- 上/下调整的增量。
prefix（字符串）-- 显示在数字前面的文本，例如 "max "。
suffix（字符串）-- 显示在数字后面的文本，例如像 " %" 这样的单位。
group_separator（布尔值，默认 false）-- 千位分隔符。
special_value_text*（字符串）-- 当数值处于 *min 时显示的文本。

保存内容：一个数字（浮点数）。

13.1.13.4.2.6. slider#

一个水平滑块，旁边带有实时的数值读数。

{
  "type": "slider",
  "name": "brightness",
  "label": "Brightness",
  "value": 50,
  "min": 0,
  "max": 100,
  "step": 1,
  "suffix": " %",
  "ticks": 25
}

参数：

value（整数，默认 0）-- 初始位置。
min*（整数，默认为 ``0`` 或 *value 中较小者）-- 滑轨的低端。
max*（整数，默认为 ``100`` 或 *value 中较大者）-- 滑轨的高端。
step（整数，默认 1）-- 键盘和拖动的增量；拖动会吸附到最接近的倍数。
prefix（字符串）-- 显示在滑块旁数值读数前面的文本，例如 "x"。
suffix（字符串）-- 显示在读数后面的文本，例如 " %"。
ticks（整数）-- 绘制在滑轨下方的刻度线间距。

保存内容：一个整数。

13.1.13.4.2.7. lineedit#

一个单行文本字段，用于名称、密码、地址之类的内容。

{
  "type": "lineedit",
  "name": "hostname",
  "label": "Hostname",
  "value": "openmv-cam",
  "placeholder": "letters, digits, dashes",
  "regex": "[A-Za-z0-9-]+",
  "clear_button": true
}

参数：

value（字符串，默认 ""）-- 初始文本。
placeholder（字符串）-- 字段为空时显示的灰色提示文本。
max_length（整数）-- 字段接受的最大字符数。
mask（字符串）-- 一个固定可输入内容格式的输入掩码，例如用于 IPv4 地址的 "000.000.000.000;_"。参见下面的 Input masks。
regex（字符串）-- 整个输入内容必须匹配的正则表达式。参见下面的 Regular expressions。
clear_button（布尔值，默认 false）-- 在字段内显示一个小的清除按钮。
password（布尔值，默认 false）-- 将文本隐藏为圆点，并添加一个眼睛按钮以显示它。

保存内容：一个 字符串。

mask 和 regex 都从相反的角度限制字段接受的内容 -- 掩码固定文本的格式，正则约束其内容。带有二者之一的字段是唯一能够阻止保存的控件：如果其文本不完整或不匹配，编辑器会按 label 列出该字段，并拒绝保存，直到它被修正或清空为止。同一字段上最多只使用二者中的一个。

13.1.13.4.2.7.1. 输入掩码#

mask 会逐个字符地固定字段：分隔符会为用户预先绘制好，用户只需填入空白处。每个掩码字符代表一个输入位置：

9 -- 必填的数字；0 -- 可选的数字。
A / a -- 必填 / 可选的字母。
N / n -- 必填 / 可选的字母或数字。
X / x -- 必填 / 可选的任意类型字符。
H / h -- 必填 / 可选的十六进制数字。
> / < -- 将其后的字母转为大写 / 小写；! 停止转换。

任何其他字符 -- 000.000.000.000 中的 .、序列号中的 - -- 都是字面分隔符：它会被自动放置，并在用户输入时被跳过。要将掩码字符用作字面字符，请在其前面加一个反斜杠。

末尾附近的 ; 用于设置未填位置所显示的占位符："000.000.000.000;_" 会将空字段显示为 ___.___.___.___。省略它则空白处为空格。只要还有任何必填位置为空，输入就是不完整的，这会阻止保存。

13.1.13.4.2.7.2. 正则表达式#

regex 检查的是内容而非格式，当规则是“这些字符、这种模式”而不是固定字段时更为合适。整个输入内容都必须匹配 -- 表达式在两端都被锚定，因此 "[A-Za-z0-9-]+" 意味着从头到尾只允许字母、数字和短横线，而不仅仅是“包含其中一个”。

每次按键都会进行检查。只要文本仍有可能扩展为完整匹配，字符就会被接受；一旦不再可能，就会立即被拒绝，因此用户永远无法逐字输入出无效的内容。只有当整个表达式匹配时，字段才算有效 -- 也才允许保存；处于中途的部分输入会保留在原处，但会阻止保存，直到它完整为止。

要构建和测试模式，regex101.com 会在你输入时逐部分进行解释 -- 将其风格（flavor）设为 PCRE2，即编辑器所使用的语法。