Skip to content
FEE
Frontend Engineering Essentials
Senior Level

[FEE-914] 框架無關的狀態機 — Zag.js 與 Ark UI ​

INFO

Zag.js 將複雜且具備無障礙能力的 UI 元件建模為有限狀態機,讓相同邏輯透過薄薄的適配層即可驅動 React、Vue、Solid 與 Svelte。Ark UI 把這些機器封裝成 45 個以上的 headless 元件,並在各框架間提供一致的 API。本文涵蓋機器模型、connect API,以及這套架構與僅支援 React 的 headless 函式庫之間的差異。

背景 ​

Zag.js 將自己描述為「a framework agnostic toolkit for implementing complex, interactive, and accessible UI components in your design system and web applications」。核心構想是把每個元件的行為以狀態機形式撰寫一次,再透過小型的適配層暴露給任何框架使用。基礎實作受到 XState 啟發,Zag 也明確致謝「XState for inspiring the base implementation of the state machine」,但 Zag 在執行期並不依賴 XState。

由於機器本身僅是純 JavaScript,相同的元件邏輯可透過薄薄的框架適配器在 React、Vue 與 Solid 之間共用:「We provide adapters for JS frameworks so you can use it in React, Solid, or Vue 3.」Ark UI 即建立在這個基礎之上:它是「a headless library with 45+ accessible components」,其 React、Solid、Vue 與 Svelte 套件共享 Zag 中的單一真相來源。

此專案由 Chakra Systems Inc. 在 GitHub chakra-ui 組織下維護,採 MIT 授權:「The Zag.js project is licensed under the MIT License, with copyright held by Chakra UI as of 2021.」儘管承襲自 Chakra,Zag.js 與 Ark UI 皆為框架無關且無樣式,並未依賴 Chakra UI 的樣式層。

視覺對比 ​

從機器定義到渲染 DOM 的資料流走的是固定管線:機器模組由 useMachine(框架適配器)實例化,產出一個 service;connect 再將 service 與 normalizeProps 結合,產出由 prop getter 組成的 api,再展開到 DOM 元素上。

這個管線對應官方文件所列的整合步驟:「All frameworks follow this basic structure: 1. Import the machine and framework adapter 2. Initialize with useMachine ... 3. Connect the machine using connect() with normalizeProps 4. Access API methods like getTriggerProps() and getContentProps().」

範例 ​

下列為 Zag tooltip 元件安裝指南所列的標準用法:

tsx
import * as tooltip from "@zag-js/tooltip"
import { useMachine, normalizeProps } from "@zag-js/react"

function Tooltip() {
  const service = useMachine(tooltip.machine, { id: "1" })
  const api = tooltip.connect(service, normalizeProps)

  return (
    <div>
      <button {...api.getTriggerProps()}>Hover me</button>
      {api.open && (
        <div {...api.getPositionerProps()}>
          <div {...api.getContentProps()}>Tooltip content</div>
        </div>
      )}
    </div>
  )
}

此處有三個關鍵點。第一,useMachine(tooltip.machine, { id: "1" }) 回傳的是 service,一個響應式訂閱控制把手,而非原始狀態。第二,tooltip.connect(service, normalizeProps) 產出 api 物件,同時暴露狀態旗標(api.open)與 prop getter(api.getTriggerProps、api.getContentProps)。第三,每個互動元素的 props 都透過展開 getter 呼叫的回傳值取得;getter 帶有事件處理器、ARIA 屬性以及與機器綁定的識別字。同樣的模式只要把 @zag-js/react 換成 @zag-js/vue 或 @zag-js/solid,即可在這些框架中產出對等的元件。

