抽出

UnoCSSは、コードベースからユーティリティの使用を検索し、オンデマンドで対応するCSSを生成することで動作します。このプロセスを抽出と呼びます。

コンテンツソース

UnoCSSは複数のソースからユーティリティの使用を抽出することをサポートしています：

• パイプライン - ビルドツールのパイプラインから直接抽出
• ファイルシステム - ファイルの読み取りと監視によるファイルシステムからの抽出
• インライン - インラインのプレーンテキストからの抽出

異なるソースからのユーティリティの使用は、マージされて最終的なCSSが生成されます。

ビルドツールパイプラインからの抽出

これはViteとWebpackの統合でサポートされています。

UnoCSSはビルドツールのパイプラインを通過するコンテンツを読み取り、そこからユーティリティの使用を抽出します。これは最も効率的で正確な抽出方法です。なぜなら、アプリで実際に使用されている使用のみをスマートに抽出し、抽出中に追加のファイルI/Oを行わないためです。

デフォルトでは、UnoCSSはビルドパイプライン内の.jsx、.tsx、.vue、.md、.html、.svelte、.astro拡張子を持つファイルからユーティリティの使用を抽出し、オンデマンドで適切なCSSを生成します。.jsと.tsファイルはデフォルトでは含まれません。

これらを設定するには、uno.config.tsを更新できます：

export default defineConfig({
  content: {
    pipeline: {
      include: [
        // デフォルト
        /\.(vue|svelte|[jt]sx|mdx?|astro|elm|php|phtml|html)($|\?)/,
        // js/tsファイルを含める
        'src/**/*.{js,ts}',
      ],
      // ファイルを除外
      // exclude: []
    },
  },
})

また、UnoCSSにスキャンしてほしいファイルの任意の場所に@unocss-includeマジックコメントを追加することもできます。*.jsまたは*.tsファイルをスキャンする必要がある場合は、設定に追加してすべてのjs/tsファイルをスキャン対象として含めてください。

// ./some-utils.js

// `.js`ファイルはデフォルトでは含まれないため、
// 以下のコメントはUnoCSSにこのファイルを強制的にスキャンするように指示します。
// @unocss-include
export const classes = {
  active: 'bg-primary text-white',
  inactive: 'bg-gray-200 text-gray-500',
}

同様に、@unocss-ignoreを追加して、ファイル全体のスキャンと変換をバイパスすることもできます。

UnoCSSに抽出ファイル内のコードブロックをスキップさせたい場合は、@unocss-skip-startと@unocss-skip-endをペアで使用できます。効果を発揮するには必ずペアで使用する必要があります。

<p class="text-green text-xl">Green Large</p>

<!-- @unocss-skip-start -->
<!-- `text-red`は抽出されません -->
<p class="text-red">Red</p>
<!-- @unocss-skip-end -->

ファイルシステムからの抽出

ビルドツールのパイプラインにアクセスできない統合（例えば、PostCSSプラグイン）を使用している場合や、コードがパイプラインを通過しないバックエンドフレームワークと統合している場合は、抽出するファイルを手動で指定できます。

export default defineConfig({
  content: {
    filesystem: [
      'src/**/*.php',
      'public/*.html',
    ],
  },
})

マッチしたファイルはファイルシステムから直接読み取られ、開発モードで変更が監視されます。

インラインテキストからの抽出

さらに、他の場所から取得した可能性のあるインラインテキストからユーティリティの使用を抽出することもできます。

コンテンツを返す非同期関数を渡すこともできます。ただし、この関数はビルド時に1回だけ呼び出されることに注意してください。

export default defineConfig({
  content: {
    inline: [
      // プレーンテキスト
      '<div class="p-4 text-red">Some text</div>',
      // 非同期ゲッター
      async () => {
        const response = await fetch('https://example.com')
        return response.text()
      },
    ],
  },
})

制限事項

UnoCSSはビルド時に動作するため、静的に提示されたユーティリティのみが生成され、アプリに配信されます。動的に使用されるユーティリティや、実行時に外部リソースから取得されるユーティリティは検出または適用されない可能性があります。

セーフリスト

時には、以下のような動的な連結を使用したい場合があります：

<div class="p-${size}"></div>
<!-- これは動作しません！ -->

UnoCSSが静的抽出を使用してビルド時に動作するという事実により、コンパイル時にすべてのユーティリティの組み合わせを知ることは不可能です。そのため、safelistオプションを設定できます。

safelist: 'p-1 p-2 p-3 p-4'.split(' ')

対応するCSSは常に生成されます：

.p-1 { padding: 0.25rem; }
.p-2 { padding: 0.5rem; }
.p-3 { padding: 0.75rem; }
.p-4 { padding: 1rem; }

または、より柔軟に：

safelist: [
  ...Array.from({ length: 4 }, (_, i) => `p-${i + 1}`),
]

実行時に真の動的生成を求めている場合は、@unocss/runtimeパッケージを確認してください。

静的リストの組み合わせ

動的に構築されたユーティリティの制限を回避する別の方法として、すべての組み合わせを静的にリストするオブジェクトを使用できます。例えば、以下のようなものが必要な場合：

<div class="text-${color} border-${color}"></div>
<!-- これは動作しません！ -->

使用したいcolorの可能な値を知っていると仮定して、すべての組み合わせをリストするオブジェクトを作成できます：

// これらは静的であるため、UnoCSSはビルド時にそれらを抽出できます
const classes = {
  red: 'text-red border-red',
  green: 'text-green border-green',
  blue: 'text-blue border-blue',
}

そして、テンプレートで使用します：

<div class="${classes[color]}"></div>

ブロックリスト

safelistと同様に、blocklistを設定して、一部のユーティリティが生成されないようにすることもできます。これは抽出の誤検出を除外するのに役立ちます。safelistとは異なり、blocklistは完全一致のための文字列とパターンマッチのための正規表現の両方を受け入れます。

blocklist: [
  'p-1',
  /^p-[2-4]$/,
]

これにより、p-1とp-2、p-3、p-4が生成から除外されます。