Extracting

抽出

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

コンテンツソース

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

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

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

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

これは、ViteおよびWebpackの統合でサポートされています。

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

デフォルトでは、UnoCSSはビルドパイプライン内の.jsx、.tsx、.vue、.md、.html、.svelte、.astro拡張子のファイルからユーティリティの使用を抽出し、必要に応じて適切なCSSを生成します。.jsおよび.tsファイルはデフォルトでは含まれていません。

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

uno.config.ts

export default defineConfig({
  content: {
    pipeline: {
      include: [
        // デフォルト
        /\.(vue|svelte|[jt]sx|vine.ts|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プラグイン）を使用している場合や、コードがパイプラインを通過しないバックエンドフレームワークと統合している場合は、抽出するファイルを手動で指定できます。

uno.config.ts

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

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

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

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

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

uno.config.ts

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オプションを設定できます。

uno.config.ts

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; }

または、より柔軟に：

uno.config.ts

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は正確な一致のための文字列とパターン一致のための正規表現の両方を受け入れます。

uno.config.ts

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

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