配置格式

SpaceLauncher 的配置匯出是 JSON 檔案。你可以閱讀、對比、複製到另一臺 Mac，或用自己的指令碼處理它們。

這個頁面是一份面向信任和可檢查性的參考，不是完整 API 規範。格式可能繼續演進，因此工具在處理時應儘量保留未知欄位。

匯出型別

SpaceLauncher 會寫出兩種 JSON 包型別。

.slbindings 只匯出快速鍵綁定：

• format: name.guoc.SpaceLauncher.key-bindings
• version: 當前為 1
• keyBindings: 快速鍵綁定規則陣列

.slbackup 匯出完整 App 備份：

• format: name.guoc.SpaceLauncher.backup
• version: 當前為 1
• configuration: 完整的 AppConfiguration

包的 version 不同於 App 配置的 schemaVersion。當前 AppConfiguration schema 版本是 2。

完整配置

完整的 AppConfiguration 包含：

• schemaVersion
• commandTrees
• bindings
• disabledApplications
• suggestedDisabledApplicationPaths

commandTrees 是當前持久化結構。bindings 也會編碼進去，用於工具和舊匯入路徑相容。

快速鍵綁定規則

每條規則是一個 FlatKeysAndActionRow，主要欄位包括：

• id: UUID
• enabled: 布林值
• applicationScope: allBut(paths) 或 only(paths)
• keys: 觸發鍵 key code 序列
• action: 動作載荷，可帶儲存在 description 中的人工描述
• leaderKey: 按住或輕按的前導鍵定義
• holdContinuationIndexAfterAction: 按住型前導鍵的可選延續設定

applicationScope 有兩種形態：

{
  "allBut": {
    "paths": []
  }
}

{
  "only": {
    "paths": [
      "/Applications/TextEdit.app"
    ]
  }
}

示例

這個 .slbindings 示例包含一條綁定：按住 Space，再按 F 和 D，開啟「下載項目」資料夾。

{
  "appVersion": "3.0.0 (300)",
  "exportedAt": "2026-06-07T12:00:00Z",
  "format": "name.guoc.SpaceLauncher.key-bindings",
  "keyBindings": [
    {
      "action": {
        "description": "Open Downloads",
        "openFolder": {
          "applicationPath": null,
          "folderPath": "~/Downloads"
        }
      },
      "applicationScope": {
        "allBut": {
          "paths": []
        }
      },
      "enabled": true,
      "id": "11111111-2222-4333-8444-555555555555",
      "keys": [
        3,
        2
      ],
      "leaderKey": {
        "hold": {
          "info": {
            "keepsTapFunction": true,
            "keyCode": 49
          }
        }
      }
    }
  ],
  "version": 1
}

在標準 Mac 鍵盤佈局上，key code 49 是 Space。key code 3 和 2 分別是 F 和 D。

匯入行為

匯入快速鍵綁定時，可以把新規則合併到當前設定，也可以替換所有當前快速鍵綁定。合併時，SpaceLauncher 會用前導鍵、觸發鍵和應用範圍檢查重複綁定身份。

完整備份恢復則不同：恢復 .slbackup 會替換 App 配置。它用於備份恢復，不是區域性合併。

為什麼這很重要

這個格式可讀，也適合指令碼處理。你可以檢查一條綁定、用 diff 對比變化、在機器之間遷移設定，或用自己的工具生成規則。SpaceLauncher 也會保留本地滾動、帶時間戳的配置備份，並在儲存前提示快速鍵衝突。