Tailwind CSS - 外掛

上一頁
下一頁

Tailwind CSS 外掛允許使用可重用的第三方外掛擴充套件 Tailwind。外掛允許你使用 JavaScript 而不是常規 CSS 程式碼向 Tailwind 新增新的樣式。

要建立你的第一個外掛，你需要做兩件事

  • 匯入外掛函式：這是透過在你的 Tailwind CSS 配置檔案中新增 `import { plugin } from 'tailwindcss/plugin'` 來完成的。
  • 將你的外掛新增到 plugins 陣列： 你可以透過在你的 plugins 陣列中呼叫 plugin 函式來實現這一點。在 plugin 函式內部，你將編寫你的外掛程式碼。
const plugin = require('tailwindcss/plugin')

module.exports = {
    plugins: [
    plugin(function({ addUtilities, addComponents, e, config }) {
        // Add your custom styles here
    }),
    ]
}

外掛函式的設計非常靈活。它們接受一個單一的物件作為輸入，可以將其分解成多個輔助函式以簡化處理。

  • addUtilities() 用於註冊新的靜態實用程式樣式。
  • matchUtilities() 用於註冊新的動態實用程式樣式。
  • addComponents() 用於註冊新的靜態元件樣式。
  • matchComponents() 用於註冊新的動態元件樣式。
  • addBase() 用於註冊新的基礎樣式。
  • addVariant() 用於註冊自定義靜態變體。
  • matchVariant() 用於註冊自定義動態變體。
  • theme() 用於查詢使用者主題配置中的值。
  • config() 用於查詢使用者 Tailwind 配置中的值。
  • corePlugins() 用於檢查核心外掛是否已啟用。
  • e() 用於手動轉義要在類名中使用的字串。

官方外掛

Tailwind CSS 有幾個官方外掛，用於核心庫中尚未包含的功能。可以使用 npm 安裝這些外掛，然後將其新增到你的 `tailwind.config.js` 檔案中。

/** @type {import('tailwindcss').Config} */
module.exports = {
  // ...
  plugins: [
    require('@tailwindcss/typography'),
    require('@tailwindcss/forms'),
    require('@tailwindcss/aspect-ratio'),
    require('@tailwindcss/container-queries'),
  ]
}

排版

Tailwind CSS 排版外掛簡化了內容文字的樣式設定。它提供預構建的類，可為來自 Markdown 或 CMS 資料庫等地方的內容新增時尚的排版，從而無需太多努力即可使你的文字看起來不錯。

<article class="prose lg:prose-xl">
  <h1>
    Garlic bread with cheese: 
    What the science tells us
  </h1>
  <p>
    For years parents have espoused the health
    benefits of eating garlic bread with cheese to their
    children, with the food earning such an iconic status
    in our culture that kids will often dress
    up as warm, cheesy loaf for Halloween.
  </p>
  <p>
    But a recent study shows that the celebrated appetizer
    may be linked to a series of rabies cases
    springing up around the country.
  </p>
  <!-- ... -->
</article>

表單

@tailwindcss/forms 外掛透過提供一組預設樣式來簡化表單樣式設定。這使得建立外觀一致的表單更加簡單。

寬高比

@tailwindcss/aspect-ratio 外掛提供了一種方法，可以在不支援此功能的較舊瀏覽器中設定元素的寬高比。它添加了新的實用程式類，例如 `aspect-w-*` 和 `aspect-h-*`，用於控制元素的寬度和高度比例。

容器查詢

"@tailwindcss/container-queries" 外掛允許你使用 "@container" 指令根據其父容器的大小來設定元素的樣式。

<div class="@container">
  <div class="@lg:text-sky-400">
     <!-- ... -->
  </div>
</div>

新增實用程式

addUtilities 和 matchUtilities 函式允許你向 Tailwind CSS 新增自定義樣式，就像預設樣式一樣。但是，只有當你實際在專案中使用這些自定義樣式時，它們才會包含在最終 CSS 中。

靜態實用程式

`addUtilities` 函式用於新增簡單的、不變的樣式（實用程式），不支援使用者提供的值。

const plugin = require('tailwindcss/plugin')

