13.1.13.4.2. 值控制項#

這些是會儲存設定的控制項。每一個都帶有一個 value，而 Save 會將編輯後的 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（字串）-- 顯示在方框旁邊的文字。僅限純文字（不同於其他控制項，那些控制項的標籤可接受豐富文字）。
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#

一個水平 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（字串）-- 顯示在 slider 旁數值讀數之前的文字，例如 "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 都會限制欄位所能接受的內容，但角度相反 -- 遮罩固定文字的 排列格式，正規表示式則約束其內容。帶有其中任一者的欄位，是唯一能夠阻擋 Save 的控制項：若其文字不完整或不相符，編輯器會以其 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;_" 會將空欄位顯示為 ___.___.___.___。若省略它，則空白處會是空格。只要有任何 required 位置仍為空，該輸入內容即為不完整，這將阻擋 Save。

13.1.13.4.2.7.2. 正規表示式#

regex 檢查的是內容而非排列格式，當規則是「這些字元、這種模式」而非一個固定欄位時，它是更合適的選擇。整個輸入內容都必須相符 -- 表示式在兩端都被錨定，因此 "[A-Za-z0-9-]+" 意味著從頭到尾只能是字母、數字與破折號，而不只是「包含其中之一」。

此檢查會在每一次按鍵時執行。只要文字仍有可能發展成完整相符，字元就會被接受；一旦不可能，字元便會立即被拒絕，因此使用者永遠無法輸入出無效的內容。唯有當整個表示式相符時，欄位才算有效 -- 且才允許 Save；尚在途中的部分輸入會被保留，但會阻擋 Save，直到它完整為止。

若要建立並測試一個模式，regex101.com 會在你輸入時說明每一個部分 -- 請將其 flavor 設為 PCRE2，即編輯器所使用的語法。