PikaCSS

繁體中文

English

繁體中文

English

外觀

第一個 Pika ​

在安裝建置插件並匯入 pika.css 之後，你就可以開始使用 pika(...) 撰寫樣式了。

前置作業 ​

請確保你已完成以下步驟：

  1. 安裝 @pikacss/unplugin-pikacss 並在打包器設定中註冊插件。
  2. 在應用程式進入點中匯入 pika.css。
ts
import { createApp } from 'vue'

import App from './App.vue'
// src/main.ts
import 'pika.css' // Import the generated CSS

createApp(App)
	.mount('#app')

最簡單的範例 ​

pika() 是一個全域函式，接受以 camelCase CSS 屬性組成的樣式物件，並回傳可繫結至元素的 class 名稱。

全域函式 — 無需匯入

pika() 由建置插件註冊為全域函式。你不需要匯入它 — 直接在任何原始碼檔案中使用即可。建置插件會透過靜態分析找到所有 pika() 呼叫，並在建置時期以產生的 class 名稱取代它們。pika.gen.ts 檔案為編輯器自動補齊提供 TypeScript 型別宣告（透過 declare global），但它不是你匯入來源的模組。

vue
<template>
	<button
		:class="pika({
			padding: '0.5rem 1rem',
			borderRadius: '0.5rem',
			backgroundColor: '#0ea5e9',
			color: 'white',
			border: 'none',
			cursor: 'pointer',
			fontSize: '1rem',
		})"
	>
		Hello PikaCSS
	</button>
</template>
ts
// In vanilla JS/TS, pika() is a global function
// available after setting up the build plugin.

const className = pika({
	padding: '0.5rem 1rem',
	borderRadius: '0.5rem',
	backgroundColor: '#0ea5e9',
	color: 'white',
	border: 'none',
	cursor: 'pointer',
	fontSize: '1rem',
})

// Use the returned class name(s) on any DOM element
document.querySelector('#my-button')!.className = className

建置時期的行為 ​

PikaCSS 完全在建置時期運作 — 零執行期負擔。當你執行建置時，PikaCSS 會：

  1. 掃描你的原始碼檔案，尋找 pika(...) 呼叫。
  2. 靜態分析樣式物件（引數必須在建置時期可分析）。
  3. 產生原子化 CSS 類別 — 每個 CSS 屬性值對成為各自的 class。
  4. 替換每個 pika(...) 呼叫為對應的 class 名稱字串。
  5. 寫入原子化 CSS 規則至產生的樣式表（pika.gen.css）。

原始碼與編譯輸出 ​

原始碼中的 pika() 呼叫：

vue
<template>
	<button
		:class="pika({
			padding: '0.5rem 1rem',
			borderRadius: '0.5rem',
			backgroundColor: '#0ea5e9',
			color: 'white',
			border: 'none',
			cursor: 'pointer',
			fontSize: '1rem',
		})"
	>
		Hello PikaCSS
	</button>
</template>

在輸出中被編譯為靜態 class 名稱：

html
<!-- After build, pika() calls are replaced with class name strings -->
<button class="a b c d e f g">
  Hello PikaCSS
</button>

而產生的 pika.gen.css 每個屬性包含一個原子化規則：

css
/* Each CSS property becomes its own atomic class */
.a {
  padding: 0.5rem 1rem;
}
.b {
  border-radius: 0.5rem;
}
.c {
  background-color: #0ea5e9;
}
.d {
  color: white;
}
.e {
  border: none;
}
.f {
  cursor: pointer;
}
.g {
  font-size: 1rem;
}

為什麼使用原子化 CSS？

每個 CSS 屬性值對都被提取為單一可重複使用的 class。如果另一個元素也使用 color: 'white'，它將共用相同的 .d class。這種去重複化機制讓樣式表隨著應用程式成長而保持精簡。

巢狀選擇器 ​

樣式物件支援用於偽類別、媒體查詢和自訂選擇器的巢狀語法。將它們作為樣式物件的鍵進行巢狀 — PikaCSS 會將每個巢狀屬性編譯為各自的原子化 class。

vue
<template>
	<button
		:class="pika({
			'padding': '0.5em 1em',
			'borderRadius': '0.25em',
			'border': 'none',
			'backgroundColor': '#0ea5e9',
			'color': 'white',
			'cursor': 'pointer',
			'transition': 'transform 0.2s ease',

			':hover': {
				transform: 'scale(1.05)',
			},

			':active': {
				transform: 'scale(0.95)',
			},
		})"
	>
		Hover me
	</button>
</template>

這將產生以下原子化 CSS：

css
/* Base styles become atomic classes */
.a {
  padding: 0.5em 1em;
}
.b {
  border-radius: 0.25em;
}
.c {
  border: none;
}
.d {
  background-color: #0ea5e9;
}
.e {
  color: white;
}
.f {
  cursor: pointer;
}
.g {
  transition: transform 0.2s ease;
}

/* Pseudo-selectors also become atomic classes */
.h:hover {
  transform: scale(1.05);
}
.i:active {
  transform: scale(0.95);
}

多個引數 ​

pika() 接受多個引數（每個都是 StyleItem）。一個引數可以是樣式物件或字串（用於設定中定義的捷徑）。它們會按順序合併：

vue
<template>
	<!-- pika() accepts multiple arguments (StyleItem[]) -->
	<!-- Each argument can be a string (shortcut) or a style object -->
	<div
		:class="pika(
			'my-shortcut',
			{
				fontSize: '1.5rem',
				color: '#333',
			},
		)"
	>
		Combining shortcuts and inline styles
	</div>
</template>

輸出格式變體 ​

預設情況下，pika() 回傳以空格分隔的 class 名稱字串（例如 "a b c"）。它也提供不同輸出格式的變體：

ts
// pika() - Default output format (configured by integration, usually string)
const classes = pika({ color: 'red', fontSize: '1rem' })
// => "a b" (string of space-separated class names)

// pika.str() - Force string output
const str = pika.str({ color: 'red', fontSize: '1rem' })
// => "a b"

// pika.arr() - Force array output
const arr = pika.arr({ color: 'red', fontSize: '1rem' })
// => ["a", "b"]
變體回傳型別使用情境
pika()已設定值預設（通常為 string）
pika.str()string強制使用空格分隔的字串
pika.arr()string[]強制使用 class 名稱陣列

使用 pikap 進行 IDE 預覽 ​

pikap 是 pika 的預覽變體，具有相同的 API，但在 IDE 中直接提供 CSS 預覽提示。在開發期間使用 pikap 可以在不執行建置的情況下查看產生的 CSS。

設定（選用） ​

PikaCSS 可以在零設定情況下運作，但你可以建立 pika.config.ts（或 .js、.mjs、.mts、.cjs、.cts）來自訂行為。使用 defineEngineConfig() 輔助函式以獲得完整的 TypeScript 自動補齊：

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

export default defineEngineConfig({
	// Prefix for generated class names (default: '')
	prefix: '',

	// Selector pattern, '%' is replaced with the class ID (default: '.%')
	defaultSelector: '.%',

	// Plugins to extend functionality
	plugins: [],

	// Global CSS injected before atomic styles
	preflights: [],
})

設定檔會由插件自動偵測。所有可用選項請參閱設定。

為什麼這樣設計 ​

你保留了 CSS-in-JS 的撰寫體驗 — 標準 CSS 屬性、TypeScript 自動補齊、物件組合 — 同時輸出靜態 CSS，無任何執行期樣式產生的負擔。

下一步 ​