最佳實踐 ​

  • MUST 將 Zag 與 Ark UI 視為 headless。Zag 並未隨附樣式:「The machine APIs are completely unstyled.」請自備 CSS、Tailwind 層或 design tokens,不要預期任何視覺預設值。
  • MUST 仰賴機器內建的無障礙能力,不要重新實作鍵盤處理。Zag「built with accessibility in mind」,每個機器都已內建 WAI-ARIA 角色、鍵盤互動、焦點管理與 ARIA 屬性。Ark UI 承襲此特性:「Built on top of Zag.js state machines, Ark UI delivers robust, framework-agnostic component logic」並提供符合 WCAG 的預設值。
  • SHOULD 在設計系統需支援多個框架時選擇 Ark UI。依 LogRocket 比較:「Framework Support — Radix Primitives & React Aria: React only. Ark UI: React, Vue, Solid」;採用 Ark UI 可省下在每個框架中重新實作 primitives 的成本。
  • SHOULD 讓心智模型對齊團隊偏好。同一份比較總結為:「Radix Primitives: Component anatomy and composition. React Aria: Hooks with explicit state. Ark UI: State machines and parts.」習慣顯式狀態轉移的團隊會覺得 Zag/Ark 自然,習慣以元件結構思考的團隊則可能偏好 Radix。
  • MAY 在單一框架且需要其他函式庫提供之生態系功能的專案中,將 Ark UI 與框架特定函式庫混用。框架無關性僅在範圍涵蓋多個框架時才能帶來效益。

設計思維 ​

Chakra UI 原作者 Segun Adebayo 明確闡述了動機:「Every interactive component in Chakra UI will be modeled as a state machine ... any solution we build has to be framework agnostic.」取捨在於將元件邏輯撰寫為狀態機的前期成本高於撰寫 React 專屬的 hook,但這份實作可同時驅動 React、Vue、Solid、Angular 與 Svelte 而不分裂。對於希望支援多個框架的設計系統維護者而言,逐框架重寫的成本會隨框架數量線性增長,而機器成本只需付出一次。Chakra Systems 選擇承擔這份前期成本,讓長尾的維護負擔維持有界。

深入探討 ​

Ark UI 在 React 生態中最相近的對手 React Aria Components 採取另一條架構路徑:行為透過 React context 傳遞。Adobe 文件指出「React Aria Components automatically provide behavior to their children by passing event handlers and other attributes via context.」這會把函式庫綁在 React 的執行期上,包含 context、hooks 與 reconciler,也排除了在不重寫傳遞機制的前提下直接移植到 Vue 或 Svelte 的可能。

Zag 的機器加 connect 取徑將 React context 替換為兩個純值:service(響應式訂閱)與 api 物件(prop getters)。兩者皆與框架中性,唯一的 React 特定程式碼存在於 @zag-js/react,由它負責讓元件訂閱 service,並讓 normalizeProps 知道事件名稱該長什麼樣子。把 React 換成 Solid 只需更換適配套件。行為、無障礙能力與狀態轉移皆不變,因為它們存在於機器模組裡,而不在框架特定的 hook 樹內。

狀態機 Connect API ​

Zag 的狀態機是「a way to model stateful, reactive behavior using: A finite number of states [and] A finite number of transitions between those states」。每個機器另外攜帶一份響應式的機器內部 context — 即每個實例的資料(current value、selected index、anchor element 等),轉移可讀取與更新這份資料。機器模組本身為宣告式:states、events、transitions、guards 與 actions,皆不直接存取 DOM。

connect 函式即為機器狀態到 DOM 的橋樑,負責暴露 prop getter:「Methods like getButtonProps() return normalized attributes for elements, encapsulating the machine's state and event handlers for framework-agnostic consumption.」每個 getter 回傳的物件包含事件處理器(onClick、onKeyDown)、ARIA 屬性(aria-expanded、aria-controls)、id、role 與適合當前機器狀態的 data-* 屬性。元件作者再把結果展開到對應的 JSX 元素上。

normalizeProps 是各框架專屬的墊片,負責調和框架表面差異。它「converts the props of the component into the format that is compatible」於目標框架 — 例如 React 使用駝峰式事件名 onKeyDown,而 Vue 樣板使用小寫 onKeydown,且各框架的 inline-style 形狀也不同。機器發出規範化的 prop 形狀;normalizeProps 負責翻譯。這也是同一份機器與同一個 connect 呼叫能在 @zag-js/react、@zag-js/vue 與 @zag-js/solid 之間原封不動運作的原因:唯一改變的只是匯入的 normalizeProps。

延伸閱讀 ​

參考資料 ​