PikaCSS

繁體中文

English

繁體中文

English

外觀

設定 ​

PikaCSS 透過兩個層次進行設定：

  1. Engine Config — 控制 CSS 引擎（前綴、選擇器、變數、關鍵影格等）
  2. Build Plugin Options — 控制建置整合（檔案掃描、程式碼產生、轉換格式）

設定檔 ​

PikaCSS 會自動偵測符合以下模式的設定檔：

**/pika.config.{js,ts,mjs,mts,cjs,cts}
**/pikacss.config.{js,ts,mjs,mts,cjs,cts}

使用 defineEngineConfig() 包裝你的設定，以獲得型別安全的 IntelliSense。這是從 @pikacss/core 匯出的恆等函式：

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

export default defineEngineConfig({
	prefix: 'pika-',
	defaultSelector: '.%',
	preflights: [
		':root { --app-radius: 12px; }',
	],
	plugins: [],
})

Engine Config ​

plugins ​

  • 型別： EnginePlugin[]
  • 預設值： []

註冊插件以擴展 PikaCSS 的功能。核心內建插件（important、variables、keyframes、selectors、shortcuts）始終會自動載入——你只需在此新增外部插件。

ts
import { defineEngineConfig } from '@pikacss/core'
import { icons } from '@pikacss/plugin-icons'
import { reset } from '@pikacss/plugin-reset'
import { typography } from '@pikacss/plugin-typography'

export default defineEngineConfig({
	plugins: [
		reset(),
		icons(),
		typography(),
	],
})

prefix ​

  • 型別： string
  • 預設值： ''

附加在每個產生的原子化樣式 ID 前面的前綴。適合用來避免與其他 CSS 框架的命名衝突。

ts
import { defineEngineConfig } from '@pikacss/core'

export default defineEngineConfig({
	// No prefix (default): generated IDs are "a", "b", "c", ...
	prefix: '',
})

export const withPrefix = defineEngineConfig({
	// With prefix: generated IDs are "pika-a", "pika-b", "pika-c", ...
	prefix: 'pika-',
})

defaultSelector ​

  • 型別： string
  • 預設值： '.%'

用於產生原子化樣式的選擇器範本。% 字元是佔位符（ATOMIC_STYLE_ID_PLACEHOLDER），在渲染時會被實際的原子化樣式 ID 取代。

ts
import { defineEngineConfig } from '@pikacss/core'

// Default: use CSS class selector
export const classSelector = defineEngineConfig({
	defaultSelector: '.%', // <div class="a b c">
})

// Use attribute selector instead
export const attrSelector = defineEngineConfig({
	defaultSelector: '[data-pika~="%"]', // <div data-pika="a b c">
})

preflights ​

  • 型別： Preflight[]
  • 預設值： []

在原子化樣式之前注入的全域 CSS。每個項目可以是：

  1. CSS 字串 — 直接注入
  2. 前置樣式定義物件 — CSS-in-JS 物件（如 { ':root': { fontSize: '16px' } }）
  3. 函式 (engine, isFormatted) => string | PreflightDefinition — 使用引擎實例動態產生 CSS
ts
import { defineEngineConfig } from '@pikacss/core'

export default defineEngineConfig({
	preflights: [
		// 1. Static CSS string
		':root { --color-brand: #ff007f; }',

		// 2. Preflight definition object (like CSS-in-JS)
		{
			':root': {
				fontSize: '16px',
				lineHeight: '1.5',
			},
			'*, *::before, *::after': {
				boxSizing: 'border-box',
			},
		},

		// 3. Dynamic function — receives the engine instance
		(engine) => {
			const prefix = engine.config.prefix
			return `/* Engine prefix: ${prefix} */`
		},

		// 4. Function returning a preflight definition object
		engine => ({
			body: {
				margin: '0',
				padding: '0',
			},
		}),
	],
})

Core Plugin 設定 ​

這些欄位是透過 模組擴增 由 PikaCSS 核心插件新增至 EngineConfig 的。它們始終可用，因為核心插件會在 createEngine() 中自動載入。

important ​

  • 型別： { default?: boolean }
  • 預設值： { default: false }

控制是否在所有產生的 CSS 宣告後附加 !important。個別樣式可透過 __important 屬性進行覆寫。

ts
import { defineEngineConfig } from '@pikacss/core'

export default defineEngineConfig({
	important: {
		// When true, all generated atomic styles will have `!important` appended.
		// Can be overridden per style with `__important: false`.
		default: true,
	},
})

variables ​

  • 型別： { variables: Arrayable<VariablesDefinition>, pruneUnused?: boolean, safeList?: string[] }
  • 預設值： undefined

定義 CSS 自訂屬性（變數），支援作用域選擇器、自動補齊設定及未使用項目清除。

子選項型別預設值說明
variablesArrayable<VariablesDefinition>（必填）變數定義。可為單一物件或物件陣列（依序合併）。
pruneUnusedbooleantrue從最終 CSS 中移除未使用的變數。
safeListstring[][]無論是否使用都始終包含的變數。

