跳轉到主要內容

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.

bricks-ctor 是一套 TypeScript SDK，讓您完全以程式碼的方式定義、建置與部署 BRICKS 應用。相較於使用視覺化編輯器，您可以撰寫 TypeScript，並將其編譯為 BRICKS 運行時可理解的設定。
bricks-ctor 目前為預覽版。API 與工具可能會有所調整。

​
為什麼選擇程式碼？

  • 型別安全 —透過完整的 TypeScript 支援，在編譯時期即可攔截錯誤
  • 版本控管 —以 Git 追蹤變更、審閱差異、協同合作
  • AI 輔助開發 —與可讀寫專案檔案的 AI 程式設計代理共同開發
  • 自動化 —透過 CLI 或 GitHub Actions 等 CI/CD 管線進行部署

​
核心概念

一個 BRICKS 應用是由可組合的實體所構成的樹狀結構，架構如下： 
Application
└── Subspace(功能/畫面容器)
    ├── Canvas(檢視/場景版面)
    │   └── Items(Brick 或 Subspace 參照的定位元素)
    ├── Brick(UI 元件)
    ├── Generator(資料/IO 提供者)
    ├── Data(狀態儲存)
    ├── Animation(視覺效果)
    └── Data Calculation(資料轉換)

​
Subspaces

Subspace 是獨立的功能單元，您可以將其視為一個畫面或功能模組。每個 subspace 擁有自己的 brick、generator、data、canvas 與 animation。應用程式會以 rootSubspace 作為進入點。

​
Canvases

Canvas 定義檢視版面。它會在格線上以 frame 座標(x、y、寬、高）放置項目(brick 或 subspace 參照）。Canvas 支援生命週期事件(firstEnter、enter、exit)，並可在彼此之間切換以進行導覽。

​
Bricks

Brick 是視覺上的建構單位—負責顯示內容並處理互動的 UI 元件。常見範例包含：
Brick用途
Text顯示文字並套用樣式
TextInput可編輯的文字欄位
RichText支援 HTML 內容、多種字型與內嵌圖片的 Rich Text
Image顯示圖片
Video影片播放
VideoStreamingRTSP / RTMP 即時影像串流
WebrtcStreamWebRTC 影音串流
GenerativeMedia由 AI 生成的圖片與影片
WebView內嵌網頁內容
Lottie.json 與 .dotlottie 動畫，支援速度、循環與影格範圍控制
Rive.riv 動畫，支援狀態機輸入、文字取代與 artboard 切換
SvgSVG 向量圖形
Chart資料視覺化
IconFontAwesome 6 Pro 圖示
QrCodeQR code 顯示
Camera相機即時畫面
Maps地圖顯示
Rect具備背景、邊框、陰影的容器
Items以陣列資料驅動的列表或網格
Slideshow具轉場效果的自動切換幻燈片
Brick 可套用樣式、動畫、回應按壓事件，並可將屬性動態繫結至資料。

​
Generators

Generator 負責所有外部 I/O 與資料處理，將應用連線到 API、資料庫、硬體、AI 模型等。每個 generator 擁有輸出埠(outlet，資料輸出通道）連線至 data，並透過事件觸發動作。 Generator 的類別包含：
類別範例
AI & LLMAssistant、LLM (GGML/OpenAI/Anthropic/ONNX)、Vector Store、Reranker
語音Text-to-Speech、Speech-to-Text、VAD、即時語音辨識
網路HTTP、WebSocket、GraphQL、MQTT、TCP、UDP、HTTP Server
儲存File、SQLite、Data Bank、Media Flow
硬體藍牙 LE、序列埠、相機、鍵盤
控制流Tick(計時）、Alarm Clock、Step、Iterator、Watchdog
其他WebRTC、Web Crawler、MCP、熱感印表機

​
Data

Data 節點儲存應用狀態。它們具型別(string、number、boolean、array、object)，並可連結至 brick 或 generator 的屬性以取得反應式更新。當 generator 的 outlet 輸出值時，所連結的 data 會更新，綁定至該 data 的 brick 也會自動重新渲染。

​
Data Calculations

Data calculation 是 JavaScript 函式，用於轉換資料。它們在沙箱環境中執行，並提供 25 個以上內建函式庫(lodash、moment、crypto 等）。適合用於格式化、解析或計算衍生值。

​
Actions 與 Events

Action 是由事件觸發的指令。Brick 與 generator 會發出事件(press、response、error、計時器觸發)，您可將其接線至 action，例如切換 canvas、更新 data、觸發 generator 或執行動畫。

​
專案結構

bricks-ctor 專案的結構如下： 
my-app/
├── application.json              # 應用後設資料(名稱、ID、階段)
├── package.json
├── tsconfig.json
├── app.ts                        # 應用程式進入點
├── root.ts                       # 根 subspace 定義
├── subspaces/
│   └── subspace-0/
│       ├── index.ts              # Subspace 匯出
│       ├── bricks.ts             # Brick 定義
│       ├── canvases.ts           # Canvas 版面
│       ├── generators.ts         # Generator 設定
│       ├── data.ts               # Data 定義
│       ├── animations.ts         # Animation 設定
│       └── data-calc/            # Data calculation 腳本
│           └── index.ts
├── automation-tests/             # E2E 測試定義
├── CLAUDE.md / AGENTS.md         # AI 代理指示(選用)
└── .mcp.json                     # MCP 伺服器設定(自動產生)
所有應用邏輯皆以 TypeScript 檔案定義。執行 bun compile 會將其轉換為 BRICKS 運行時執行所需的 JSON 設定。

​
下一步

開始使用

設定您的開發環境並建立第一個 BRICKS 專案。