module.exports = {
  plugins: [
    plugin(function({ addUtilities }) {
      addUtilities({
        '.content-auto': {
          'content-visibility': 'auto',
        },
        '.content-hidden': {
          'content-visibility': 'hidden',
        },
        '.content-visible': {
          'content-visibility': 'visible',
        },
      })
    })
  ]
}

動態實用程式

`matchUtilities` 函式允許你建立使用主題配置中值的 CSS 實用程式類。

const plugin = require('tailwindcss/plugin')

module.exports = {
    theme: {
    tabSize: {
        1: '1',
        2: '2',
        4: '4',
        8: '8',
    }
    },
    plugins: [
    plugin(function({ matchUtilities, theme }) {
        matchUtilities(
        {
            tab: (value) => ({
            tabSize: value
            }),
        },
        { values: theme('tabSize') }
        )
    })
    ]
}

即使在你的主題中沒有定義，你也可以使用方括號在你的實用程式中使用自定義值。

<div class="tab-[13]">
   <!-- ... -->
</div>

字首和重要性

外掛的工具會自動使用使用者的設定，例如“字首”和“重要”選項。

這意味著，給定此 Tailwind 配置

/** @type {import('tailwindcss').Config} */
module.exports = {
    prefix: 'tw-',
    important: true,
    // ...
}

上面的示例外掛將生成以下 CSS

.tw-content-auto {
    content-visibility: auto !important;
    }
    .tw-content-hidden {
    content-visibility: hidden !important;
    }
    .tw-content-visible {
    content-visibility: visible !important;
    }

與修飾符一起使用

使用 `addUtilities` 新增的任何自定義實用程式都可以與其他實用程式類（如 `hover`、`focus` 等）組合使用。

<div class="content-auto lg:content-visible">
  <!-- ... -->
</div>

提供預設值

實用程式外掛可以透過向外掛函式的第二個引數提供配置物件來設定預設值。這些預設值的行為類似於原始預設設定，使用者可以更改或新增它們。

const plugin = require('tailwindcss/plugin')

module.exports = plugin(function({ matchUtilities, theme }) {
    matchUtilities(
    {
        tab: (value) => ({
        tabSize: value
        }),
    },
    { values: theme('tabSize') }
    )
}, {
    theme: {
    tabSize: {
        1: '1',
        2: '2',
        4: '4',
        8: '8',
    }
    }
})

新增元件

Tailwind CSS 中的 `addComponents` 函式允許你建立自定義預先設計的元件，例如按鈕、表單、警告等等。這些元件就像你可以設計中使用的構建塊，如果需要，你可以使用其他 Tailwind 類修改它們的外觀。

要從外掛新增新的元件樣式，請呼叫 `addComponents`，並使用 CSS-in-JS 語法傳入你的樣式。

const plugin = require('tailwindcss/plugin')

module.exports = {
  plugins: [
    plugin(function({ addComponents }) {
      addComponents({
        '.btn': {
          padding: '.5rem 1rem',
          borderRadius: '.25rem',
          fontWeight: '600',
        },
        '.btn-blue': {
          backgroundColor: '#3490dc',
          color: '#fff',
          '&:hover': {
            backgroundColor: '#2779bd'
          },
        },
        '.btn-red': {
          backgroundColor: '#e3342f',
          color: '#fff',
          '&:hover': {
            backgroundColor: '#cc1f1a'
          },
        },
      })
    })
  ]
}

字首和重要性

預設情況下，元件類遵循使用者的 `prefix` 首選項，但忽略它們的“重要”首選項。

這意味著，給定此 Tailwind 配置

/** @type {import('tailwindcss').Config} */
module.exports = {
  prefix: 'tw-',
  important: true,
  // ...
}

上面的示例外掛將生成以下 CSS

.tw-btn {
    padding: .5rem 1rem;
    border-radius: .25rem;
    font-weight: 600;
    }
    .tw-btn-blue {
    background-color: #3490dc;
    color: #fff;
    }
    .tw-btn-blue:hover {
    background-color: #2779bd;
    }
    .tw-btn-red {
    background-color: #e3342f;
    color: #fff;
    }
    .tw-btn-red:hover {
    background-color: #cc1f1a;
    }

通常最好不要使元件宣告為重要。但是，如果你絕對需要這樣做，你可以手動新增 `!important` 關鍵字。

const plugin = require('tailwindcss/plugin')

