Keyframes

core:keyframes 插件管理 CSS @keyframes 動畫。它將 @keyframes 規則產生為前置樣式 CSS，並為 animationName 和 animation 屬性提供自動補齊。

運作原理

1. 關鍵影格定義在 rawConfigConfigured 期間從 config.keyframes.keyframes 收集。
2. 在 configureEngine 期間，每個定義會被解析並註冊：
   • 為 animationName 和 animation 新增自動補齊條目。
   • 具有 frames 的條目儲存於 engine.keyframes.store。
3. 前置樣式函式掃描原子化樣式中的動畫參照，以確定哪些關鍵影格實際被使用。
4. 只有已使用的關鍵影格（或具有 pruneUnused: false 的）才會輸出至 CSS。

設定

interface KeyframesConfig {
  /** Array of keyframe definitions. */
  keyframes: Keyframes[]
  /** Whether to prune unused keyframes from CSS output. @default true */
  pruneUnused?: boolean
}

關鍵影格定義格式

PikaCSS 支援三種定義關鍵影格的形式：

1. 字串形式

僅為自動補齊登錄關鍵影格名稱——不會產生 @keyframes 區塊。

'external-animation'

2. 元組形式

type TupleForm = [name: string, frames?: KeyframesProgress, autocomplete?: string[], pruneUnused?: boolean]

3. 物件形式

interface ObjectForm { name: string, frames?: KeyframesProgress, autocomplete?: string[], pruneUnused?: boolean }

KeyframesProgress

frames 物件將動畫停止點對應至 CSS 屬性：

• from — 0% 的別名
• to — 100% 的別名
• `${number}%` — 任意百分比停止點（例如 '25%'、'50%'）

完整範例

// pika.config.ts
import { defineEngineConfig } from '@pikacss/unplugin-pikacss'

export default defineEngineConfig({
	keyframes: {
		keyframes: [
			// Tuple form: [name, frames, autocomplete?, pruneUnused?]
			['fade-in', {
				from: { opacity: '0' },
				to: { opacity: '1' },
			}, ['fade-in 0.3s ease']],

			// Object form
			{
				name: 'slide-up',
				frames: {
					from: { transform: 'translateY(100%)' },
					to: { transform: 'translateY(0)' },
				},
				autocomplete: ['slide-up 0.5s ease-out'],
				pruneUnused: false, // always include in CSS output
			},

			// Percentage-based keyframes
			['bounce', {
				'0%': { transform: 'translateY(0)' },
				'50%': { transform: 'translateY(-20px)' },
				'100%': { transform: 'translateY(0)' },
			}],

			// String-only form: register an external animation name for autocomplete
			'external-animation',
		],
		// Prune keyframes not referenced in atomic styles (default: true)
		pruneUnused: true,
	},
})

與 pika() 搭配使用

在 animationName 或 animation 簡寫中參照已定義的關鍵影格：

const className = pika({
	animation: 'fade-in 0.3s ease',
})

產生的 CSS 輸出：

/* Preflight: @keyframes definitions */
@keyframes fade-in {
  from { opacity: 0; }
  to { opacity: 1; }
}
@keyframes slide-up {
  from { transform: translateY(100%); }
  to { transform: translateY(0); }
}

/* Atomic style generated by pika() */
.a { animation: fade-in 0.3s ease; }

清除未使用的關鍵影格

預設情況下，pruneUnused 為 true。只有名稱出現在 animationName 或 animation 原子化樣式值中的關鍵影格才會包含在 CSS 輸出中。

• 全域設定：keyframes.pruneUnused 套用於所有條目。
• 逐關鍵影格覆寫：在個別條目上設定 pruneUnused。
• 沒有 frames 的條目不會被輸出（它們只影響自動補齊）。

自動補齊

插件會自動註冊以下自動補齊值：

• animationName — 關鍵影格名稱（例如 fade-in）
• animation — 名稱後接空格（例如 fade-in ），以提示輸入持續時間和緩動
• 自訂的 autocomplete 字串也會作為 animation 建議新增

Engine API

插件可以用程式方式管理關鍵影格：

• engine.keyframes.store — 所有已註冊關鍵影格的 Map<string, ResolvedKeyframesConfig>
• engine.keyframes.add(...list) — 在執行階段新增關鍵影格定義（接受三種形式）

原始碼參考

• packages/core/src/internal/plugins/keyframes.ts

Next

• 繼續閱讀 Selectors