每個變數的值可以是：

  • 字串／數字 — CSS 值（預設渲染於 :root 下）
  • null — 僅供自動補齊使用，不產生 CSS 輸出
  • VariableObject — 對值、自動補齊行為及清除進行精細控制
ts
import { defineEngineConfig } from '@pikacss/core'

export default defineEngineConfig({
	variables: {
		variables: {
			// Simple variable (rendered under :root by default)
			'--color-bg': '#ffffff',
			'--color-text': '#1a1a1a',

			// Variable with null value (autocomplete only, no CSS output)
			'--external-var': null,

			// Scoped variables under a selector
			'[data-theme="dark"]': {
				'--color-bg': '#1a1a1a',
				'--color-text': '#ffffff',
			},

			// Variable with advanced options
			'--spacing-unit': {
				value: '4px',
				autocomplete: {
					asValueOf: ['margin', 'padding', 'gap'],
					asProperty: true,
				},
				pruneUnused: false, // Always include in output
			},
		},

		// Whether to remove unused variables from the final CSS
		pruneUnused: true,

		// Variables that are always included regardless of usage
		safeList: ['--color-bg', '--color-text'],
	},
})

你也可以傳入一個變數定義陣列，依序合併：

ts
import { defineEngineConfig } from '@pikacss/core'

export default defineEngineConfig({
	variables: {
		// Pass an array of variable definitions (merged in order)
		variables: [
			{
				'--color-primary': '#3b82f6',
				'--color-secondary': '#8b5cf6',
			},
			{
				'@media (prefers-color-scheme: dark)': {
					'--color-primary': '#60a5fa',
					'--color-secondary': '#a78bfa',
				},
			},
		],
	},
})

keyframes ​

  • 型別： { keyframes: Keyframes[], pruneUnused?: boolean }
  • 預設值： undefined

定義 CSS @keyframes 動畫，包含影格定義與自動補齊建議。

子選項型別預設值說明
keyframesKeyframes[]（必填）關鍵影格定義。
pruneUnusedbooleantrue從最終 CSS 中移除未使用的關鍵影格。

每個關鍵影格可定義為：

  • 字串 — 僅動畫名稱（供自動補齊使用，不產生影格）
  • 元組 [name, frames?, autocomplete?, pruneUnused?]
  • 物件 { name, frames?, autocomplete?, pruneUnused? }
ts
import { defineEngineConfig } from '@pikacss/core'

export default defineEngineConfig({
	keyframes: {
		keyframes: [
			// 1. String only — name for autocomplete, no frames defined
			'external-animation',

			// 2. Tuple form: [name, frames?, autocomplete?, pruneUnused?]
			['fade-in', {
				from: { opacity: '0' },
				to: { opacity: '1' },
			}, ['fade-in 0.3s ease']],

			// 3. 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 output
			},

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

		// Whether to prune unused keyframes from the final CSS
		pruneUnused: true,
	},
})

selectors ​

  • 型別： { selectors: Selector[] }
  • 預設值： undefined

定義可在樣式定義中作為鍵使用的自訂選擇器。替換值中的 $ 代表目前元素的選擇器。

選擇器形式說明
string僅供自動補齊使用
[name, replacement]靜態對應
[pattern, handler, autocomplete?]動態（基於正規表示式）對應
{ selector, value }物件形式（靜態）
{ selector, value, autocomplete? }物件形式（動態）
ts
import { defineEngineConfig } from '@pikacss/core'

export default defineEngineConfig({
	selectors: {
		selectors: [
			// 1. Static selector: [name, replacement]
			['hover', '$:hover'],
			['focus', '$:focus'],
			['dark', '[data-theme="dark"] $'],

			// 2. Dynamic selector: [pattern, handler, autocomplete?]
			[/^screen-(\d+)$/, m => `@media (min-width: ${m[1]}px)`, [
				'screen-640',
				'screen-768',
				'screen-1024',
				'screen-1280',
			]],

			// 3. Object form (static)
			{
				selector: 'first-child',
				value: '$:first-child',
			},

			// 4. Object form (dynamic)
			{
				selector: /^aria-(\w+)$/,
				value: m => `$[aria-${m[1]}="true"]`,
				autocomplete: ['aria-expanded', 'aria-selected', 'aria-disabled'],
			},
		],
	},
})

shortcuts ​

  • 型別： { shortcuts: Shortcut[] }
  • 預設值： undefined

定義可重複使用的樣式捷徑——樣式屬性或其他捷徑的具名組合。

捷徑形式說明
string僅供自動補齊使用
[name, styleDefinition]靜態對應
[pattern, handler, autocomplete?]動態（基於正規表示式）對應
{ shortcut, value }物件形式（靜態）
{ shortcut, value, autocomplete? }物件形式（動態）
ts
import { defineEngineConfig } from '@pikacss/core'