module.exports = {
  plugins: [
    plugin(function({ addComponents }) {
      addComponents({
        '.btn': {
          padding: '.5rem 1rem !important',
          borderRadius: '.25rem !important',
          fontWeight: '600 !important',
        },
        // ...
      })
    })
  ]
}

預設情況下，選擇器中的所有類都將新增字首，因此，如果你新增更復雜的樣式，例如：

const plugin = require('tailwindcss/plugin')

module.exports = {
    prefix: 'tw-',
    plugins: [
    plugin(function({ addComponents }) {
        const components = {
        // ...
        '.navbar-inverse a.nav-link': {
            color: '#fff',
        }
        }

        addComponents(components)
    })
    ]
}

將生成以下 CSS：

.tw-navbar-inverse a.tw-nav-link {
    color: #fff;
}

與修飾符一起使用

使用 `addUtilities` 新增的任何自定義實用程式都可以與其他實用程式類（如 `hover`、`focus` 等）組合使用。

<div class="btn md:btn-lg">
  <!-- ... -->
</div>

新增基礎樣式

Tailwind CSS 中的 `addBase` 函式允許你新增應用於整個專案的全域性基礎樣式。這非常適合設定預設字型樣式、重置瀏覽器預設值或定義自定義字型。

要從外掛新增新的基礎樣式，請呼叫 `addBase`，並使用 CSS-in-JS 語法傳入你的樣式。

const plugin = require('tailwindcss/plugin')

module.exports = {
    plugins: [
    plugin(function({ addBase, theme }) {
        addBase({
        'h1': { fontSize: theme('fontSize.2xl') },
        'h2': { fontSize: theme('fontSize.xl') },
        'h3': { fontSize: theme('fontSize.lg') },
        })
    })
    ]
}

新增變體

`addVariant` 和 `matchVariant` 函式允許你建立你自己的自定義修飾符，這些修飾符可以像 `hover`、`focus` 或 `supports` 等內建變體一樣使用。

靜態變體

使用 `addVariant` 函式建立簡單的自定義變體。提供你的自定義變體的名稱和一個描述如何修改選擇器的格式字串。

const plugin = require('tailwindcss/plugin')

module.exports = {
    // ...
    plugins: [
    plugin(function({ addVariant }) {
        addVariant('optional', '&:optional')
        addVariant('hocus', ['&:hover', '&:focus'])
        addVariant('inverted-colors', '@media (inverted-colors: inverted)')
    })
    ]
}

第一個引數是使用者將在 HTML 中使用的修飾符名稱，因此上面的示例將使編寫如下類成為可能：

<form class="flex inverted-colors:outline ...">
    <input class="optional:border-gray-300 ..." />
    <button class="bg-blue-500 hocus:bg-blue-600">...</button>
</form>

動態變體

`matchVariant` 函式允許你建立自定義引數化變體，類似於內建變體，如 `supports-*`、`data-*` 和 `aria-*`。

const plugin = require('tailwindcss/plugin')

module.exports = {
    plugins: [
    plugin(function({ matchVariant }) {
        matchVariant(
        'nth',
        (value) => {
            return `&:nth-child(${value})`;
        },
        {
            values: {
            1: '1',
            2: '2',
            3: '3',
            }
        }
        );
    })
    ]
}

使用 `matchVariant` 定義的變體也支援使用方括號表示法的任意值。

<div class="nth-[3n+1]:bg-blue-500 ...">
  <!-- ... -->
</div>

如果需要避免與來自相同變體的其他值的優先順序問題，請使用 `sort` 選項控制生成的 CSS 的源順序。

matchVariant("min", (value) => `@media (min-width: ${value})`, {
    sort(a, z) {
        return parseInt(a.value) - parseInt(z.value);
    },
    });

父級和兄弟級狀態

Tailwind 的特殊功能（如 `group-*` 和 `peer-*`）不會自動與自定義修飾符一起工作。要使它們工作，你需要使用 `:merge` 將自定義修飾符註冊為單獨的變體。這確保了 `group` 和 `peer` 類只在最終樣式表中出現一次，從而確保正確的應用。

const plugin = require('tailwindcss/plugin')

