可用的 Hook

PikaCSS 外掛可以實作在引擎生命週期特定時機執行的 hook。

configureRawConfig

簽章

configureRawConfig?: (config: EngineConfig) => void | EngineConfig | Promise<void | EngineConfig>

時機

會在 createEngine() 期間、把原始設定解析為最終形式之前呼叫。外掛可以就地變動設定物件，或回傳一個新的。

範例

defineEnginePlugin({
  name: 'add-layer',
  configureRawConfig: (config) => {
    config.layers ??= {}
    config.layers['my-layer'] = 5
  },
})

rawConfigConfigured

簽章

rawConfigConfigured?: (config: EngineConfig) => void

時機

會在所有外掛的 configureRawConfig 都執行完之後呼叫。此時原始設定已經定案，這是一個用來讀取最終原始設定的通知型 hook，而不是用來做變動的。

範例

defineEnginePlugin({
  name: 'log-config',
  rawConfigConfigured: (config) => {
    console.log('Final raw config:', config)
  },
})

configureResolvedConfig

簽章

configureResolvedConfig?: (config: ResolvedEngineConfig) => void | ResolvedEngineConfig | Promise<void | ResolvedEngineConfig>

時機

會在原始設定解析成 ResolvedEngineConfig 之後呼叫。外掛可以調整解析後的值，例如 prefix、layer 或自動完成狀態。

範例

defineEnginePlugin({
  name: 'override-prefix',
  configureResolvedConfig: (config) => {
    config.prefix = 'custom-'
  },
})

configureEngine

簽章

configureEngine?: (engine: Engine) => void | Engine | Promise<void | Engine>

時機

會在引擎實例建構完成之後呼叫。外掛可以加入 preflight、註冊自動完成項目，或用自訂行為擴充引擎。

核心服務與 order: 'pre'

engine.selectors、engine.shortcuts、engine.keyframes 與 engine.variables 這些服務是由核心外掛自己的 configureEngine hook 掛上的。核心外掛會在預設順序群組中執行，因此帶有 order: 'pre' 的外掛會在這些服務存在之前就抵達 configureEngine，此時去存取它們會拋出錯誤；而因為 hook 錯誤會被捕捉並記錄下來，這個失敗很容易被忽略。當你需要這些服務時，請使用預設順序；或是把 'pre' 外掛限制在設定 hook，以及在建構時就存在的引擎方法（例如 addPreflight 與 addConfigDependency）。見 生命週期與注意事項。

範例

defineEnginePlugin({
  name: 'add-preflight',
  configureRawConfig: (config) => {
    // 註冊這個外掛要渲染到的 layer。指派給未宣告 layer 的 preflight
    // 會渲染成一個結尾的 `@layer` 區塊，而這個區塊不在 layer 順序宣告
    // 之中，於是它獲得了最高的層疊優先權，這與 base layer 應有的行為
    // 正好相反。
    config.layers ??= {}
    config.layers.base ??= 0
  },
  configureEngine: async (engine) => {
    engine.addPreflight({
      layer: 'base',
      preflight: '*, *::before, *::after { box-sizing: border-box; }',
    })
    engine.selectors.add(['@dark', 'html.dark $'])
    engine.shortcuts.add(['flex-center', { display: 'flex', alignItems: 'center', justifyContent: 'center' }])
    engine.keyframes.add(['fade-in', { from: { opacity: '0' }, to: { opacity: '1' } }])
    engine.variables.add({ '--color-primary': '#3b82f6' })
  },
})

預設的 layer 是 preflights（權重 1）與 utilities（權重 10）；把 base 註冊為權重 0，會讓它在 @layer 順序宣告中排在兩者之前。

transformSelectors

簽章

transformSelectors?: (selectors: string[]) => string[] | void | Promise<string[] | void>

時機

會在樣式擷取期間解析選擇器字串時呼叫。外掛可以改寫、展開或篩選選擇器的值。回傳 void 可讓目前的選擇器清單維持不變。

範例

defineEnginePlugin({
  name: 'dark-mode',
  transformSelectors: (selectors) => {
    return selectors.map(s =>
      s === '@dark' ? 'html.dark $' : s
    )
  },
})

transformStyleItems

簽章

transformStyleItems?: (items: StyleItem[]) => StyleItem[] | void | Promise<StyleItem[] | void>

時機

會在 engine.use() 中處理樣式項目時呼叫。上面的簽章為了可讀性使用了基礎匯出的 StyleItem 別名，但執行階段的 payload 是套用任何 PikaAugment.StyleItem 擴充之後、已解析且具備擴增感知的樣式項目清單。外掛可以在樣式項目被擷取成原子樣式之前，注入、移除或改寫它們。回傳 void 可讓目前的樣式項目維持不變。

範例

defineEnginePlugin({
  name: 'expand-shortcut',
  transformStyleItems: (items) => {
    return items.flatMap(item =>
      item === 'my-shortcut'
        ? [{ display: 'flex' }, { alignItems: 'center' }]
        : [item]
    )
  },
})

transformStyleDefinitions

簽章

transformStyleDefinitions?: (definitions: StyleDefinition[]) => StyleDefinition[] | void | Promise<StyleDefinition[] | void>

時機

會在樣式項目轉換成樣式定義之後呼叫。上面的簽章為了可讀性使用了基礎匯出的 StyleDefinition 別名，但執行階段的 payload 是套用任何 PikaAugment.StyleDefinition 擴充之後、已解析且具備擴增感知的定義清單。外掛可以在樣式定義被擷取成 atomic CSS 內容之前先轉換它們。回傳 void 可讓目前的樣式定義維持不變。

範例

defineEnginePlugin({
  name: 'auto-prefix',
  transformStyleDefinitions: (definitions) => {
    return definitions
  },
})

preflightUpdated

簽章

preflightUpdated?: () => void

時機

會在每次加入 preflight 或 CSS import 變更時呼叫。用這個 hook 來對 preflight 的變化做出反應。

範例

defineEnginePlugin({
  name: 'preflight-watcher',
  preflightUpdated: () => {
    console.log('Preflights changed')
  },
})

atomicStyleAdded

簽章

atomicStyleAdded?: (atomicStyle: AtomicStyle) => void

時機

每次有新的原子樣式註冊到引擎的 store 時呼叫。可以用它來做追蹤、分析或副作用。

範例

defineEnginePlugin({
  name: 'style-tracker',
  atomicStyleAdded: (atomicStyle) => {
    console.log(`New style: ${atomicStyle.id}`)
  },
})

autocompleteConfigUpdated

簽章

autocompleteConfigUpdated?: () => void

時機

會在自動完成設定變更時呼叫。用它來對新的自動完成項目做出反應。

範例

defineEnginePlugin({
  name: 'autocomplete-watcher',
  autocompleteConfigUpdated: () => {
    console.log('Autocomplete updated')
  },
})

下一步

• 型別擴增：擴充 PikaCSS 型別。
• 建立外掛：外掛結構與 defineEnginePlugin 輔助函式。
• Define 輔助函式：defineEngineConfig 與 defineEnginePlugin。