export default defineEngineConfig({
	shortcuts: {
		shortcuts: [
			// 1. Static shortcut: [name, styleDefinition]
			['flex-center', {
				display: 'flex',
				alignItems: 'center',
				justifyContent: 'center',
			}],

			// 2. Static shortcut with multiple values (array)
			['btn-base', [
				{ display: 'inline-flex', alignItems: 'center', justifyContent: 'center' },
				{ padding: '8px 16px', borderRadius: '4px' },
			]],

			// 3. Dynamic shortcut: [pattern, handler, autocomplete?]
			[/^m-(\d+)$/, m => ({ margin: `${m[1]}px` }), [
				'm-0',
				'm-4',
				'm-8',
				'm-16',
			]],

			// 4. Object form (static)
			{
				shortcut: 'sr-only',
				value: {
					position: 'absolute',
					width: '1px',
					height: '1px',
					overflow: 'hidden',
					clip: 'rect(0, 0, 0, 0)',
					whiteSpace: 'nowrap',
					borderWidth: '0',
				},
			},

			// 5. Object form (dynamic)
			{
				shortcut: /^p-(\d+)$/,
				value: m => ({ padding: `${m[1]}px` }),
				autocomplete: ['p-0', 'p-4', 'p-8', 'p-16'],
			},
		],
	},
})

Build Plugin Options（PluginOptions） ​

這些選項傳遞給建置插件（例如在你的 Vite／Webpack／Rollup 設定中的 pikacss()）。它們控制 PikaCSS 如何與你的建置工具整合。

選項型別預設值說明
scan{ include?, exclude? }見下方掃描 pika() 呼叫的檔案模式
configEngineConfig | stringundefined行內引擎設定或設定檔路徑
autoCreateConfigbooleantrue若無設定檔則自動建立
fnNamestring'pika'在原始碼中偵測的函式名稱
transformedFormat'string' | 'array' | 'inline''string'產生的 class 名稱輸出格式
tsCodegenboolean | stringtrueTypeScript 程式碼產生檔路徑（true = 'pika.gen.ts'，false = 停用）
cssCodegentrue | stringtrueCSS 程式碼產生檔路徑（true = 'pika.gen.css'）

scan ​

預設值：

  • include：['**/*.{js,ts,jsx,tsx,vue}']
  • exclude：['node_modules/**', 'dist/**']

transformedFormat ​

控制 pika() 呼叫在建置時期的轉換方式：

  • 'string' — "a b c"（以空格分隔的字串）
  • 'array' — ['a', 'b', 'c']（class 名稱陣列）
  • 'inline' — 行內樣式物件格式
ts
// vite.config.ts
import pikacss from '@pikacss/unplugin-pikacss/vite'
import { defineConfig } from 'vite'

export default defineConfig({
	plugins: [
		pikacss({
			// File scanning patterns
			scan: {
				include: ['src/**/*.{ts,tsx,vue}'],
				exclude: ['node_modules/**', 'dist/**'],
			},

			// Engine config or path to config file
			config: './pika.config.ts',

			// Auto-create config file if missing
			autoCreateConfig: true,

			// Name of the pika function in source code
			fnName: 'pika',

			// Output format: 'string' | 'array' | 'inline'
			transformedFormat: 'string',

			// TypeScript codegen file (true = 'pika.gen.ts')
			tsCodegen: true,

			// CSS codegen file (true = 'pika.gen.css')
			cssCodegen: true,
		}),
	],
})

完整範例 ​

使用所有可用選項的完整設定檔：

ts
// pika.config.ts
import { defineEngineConfig } from '@pikacss/core'
import { icons } from '@pikacss/plugin-icons'
import { reset } from '@pikacss/plugin-reset'

export default defineEngineConfig({
	plugins: [
		reset(),
		icons(),
	],

	prefix: 'pk-',
	defaultSelector: '.%',

	preflights: [
		'*, *::before, *::after { box-sizing: border-box; }',
	],

	important: {
		default: false,
	},

	variables: {
		variables: {
			'--color-bg': '#ffffff',
			'--color-text': '#1a1a1a',
			'[data-theme="dark"]': {
				'--color-bg': '#1a1a1a',
				'--color-text': '#ffffff',
			},
		},
		pruneUnused: true,
		safeList: ['--color-bg', '--color-text'],
	},

	keyframes: {
		keyframes: [
			['fade-in', {
				from: { opacity: '0' },
				to: { opacity: '1' },
			}, ['fade-in 0.3s ease']],
		],
		pruneUnused: true,
	},

	selectors: {
		selectors: [
			['hover', '$:hover'],
			['focus', '$:focus'],
			['dark', '[data-theme="dark"] $'],
		],
	},

	shortcuts: {
		shortcuts: [
			['flex-center', {
				display: 'flex',
				alignItems: 'center',
				justifyContent: 'center',
			}],
		],
	},
})

Next ​