添加注释

CustomKeyboard/Resource/kb_keyboard_layout_config.json

@@ -1,194 +1,412 @@
 {
+  "__comment": "键盘布局配置：所有尺寸为设计稿值（会按 designWidth 等比缩放）",
   "designWidth": 375,
+  "__comment_designWidth": "设计稿宽度（如 375），用于计算缩放比例",
   "defaultKeyBackground": "#FFFFFF",
+  "__comment_defaultKeyBackground": "无皮肤时按键默认背景色",
   "metrics": {
+    "__comment": "全局尺寸参数（单位：pt，按 designWidth 缩放）",
     "rowSpacing": 8,
+    "__comment_rowSpacing": "行间距（垂直）",
     "topInset": 8,
+    "__comment_topInset": "键盘顶部内边距",
     "bottomInset": 6,
+    "__comment_bottomInset": "键盘底部内边距",
     "keyHeight": 41,
+    "__comment_keyHeight": "默认按键高度",
     "edgeInset": 4,
+    "__comment_edgeInset": "行左右内边距（默认）",
     "gap": 5,
+    "__comment_gap": "按键之间水平间距",
     "letterWidth": 32,
+    "__comment_letterWidth": "字母键默认宽度",
     "controlWidth": 41,
+    "__comment_controlWidth": "控制键宽度（如 shift/backspace/123）",
     "sendWidth": 88,
+    "__comment_sendWidth": "send 键宽度",
     "symbolsWideWidth": 47,
-    "symbolsSideWidth": 41
+    "__comment_symbolsWideWidth": "符号第3行中间大键宽度",
+    "symbolsSideWidth": 41,
+    "__comment_symbolsSideWidth": "符号第3行左右控制键宽度"
   },
   "fonts": {
+    "__comment": "字体大小（pt）",
     "letter": 20,
+    "__comment_letter": "字母键字体大小",
     "digit": 20,
+    "__comment_digit": "数字键字体大小",
     "symbol": 18,
+    "__comment_symbol": "符号键字体大小",
     "mode": 14,
+    "__comment_mode": "模式切换键字体大小（ABC/#+=/123）",
     "space": 18,
-    "send": 18
+    "__comment_space": "空格键字体大小",
+    "send": 18,
+    "__comment_send": "发送键字体大小"
   },
   "keyDefs": {
-    "shift": { "type": "shift", "title": "⇧", "symbolName": "shift", "selectedSymbolName": "shift.fill", "font": "symbol", "width": "controlWidth", "backgroundColor": "#B7BBC4" },
-    "backspace": { "type": "backspace", "title": "⌫", "font": "symbol", "width": "controlWidth", "backgroundColor": "#B7BBC4" },
-    "mode_123": { "type": "mode", "title": "123", "font": "mode", "width": "controlWidth", "backgroundColor": "#B7BBC4" },
-    "mode_abc": { "type": "mode", "title": "ABC", "font": "mode", "width": "controlWidth", "backgroundColor": "#B7BBC4" },
-    "symbols_toggle_more": { "type": "symbolsToggle", "title": "#+=", "font": "mode", "width": "symbolsSideWidth", "backgroundColor": "#B7BBC4" },
-    "symbols_toggle_123": { "type": "symbolsToggle", "title": "123", "font": "mode", "width": "symbolsSideWidth", "backgroundColor": "#B7BBC4" },
-    "emoji": { "type": "custom", "title": "😁", "font": "symbol", "width": "controlWidth", "backgroundColor": "#B7BBC4" },
-    "space": { "type": "space", "title": "space", "font": "space", "width": "flex" },
-    "send": { "type": "return", "title": "send", "font": "send", "width": "sendWidth", "backgroundColor": "#B7BBC4" }
+    "__comment": "特殊功能键配置（id 对应布局中的 item）",
+    "shift": {
+      "__comment": "大小写切换键",
+      "type": "shift",
+      "__comment_type": "类型：shift/backspace/mode/symbolsToggle/space/return/custom",
+      "title": "⇧",
+      "__comment_title": "按钮文本（无皮肤时显示）",
+      "symbolName": "shift",
+      "__comment_symbolName": "无皮肤时使用 SF Symbol 名称",
+      "selectedSymbolName": "shift.fill",
+      "__comment_selectedSymbolName": "选中态 SF Symbol 名称",
+      "font": "symbol",
+      "__comment_font": "使用 fonts 中哪一类字号",
+      "width": "controlWidth",
+      "__comment_width": "宽度：引用 metrics 中字段或具体数值",
+      "backgroundColor": "#B7BBC4",
+      "__comment_backgroundColor": "按键背景色"
+    },
+    "backspace": {
+      "__comment": "删除键",
+      "type": "backspace",
+      "__comment_type": "类型：shift/backspace/mode/symbolsToggle/space/return/custom",
+      "title": "⌫",
+      "__comment_title": "按钮文本（无皮肤时显示）",
+      "font": "symbol",
+      "__comment_font": "使用 fonts 中哪一类字号",
+      "width": "controlWidth",
+      "__comment_width": "宽度：引用 metrics 中字段或具体数值",
+      "backgroundColor": "#B7BBC4",
+      "__comment_backgroundColor": "按键背景色"
+    },
+    "mode_123": {
+      "__comment": "字母面板左下角 123",
+      "type": "mode",
+      "__comment_type": "类型：shift/backspace/mode/symbolsToggle/space/return/custom",
+      "title": "123",
+      "__comment_title": "按钮文本（无皮肤时显示）",
+      "font": "mode",
+      "__comment_font": "使用 fonts 中哪一类字号",
+      "width": "controlWidth",
+      "__comment_width": "宽度：引用 metrics 中字段或具体数值",
+      "backgroundColor": "#B7BBC4",
+      "__comment_backgroundColor": "按键背景色"
+    },
+    "mode_abc": {
+      "__comment": "数字面板左下角 ABC",
+      "type": "mode",
+      "__comment_type": "类型：shift/backspace/mode/symbolsToggle/space/return/custom",
+      "title": "ABC",
+      "__comment_title": "按钮文本（无皮肤时显示）",
+      "font": "mode",
+      "__comment_font": "使用 fonts 中哪一类字号",
+      "width": "controlWidth",
+      "__comment_width": "宽度：引用 metrics 中字段或具体数值",
+      "backgroundColor": "#B7BBC4",
+      "__comment_backgroundColor": "按键背景色"
+    },
+    "symbols_toggle_more": {
+      "__comment": "数字面板内 123 -> #+=",
+      "type": "symbolsToggle",
+      "__comment_type": "类型：shift/backspace/mode/symbolsToggle/space/return/custom",
+      "title": "#+=",
+      "__comment_title": "按钮文本（无皮肤时显示）",
+      "font": "mode",
+      "__comment_font": "使用 fonts 中哪一类字号",
+      "width": "symbolsSideWidth",
+      "__comment_width": "宽度：引用 metrics 中字段或具体数值",
+      "backgroundColor": "#B7BBC4",
+      "__comment_backgroundColor": "按键背景色"
+    },
+    "symbols_toggle_123": {
+      "__comment": "数字面板内 #+= -> 123",
+      "type": "symbolsToggle",
+      "__comment_type": "类型：shift/backspace/mode/symbolsToggle/space/return/custom",
+      "title": "123",
+      "__comment_title": "按钮文本（无皮肤时显示）",
+      "font": "mode",
+      "__comment_font": "使用 fonts 中哪一类字号",
+      "width": "symbolsSideWidth",
+      "__comment_width": "宽度：引用 metrics 中字段或具体数值",
+      "backgroundColor": "#B7BBC4",
+      "__comment_backgroundColor": "按键背景色"
+    },
+    "emoji": {
+      "__comment": "emoji 功能键",
+      "type": "custom",
+      "__comment_type": "类型：shift/backspace/mode/symbolsToggle/space/return/custom",
+      "title": "😁",
+      "__comment_title": "按钮文本（无皮肤时显示）",
+      "font": "symbol",
+      "__comment_font": "使用 fonts 中哪一类字号",
+      "width": "controlWidth",
+      "__comment_width": "宽度：引用 metrics 中字段或具体数值",
+      "backgroundColor": "#B7BBC4",
+      "__comment_backgroundColor": "按键背景色"
+    },
+    "space": {
+      "__comment": "空格键",
+      "type": "space",
+      "__comment_type": "类型：shift/backspace/mode/symbolsToggle/space/return/custom",
+      "title": "space",
+      "__comment_title": "按钮文本（无皮肤时显示）",
+      "font": "space",
+      "__comment_font": "使用 fonts 中哪一类字号",
+      "width": "flex",
+      "__comment_width": "flex 表示自动占满剩余空间"
+    },
+    "send": {
+      "__comment": "发送键",
+      "type": "return",
+      "__comment_type": "类型：shift/backspace/mode/symbolsToggle/space/return/custom",
+      "title": "send",
+      "__comment_title": "按钮文本（无皮肤时显示）",
+      "font": "send",
+      "__comment_font": "使用 fonts 中哪一类字号",
+      "width": "sendWidth",
+      "__comment_width": "宽度：引用 metrics 中字段或具体数值",
+      "backgroundColor": "#B7BBC4",
+      "__comment_backgroundColor": "按键背景色"
+    }
   },
   "layouts": {
+    "__comment": "布局集合：letters/numbers/symbolsMore",
     "letters": {
+      "__comment": "字母布局（小写/大写共用）",
       "rows": [
         {
+          "__comment": "字母第一行 qwertyuiop",
           "align": "left",
+          "__comment_align": "对齐方式：left/center",
           "insetLeft": 4,
+          "__comment_insetLeft": "本行左边距（覆盖 metrics.edgeInset）",
           "insetRight": 4,
+          "__comment_insetRight": "本行右边距（覆盖 metrics.edgeInset）",
           "gap": 5,
+          "__comment_gap": "本行按键间距（覆盖 metrics.gap）",
           "items": [
             "letter:q", "letter:w", "letter:e", "letter:r", "letter:t",
             "letter:y", "letter:u", "letter:i", "letter:o", "letter:p"
-          ]
+          ],
+          "__comment_items": "本行按键列表；letter:x/digit:x/sym:x 或 keyDefs 中的 id"
         },
         {
+          "__comment": "字母第二行 asdfghjkl",
           "align": "center",
+          "__comment_align": "对齐方式：left/center",
           "insetLeft": 0,
+          "__comment_insetLeft": "本行左边距（覆盖 metrics.edgeInset）",
           "insetRight": 0,
+          "__comment_insetRight": "本行右边距（覆盖 metrics.edgeInset）",
           "gap": 5,
+          "__comment_gap": "本行按键间距（覆盖 metrics.gap）",
           "items": [
             "letter:a", "letter:s", "letter:d", "letter:f", "letter:g",
             "letter:h", "letter:j", "letter:k", "letter:l"
-          ]
+          ],
+          "__comment_items": "本行按键列表；letter:x/digit:x/sym:x 或 keyDefs 中的 id"
         },
         {
+          "__comment": "字母第三行：左 shift，中间字母，右 backspace",
           "align": "left",
+          "__comment_align": "对齐方式：left/center",
           "insetLeft": 4,
+          "__comment_insetLeft": "本行左边距（覆盖 metrics.edgeInset）",
           "insetRight": 4,
+          "__comment_insetRight": "本行右边距（覆盖 metrics.edgeInset）",
           "gap": 5,
+          "__comment_gap": "本行按键间距（覆盖 metrics.gap）",
           "segments": {
+            "__comment": "分段布局：left/center/right",
             "left": [
-              { "id": "shift", "width": "controlWidth" }
+              { "id": "shift", "width": "controlWidth", "__comment_id": "引用 keyDefs 的 id", "__comment_width": "宽度引用 metrics.controlWidth" }
             ],
+            "__comment_left": "左侧固定按钮",
             "center": [
               "letter:z", "letter:x", "letter:c", "letter:v", "letter:b", "letter:n", "letter:m"
             ],
+            "__comment_center": "中间字母键集合，整体居中",
             "right": [
-              { "id": "backspace", "width": "controlWidth" }
-            ]
+              { "id": "backspace", "width": "controlWidth", "__comment_id": "引用 keyDefs 的 id", "__comment_width": "宽度引用 metrics.controlWidth" }
+            ],
+            "__comment_right": "右侧固定按钮"
           }
         },
         {
+          "__comment": "字母第四行：123/emoji/space/send",
           "align": "left",
+          "__comment_align": "对齐方式：left/center",
           "insetLeft": 4,
+          "__comment_insetLeft": "本行左边距（覆盖 metrics.edgeInset）",
           "insetRight": 4,
+          "__comment_insetRight": "本行右边距（覆盖 metrics.edgeInset）",
           "gap": 5,
+          "__comment_gap": "本行按键间距（覆盖 metrics.gap）",
           "items": [
             "mode_123", "emoji", "space", "send"
-          ]
+          ],
+          "__comment_items": "本行按键列表；letter:x/digit:x/sym:x 或 keyDefs 中的 id"
         }
       ]
     },
     "numbers": {
+      "__comment": "数字面板布局（123 页）",
       "rows": [
         {
+          "__comment": "数字第一行 1234567890",
           "align": "left",
+          "__comment_align": "对齐方式：left/center",
           "insetLeft": 4,
+          "__comment_insetLeft": "本行左边距（覆盖 metrics.edgeInset）",
           "insetRight": 4,
+          "__comment_insetRight": "本行右边距（覆盖 metrics.edgeInset）",
           "gap": 5,
+          "__comment_gap": "本行按键间距（覆盖 metrics.gap）",
           "items": [
             "digit:1", "digit:2", "digit:3", "digit:4", "digit:5",
             "digit:6", "digit:7", "digit:8", "digit:9", "digit:0"
-          ]
+          ],
+          "__comment_items": "本行按键列表；letter:x/digit:x/sym:x 或 keyDefs 中的 id"
         },
         {
+          "__comment": "数字第二行 - / : ; ( ) ￥ & @ “",
           "align": "left",
+          "__comment_align": "对齐方式：left/center",
           "insetLeft": 4,
+          "__comment_insetLeft": "本行左边距（覆盖 metrics.edgeInset）",
           "insetRight": 4,
+          "__comment_insetRight": "本行右边距（覆盖 metrics.edgeInset）",
           "gap": 5,
+          "__comment_gap": "本行按键间距（覆盖 metrics.gap）",
           "items": [
             "sym:-", "sym:/", "sym::", "sym:;", "sym:(",
             "sym:)", "sym:￥", "sym:&", "sym:@", "sym:“"
-          ]
+          ],
+          "__comment_items": "本行按键列表；letter:x/digit:x/sym:x 或 keyDefs 中的 id"
         },
         {
+          "__comment": "数字第三行：#+= / 中间符号 / 删除",
           "align": "center",
+          "__comment_align": "对齐方式：left/center",
           "insetLeft": 4,
+          "__comment_insetLeft": "本行左边距（覆盖 metrics.edgeInset）",
           "insetRight": 4,
+          "__comment_insetRight": "本行右边距（覆盖 metrics.edgeInset）",
           "gap": 5,
+          "__comment_gap": "本行按键间距（覆盖 metrics.gap）",
           "segments": {
+            "__comment": "分段布局：left/center/right",
             "left": [
-              { "id": "symbols_toggle_more", "width": "symbolsSideWidth" }
+              { "id": "symbols_toggle_more", "width": "symbolsSideWidth", "__comment_id": "引用 keyDefs 的 id", "__comment_width": "宽度引用 metrics.symbolsSideWidth" }
             ],
+            "__comment_left": "左侧切换按钮",
             "center": [
-              { "id": "sym:.", "width": "symbolsWideWidth" },
-              { "id": "sym:,", "width": "symbolsWideWidth" },
-              { "id": "sym:?", "width": "symbolsWideWidth" },
-              { "id": "sym:!", "width": "symbolsWideWidth" },
-              { "id": "sym:‘", "width": "symbolsWideWidth" }
+              { "id": "sym:.", "width": "symbolsWideWidth", "__comment_id": "符号键 id", "__comment_width": "宽度引用 metrics.symbolsWideWidth" },
+              { "id": "sym:,", "width": "symbolsWideWidth", "__comment_id": "符号键 id", "__comment_width": "宽度引用 metrics.symbolsWideWidth" },
+              { "id": "sym:?", "width": "symbolsWideWidth", "__comment_id": "符号键 id", "__comment_width": "宽度引用 metrics.symbolsWideWidth" },
+              { "id": "sym:!", "width": "symbolsWideWidth", "__comment_id": "符号键 id", "__comment_width": "宽度引用 metrics.symbolsWideWidth" },
+              { "id": "sym:‘", "width": "symbolsWideWidth", "__comment_id": "符号键 id", "__comment_width": "宽度引用 metrics.symbolsWideWidth" }
             ],
+            "__comment_center": "中间符号键集合，整体居中",
             "right": [
-              { "id": "backspace", "width": "symbolsSideWidth" }
-            ]
+              { "id": "backspace", "width": "symbolsSideWidth", "__comment_id": "引用 keyDefs 的 id", "__comment_width": "宽度引用 metrics.symbolsSideWidth" }
+            ],
+            "__comment_right": "右侧删除键"
           }
         },
         {
+          "__comment": "数字第四行：ABC/emoji/space/send",
           "align": "left",
+          "__comment_align": "对齐方式：left/center",
           "insetLeft": 4,
+          "__comment_insetLeft": "本行左边距（覆盖 metrics.edgeInset）",
           "insetRight": 4,
+          "__comment_insetRight": "本行右边距（覆盖 metrics.edgeInset）",
           "gap": 5,
+          "__comment_gap": "本行按键间距（覆盖 metrics.gap）",
           "items": [
             "mode_abc", "emoji", "space", "send"
-          ]
+          ],
+          "__comment_items": "本行按键列表；letter:x/digit:x/sym:x 或 keyDefs 中的 id"
         }
       ]
     },
     "symbolsMore": {
+      "__comment": "符号面板布局（#+= 页）",
       "rows": [
         {
+          "__comment": "符号第一行 [ ] { } # % ^ * + =",
           "align": "left",
+          "__comment_align": "对齐方式：left/center",
           "insetLeft": 4,
+          "__comment_insetLeft": "本行左边距（覆盖 metrics.edgeInset）",
           "insetRight": 4,
+          "__comment_insetRight": "本行右边距（覆盖 metrics.edgeInset）",
           "gap": 5,
+          "__comment_gap": "本行按键间距（覆盖 metrics.gap）",
           "items": [
             "sym:[", "sym:]", "sym:{", "sym:}", "sym:#",
             "sym:%", "sym:^", "sym:*", "sym:+", "sym:="
-          ]
+          ],
+          "__comment_items": "本行按键列表；letter:x/digit:x/sym:x 或 keyDefs 中的 id"
         },
         {
+          "__comment": "符号第二行 _ \\ | ~ < > € ￥ $ ·",
           "align": "left",
+          "__comment_align": "对齐方式：left/center",
           "insetLeft": 4,
+          "__comment_insetLeft": "本行左边距（覆盖 metrics.edgeInset）",
           "insetRight": 4,
+          "__comment_insetRight": "本行右边距（覆盖 metrics.edgeInset）",
           "gap": 5,
+          "__comment_gap": "本行按键间距（覆盖 metrics.gap）",
           "items": [
             "sym:_", "sym:\\", "sym:|", "sym:~", "sym:<",
             "sym:>", "sym:€", "sym:￥", "sym:$", "sym:·"
-          ]
+          ],
+          "__comment_items": "本行按键列表；letter:x/digit:x/sym:x 或 keyDefs 中的 id"
         },
         {
+          "__comment": "符号第三行：123 / 中间符号 / 删除",
           "align": "center",
+          "__comment_align": "对齐方式：left/center",
           "insetLeft": 4,
+          "__comment_insetLeft": "本行左边距（覆盖 metrics.edgeInset）",
           "insetRight": 4,
+          "__comment_insetRight": "本行右边距（覆盖 metrics.edgeInset）",
           "gap": 5,
+          "__comment_gap": "本行按键间距（覆盖 metrics.gap）",
           "segments": {
+            "__comment": "分段布局：left/center/right",
             "left": [
-              { "id": "symbols_toggle_123", "width": "symbolsSideWidth" }
+              { "id": "symbols_toggle_123", "width": "symbolsSideWidth", "__comment_id": "引用 keyDefs 的 id", "__comment_width": "宽度引用 metrics.symbolsSideWidth" }
             ],
+            "__comment_left": "左侧切换按钮",
             "center": [
-              { "id": "sym:.", "width": "symbolsWideWidth" },
-              { "id": "sym:,", "width": "symbolsWideWidth" },
-              { "id": "sym:?", "width": "symbolsWideWidth" },
-              { "id": "sym:!", "width": "symbolsWideWidth" },
-              { "id": "sym:‘", "width": "symbolsWideWidth" }
+              { "id": "sym:.", "width": "symbolsWideWidth", "__comment_id": "符号键 id", "__comment_width": "宽度引用 metrics.symbolsWideWidth" },
+              { "id": "sym:,", "width": "symbolsWideWidth", "__comment_id": "符号键 id", "__comment_width": "宽度引用 metrics.symbolsWideWidth" },
+              { "id": "sym:?", "width": "symbolsWideWidth", "__comment_id": "符号键 id", "__comment_width": "宽度引用 metrics.symbolsWideWidth" },
+              { "id": "sym:!", "width": "symbolsWideWidth", "__comment_id": "符号键 id", "__comment_width": "宽度引用 metrics.symbolsWideWidth" },
+              { "id": "sym:‘", "width": "symbolsWideWidth", "__comment_id": "符号键 id", "__comment_width": "宽度引用 metrics.symbolsWideWidth" }
             ],
+            "__comment_center": "中间符号键集合，整体居中",
             "right": [
-              { "id": "backspace", "width": "symbolsSideWidth" }
-            ]
+              { "id": "backspace", "width": "symbolsSideWidth", "__comment_id": "引用 keyDefs 的 id", "__comment_width": "宽度引用 metrics.symbolsSideWidth" }
+            ],
+            "__comment_right": "右侧删除键"
           }
         },
         {
+          "__comment": "符号第四行：ABC/emoji/space/send",
           "align": "left",
+          "__comment_align": "对齐方式：left/center",
           "insetLeft": 4,
+          "__comment_insetLeft": "本行左边距（覆盖 metrics.edgeInset）",
           "insetRight": 4,
+          "__comment_insetRight": "本行右边距（覆盖 metrics.edgeInset）",
           "gap": 5,
+          "__comment_gap": "本行按键间距（覆盖 metrics.gap）",
           "items": [
             "mode_abc", "emoji", "space", "send"
-          ]
+          ],
+          "__comment_items": "本行按键列表；letter:x/digit:x/sym:x 或 keyDefs 中的 id"
         }
       ]
     }