module.exports = {
    // ...
    plugins: [
    plugin(function({ addVariant }) {
        addVariant('optional', '&:optional')addComponents([
  {
    '@media (min-width: 500px)': {
      // ...
    }
  },
  {
    '@media (min-width: 500px)': {
      // ...
    }
  },
  {
    '@media (min-width: 500px)': {
      // ...
    }
  },
])
        addVariant('group-optional', ':merge(.group):optional &')
        addVariant('peer-optional', ':merge(.peer):optional ~ &')
    })
    ]
}

擴充套件配置

外掛可以透過向外掛函式的第二個引數提供物件來向用戶的 `tailwind.config.js` 檔案新增自己的設定。

const plugin = require('tailwindcss/plugin')

module.exports = plugin(function({ matchUtilities, theme }) {
  matchUtilities(
    {
      tab: (value) => ({
        tabSize: value
      }),
    },
    { values: theme('tabSize') }
  )
}, {
  theme: {
    tabSize: {
      1: '1',
      2: '2',
      4: '4',
      8: '8',
    }
  }
})

公開選項

`plugin.withOptions` API 允許你使用自定義配置物件配置外掛。這使使用者能夠調整外掛的行為，而這些行為與主題設定沒有直接關係。例如，你可以使用此 API 讓使用者指定外掛使用的類名。此 API 的工作方式類似於常規外掛 API，但不是直接傳遞值，而是定義接收使用者配置選項並返回外掛相應值的函式。

const plugin = require('tailwindcss/plugin')

module.exports = plugin.withOptions(function (options = {}) {
  return function({ addComponents }) {
    const className = options.className ?? 'markdown'

    addComponents({
      [`.${className}`]: {
        // ...
      }
    })
  }
}, function (options) {
  return {
    theme: {
      markdown: {
        // ...
      }
    },
  }
})

使用者將在他們的外掛配置中註冊外掛時，傳遞他們的選項。

/** @type {import('tailwindcss').Config} */
module.exports = {
  theme: {
    // ...
  },
  plugins: [
    require('./plugins/markdown.js')({
      className: 'wysiwyg'
    })
  ],
}

如果使用者不需要傳入任何自定義選項，他們也可以正常註冊以這種方式建立的外掛，而無需呼叫它們。

/** @type {import('tailwindcss').Config} */
module.exports = {
  theme: {
    // ...
  },
  plugins: [
    require('./plugins/markdown.js')
  ],
}

CSS-in-JS 語法

Tailwind 的外掛系統使用 JavaScript 物件編寫 CSS 規則，類似於 Emotion 等 CSS-in-JS 庫的方式。它在後臺使用 postcss-js。

考慮這個簡單的 CSS 規則：

.card {
    background-color: #fff;
    border-radius: .25rem;
    box-shadow: 0 2px 4px rgba(0,0,0,0.2);
    }

將其轉換為 CSS-in-JS 物件如下所示：

addComponents({
    '.card': {
        'background-color': '#fff',
        'border-radius': '.25rem',
        'box-shadow': '0 2px 4px rgba(0,0,0,0.2)',
    }
    })

也支援巢狀（由 postcss-nested 提供支援），使用你可能熟悉的與 Sass 或 Less 相同的語法。

addComponents({
    '.card': {
        backgroundColor: '#fff',
        borderRadius: '.25rem',
        boxShadow: '0 2px 4px rgba(0,0,0,0.2)',
        '&:hover': {
        boxShadow: '0 10px 15px rgba(0,0,0,0.2)',
        },
        '@media (min-width: 500px)': {
        borderRadius: '.5rem',
        }
    }
    })

可以在同一個物件中定義多個規則。

addComponents({
    '.btn': {
        padding: '.5rem 1rem',
        borderRadius: '.25rem',
        fontWeight: '600',
    },
    '.btn-blue': {
        backgroundColor: '#3490dc',
        color: '#fff',
        '&:hover': {
        backgroundColor: '#2779bd'
        },
    },
    '.btn-red': {
        backgroundColor: '#e3342f',
        color: '#fff',
        '&:hover': {
        backgroundColor: '#cc1f1a'
        },
    },
    })

或者，如果需要重複相同的鍵，則可以作為物件陣列。

addComponents([
  {
    '@media (min-width: 500px)': {
      // ...
    }
  },
  {
    '@media (min-width: 500px)': {
      // ...
    }
  },
  {
    '@media (min-width: 500px)': {
      // ...
    }
  },
])
列印頁面
上一頁
下一頁
廣告