使用方式

在 JavaScript 物件裡用 CSS 屬性名稱撰寫樣式，PikaCSS 會在建置時期把它們轉換成 atomic CSS。

你的第一個樣式化元件

除了 安裝與設定 的步驟以外，不需要其他設定；直接在元件裡呼叫 pika 全域變數即可。不要匯入它：建置外掛會在建置時期替換每一次呼叫。

Vue

<!-- App.vue -->
<script setup lang="ts">
const buttonClass = pika({
  padding: '0.5rem 1rem',
  border: 'none',
  borderRadius: '8px',
  backgroundColor: '#3b82f6',
  color: 'white',
  cursor: 'pointer',
  '$:hover': {
    backgroundColor: '#2563eb',
  },
})
</script>

<template>
  <button :class="buttonClass">Click me</button>
</template>

React

// Button.tsx
const buttonClass = pika({
  padding: '0.5rem 1rem',
  border: 'none',
  borderRadius: '8px',
  backgroundColor: '#3b82f6',
  color: 'white',
  cursor: 'pointer',
  '$:hover': {
    backgroundColor: '#2563eb',
  },
})

export function Button() {
  return <button className={buttonClass}>Click me</button>
}

在建置時期，外掛會把 pika() 呼叫替換成一段由產生出來的 class 名稱組成的字串常值：

const buttonClass = 'pk-a pk-b pk-c pk-d pk-e pk-f pk-g'

轉換後的呼叫一律使用單引號字串常值，因此即使放在雙引號包住的 Vue 樣板屬性裡（例如 :class="pika({ ... })"），替換結果仍然有效。

每一條宣告在產生出來的 CSS（透過 import 'pika.css' 匯入）裡都會變成各自獨立的原子 class：

@layer utilities {
  .pk-a {
    padding: 0.5rem 1rem;
  }
  .pk-b {
    border: none;
  }
  .pk-c {
    border-radius: 8px;
  }
  .pk-d {
    background-color: #3b82f6;
  }
  .pk-e {
    color: white;
  }
  .pk-f {
    cursor: pointer;
  }
  .pk-g:hover {
    background-color: #2563eb;
  }
}

pika() 變體

PikaCSS 提供多種函式變體，對應不同的輸出格式與使用情境：

pika()

預設的函式。回傳一個以空格分隔的原子 class 名稱字串。

const className = pika({ color: 'red', fontSize: '16px' })
// → 'pk-a pk-b'

pika.str()

明確的字串變體。即使整合設定成 transformedFormat: 'array'，也一律回傳以空格分隔的 class 名稱字串；在預設的 transformedFormat: 'string' 下，行為與 pika() 完全相同。

const className = pika.str({ color: 'red' })
// → 'pk-a'

pika.arr()

陣列變體。回傳一個由個別 class 名稱字串組成的陣列，而不是單一串接好的字串。對於接受 class 名稱陣列的框架或工具很有用。

const classNames = pika.arr({ color: 'red', fontSize: '16px' })
// → ['pk-a', 'pk-b']

pikap()：預覽模式

供開發時使用的預覽變體。運作方式與 pika() 相同，但在你存檔時會觸發產生出來的 CSS 的即時預覽。提供 pikap()、pikap.str() 與 pikap.arr() 三種形式。

// 存檔即可看到產生出來的 CSS 預覽
const className = pikap({ color: 'red' })

預覽會出現在你的編輯器裡：每存檔一次 pikap() 呼叫，整合就會把一段含有渲染後 CSS 的 JSDoc overload 寫進產生出來的 pika.gen.ts，因此把游標移到該呼叫上時，型別提示裡就會顯示對應的 CSS。這需要啟用 tsCodegen（預設即為啟用），而且產生出來的檔案必須屬於你的 TypeScript program，見 產生的檔案。

提示

所有變體都接受相同的引數，差別只在回傳型別。ESLint 外掛會平等地驗證所有變體。

範例

基本的 CSS 屬性

傳入一個帶有標準 CSS 屬性的樣式定義物件：

輸入

const className = pika({
	color: 'red',
	fontSize: '16px',
})

輸出

@layer utilities {
  .pk-a {
    color: red;
  }
  .pk-b {
    font-size: 16px;
  }
}

偽類與偽元素

使用 $:hover、$:focus、$::before 等等來加入偽選擇器（pseudo selector）：

輸入

const className = pika({
	color: 'blue',
	'$:hover': {
		color: 'red',
	},
})

輸出

@layer utilities {
  .pk-a {
    color: blue;
  }
  .pk-b:hover {
    color: red;
  }
}

回應式樣式

使用 @media 查詢當作 key，對應回應式斷點：

輸入

const className = pika({
	fontSize: '14px',
	'@media (min-width: 768px)': {
		fontSize: '16px',
	},
	'@media (min-width: 1024px)': {
		fontSize: '18px',
	},
})

輸出

@layer utilities {
  .pk-a {
    font-size: 14px;
  }
  @media (min-width: 768px) {
    .pk-b {
      font-size: 16px;
    }
  }
  @media (min-width: 1024px) {
    .pk-c {
      font-size: 18px;
    }
  }
}

自訂選擇器

使用你在引擎設定中定義的自訂選擇器名稱。這個範例需要先註冊 @dark 選擇器：

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

export default defineEngineConfig({
  selectors: {
    definitions: [
      ['@dark', 'html.dark $'],
    ],
  },
})

輸入

const className = pika({
	color: 'black',
	'@dark': {
		color: 'white',
	},
})

輸出

@layer utilities {
  .pk-a {
    color: black;
  }
  html.dark .pk-b {
    color: white;
  }
}

Shortcut 參考

以字串引數的形式參考具名的 shortcut：

// 假設設定中已定義了一個名為 "flex-center" 的 shortcut
const className = pika('flex-center')

下一步

• 引擎設定：自訂引擎的行為。
• 客製化：定義自訂選擇器。