> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bricks.tools/llms.txt
> Use this file to discover all available pages before exploring further.

# 編輯器

> 在 CTOR 內以視覺方式編輯專案設定

**編輯器**分頁內嵌 [BRICKS Controller](/zh-Hant/controller) 提供的同一個視覺化 [Config Editor](/zh-Hant/controller/config-editor)，但改為連線至您的本機專案。您可以視覺化地編輯 Subspace、Canvas、Brick、Generator、Data、Animation 與 Data Calculation，而儲存時會將您的編輯編譯成專案的 bricks-ctor TypeScript 原始程式碼，並提交至 Git。編輯器可在專案工作階段中使用——而非主聊天——並會沿用 CTOR 的語言與主題。它同時適用於應用程式專案與模組專案。

編輯器使用與網頁版 Config Editor 相同的實體模型。關於 Subspace、Canvas、Brick、Generator、Data、Animation 與 Data Calculation 的定義，請參閱 [Config Editor 參考](/zh-Hant/controller/config-editor)。

## 開啟編輯器

從任一[面板](/zh-Hant/ctor/reference/panels)的 **+**（新增分頁）選單新增**編輯器**分頁。

## 需求

<Info>
  編輯器需要全域安裝的 [BRICKS CLI](/zh-Hant/cli)，版本為 **2.25.0 或更新版本**。

  * **較舊的 CLI**——編輯器會顯示「設定編輯器需要 BRICKS CLI 2.25.0 或更新版本，請更新後再使用。」，並附上您目前的版本與**更新 BRICKS CLI** 按鈕。
  * **已淘汰的套件**——使用已淘汰 bricks-ctor 套件的專案會顯示遷移提示，並附上**遷移**按鈕。
  * **未安裝 CLI**——編輯器會顯示「找不到 BRICKS CLI，請執行以下指令安裝：」與安裝指令。
</Info>

## 工具列

編輯器工具列有以下控制項：

| 控制項                       | 動作                                                                                  |
| ------------------------- | ----------------------------------------------------------------------------------- |
| **Undo** / **Redo**       | 逐步復原與重做您的編輯                                                                         |
| **History**               | 開啟編輯歷程面板                                                                            |
| **Single** / **Subspace** | 在檢視單一 Canvas 與整個 Subspace 之間切換。目前 Subspace 有多個 Canvas 時會顯示此區段                       |
| **Grid** / **Preview**    | 切換 Brick 版面配置的算繪模式。這是編輯器內的版面算繪模式，與右側面板的[模擬器](/zh-Hant/ctor/reference/simulator)分頁不同 |
| 儲存狀態圓點                    | 顯示您的編輯是否已儲存——請參閱[儲存狀態](#儲存狀態)                                                       |
| **重新載入**                  | 從磁碟重新載入已編譯的設定                                                                       |
| **儲存**                    | 儲存您的編輯並提交                                                                           |

## 儲存與提交

點選**儲存**會開啟提交訊息快顯，並預先填入預留位置 `chore: update config from CTOR editor`。以**儲存並提交**確認以寫入您的編輯。

儲存時會：

* 為您的編輯產生原始程式碼檔案——`application.json`、`app.ts`、`root.ts`，以及 `subspaces/` 與 `automation-tests/` 下的檔案。
* 編譯並型別檢查所產生的原始程式碼。
* 建立一個 Git 提交——主旨為您的訊息（或預設的預留位置），內文為變更摘要。只有編輯器產生或移除的檔案會被暫存，絕不包含您無關的變更。

若編譯或型別檢查失敗，儲存會被拒絕並顯示失敗內容。不會提交任何內容。

## 儲存狀態

儲存狀態圓點會回報您編輯的狀態。將游標停留在其上可檢視完整文字。

| 狀態          | 意義            |
| ----------- | ------------- |
| **已儲存**     | 您的編輯已寫入並提交    |
| **未儲存**     | 您有尚未儲存的編輯     |
| **正在儲存...** | 儲存進行中         |
| 衝突警告        | 已編譯設定在編輯器外部變更 |
| 錯誤          | 上次儲存失敗        |

若您有尚未儲存的編輯，而已編譯設定在編輯器外部變更（例如代理編輯了原始程式碼），儲存時會顯示「已編譯設定在編輯器外部變更。請重新載入或處理外部變更後再儲存。」編輯器會嘗試自動合併外部變更並重試儲存；若無法合併，請先使用**重新載入**或處理該變更。

**重新載入**會捨棄您尚未儲存的編輯——並確認「要捨棄尚未儲存的設定編輯器變更嗎？」——同時清除復原歷程。

## 鍵盤快速鍵

| 快速鍵                          | 動作      |
| ---------------------------- | ------- |
| **Cmd/Ctrl+Z**               | 復原      |
| **Cmd+Shift+Z** 或 **Ctrl+Y** | 重做      |
| **Backspace** / **Delete**   | 移除選取的項目 |
| **Cmd/Ctrl+C**               | 複製選取內容  |
| **Cmd/Ctrl+V**               | 貼上      |
| **Cmd/Ctrl+D**               | 再製選取內容  |

當您正在文字欄位中輸入時，複製、貼上與再製會略過。在任何項目上按右鍵可開啟其快顯選單。

複製的 Brick 與 Canvas 可在編輯器與網頁版 [Config Editor](/zh-Hant/controller/config-editor) 之間雙向移動，因此您可以在其中一邊複製，並在另一邊貼上。

## 命令選擇區

當**編輯器**分頁為使用中時，按 **Cmd/Ctrl+K** 開啟編輯器的命令選擇區，其標題為 **編輯器指令**。內容包含：

* **New: Subspace / Canvas / Data / General Data Calculation / Script Data Calculation / Animation**——建立該類型的新項目。
* **New Brick: \<name>** 與 **New Generator: \<name>**——建立指定類型的新 Brick 或 Generator。
* 針對設定中既有項目的前往導覽。

模組專案無法建立 Subspace。

## 即時模擬與代理

您尚未儲存的編輯會即時算繪在[模擬器](/zh-Hant/ctor/reference/simulator)中，代理的螢幕截圖也會使用這些編輯，因此您看到的內容會與代理看到的一致。

當代理在編輯器開啟時變更設定，該變更會就地套用——受影響的 Brick、Canvas 框架與清單列會短暫閃動，讓您看出變更之處。

代理也能看見您的編輯器狀態：編輯器是否開啟、是否有尚未儲存的編輯、目前的 Subspace、目前選取內容，以及近期編輯歷程。這讓代理能與您的視覺化編輯同步進行。

## 尚未儲存的編輯保護

在您有尚未儲存的編輯時切換工作階段或專案、關閉**編輯器**分頁，或關閉視窗，都會先詢問「要捨棄尚未儲存的設定編輯器變更嗎？」，以免您不慎遺失工作內容。

## 個別項目說明

許多項目帶有說明（**?**）圖示。點選即可開啟停靠的參考抽屜，並以編輯器的語言顯示。

## 後續步驟

<CardGroup cols={2}>
  <Card title="模擬器" icon="play" href="/zh-Hant/ctor/reference/simulator">
    在內嵌模擬器中執行您的專案，即時檢視尚未儲存的編輯器編輯。
  </Card>

  <Card title="Config Editor" icon="pen-to-square" href="/zh-Hant/controller/config-editor">
    了解 Subspace、Canvas、Brick 與 Generator 背後的實體模型。
  </Card>
</CardGroup>