unocss 的相关配置说明

151 min read
import {
  defineConfig,
  presetAttributify,
  presetIcons,
  presetTypography,
  presetUno,
  transformerDirectives,
  transformerVariantGroup,
} from 'unocss'

export default defineConfig({
  presets: [
    presetUno(),
    presetAttributify(),
    presetIcons({
      scale: 1.1,
      cdn: 'https://esm.sh/',
    }),
    presetTypography({
      cssExtend: {
        'ul,ol': {
          'padding-left': '2.25em',
          'position': 'relative',
        },
      },
    }),
  ],
  transformers: [transformerVariantGroup(), transformerDirectives()],
  shortcuts: [{
    'fc': 'flex justify-center',
    'fi': 'flex items-center',
    'fb': 'flex justify-between',
    'fcc': 'fc items-center',
    'fie': 'fi justify-end',
    'col-fcc': 'flex-col fcc',
    'inline-fcc': 'inline-flex items-center justify-center',
    'base-focus': 'focus:(bg-op-20 ring-0 outline-none)',
    'b-slate-link': 'border-b border-(slate none) hover:border-dashed',
    'gpt-title': 'text-2xl font-extrabold mr-1',
    'gpt-subtitle': 'text-(2xl transparent) font-extrabold bg-(clip-text gradient-to-r) from-sky-400 to-emerald-600',
    'gpt-copy-btn': 'absolute top-12px right-12px z-3 fcc border b-transparent w-8 h-8 p-2 bg-light-300 dark:bg-dark-300 op-90 cursor-pointer',
    'gpt-copy-tips': 'op-0 h-7 bg-black px-2.5 py-1 box-border text-xs c-white fcc rounded absolute z-1 transition duration-600 whitespace-nowrap -top-8',
    'gpt-retry-btn': 'fi gap-1 px-2 py-0.5 op-70 border border-slate rounded-md text-sm cursor-pointer hover:bg-slate/10',
    'gpt-back-top-btn': 'fcc p-2.5 text-base rounded-md hover:bg-slate/10 fixed bottom-60px right-20px z-10 cursor-pointer transition-colors',
    'gpt-back-bottom-btn': 'gpt-back-top-btn bottom-20px transform-rotate-180deg',
    'gpt-password-input': 'px-4 py-3 h-12 rounded-sm bg-(slate op-15) base-focus',
    'gpt-password-submit': 'fcc h-12 w-12 bg-slate cursor-pointer bg-op-20 hover:bg-op-50',
    'gen-slate-btn': 'h-12 px-4 py-2 bg-(slate op-15) hover:bg-op-20 rounded-sm',
    'gen-cb-wrapper': 'h-12 my-4 fcc gap-4 bg-(slate op-15) rounded-sm',
    'gen-cb-stop': 'px-2 py-0.5 border border-slate rounded-md text-sm op-70 cursor-pointer hover:bg-slate/10',
    'gen-text-wrapper': 'my-4 fc gap-2 transition-opacity',
    'gen-textarea': 'w-full px-3 py-3 min-h-12 max-h-36 rounded-sm bg-(slate op-15) resize-none base-focus placeholder:op-50 dark:(placeholder:op-30) scroll-pa-8px',
    'sys-edit-btn': 'inline-fcc gap-1 text-sm bg-slate/20 px-2 py-1 rounded-md transition-colors cursor-pointer hover:bg-slate/50',
    'stick-btn-on': '!bg-$c-fg text-$c-bg hover:op-80',
  }],
})

presetIcons 是 UnoCSS 的一个预设，用于在项目中方便地使用 SVG 图标。通过 presetIcons 预设，你可以直接在 HTML 中通过特定的类名引入图标。这个预设通常从一个 CDN 加载图标，并支持配置选项来调整图标的尺寸和来源。

下面是如何使用 presetIcons 预设的步骤：

1. 配置 presetIcons

在你的 UnoCSS 配置文件中，引入并配置 presetIcons：

import { defineConfig, presetIcons } from 'unocss';

export default defineConfig({
  presets: [
    presetIcons({
      scale: 1.1, // 设置图标的缩放比例
      cdn: 'https://esm.sh/', // 指定图标的 CDN 地址
    }),
    // ...其他预设
  ],
});
  • scale：这个选项用于调整图标的大小。在这个例子中，图标的大小会被设置为原始尺寸的 1.1 倍。
  • cdn：这里指定了用于加载图标的 CDN 地址。https://esm.sh/ 是一个提供 ESM 模块的 CDN，也可以用于加载 SVG 图标。

2. 在 HTML 中使用图标

配置好 presetIcons 之后，你可以直接在 HTML 中通过类名引入图标。例如：

<div class="i-carbon:alarm"></div>
  • i-carbon:alarm：这个类名表示从 carbon 图标集中引入名为 alarm 的图标。格式通常为 i-[collection]:[icon]。

3. 个性化图标样式

你还可以添加额外的类来个性化图标的样式，例如颜色、大小等：

<div class="i-carbon:alarm text-2xl text-blue-500"></div>

在这个例子中，除了引入 alarm 图标外，还应用了 text-2xl 和 text-blue-500 类来设置图标的大小和颜色。

注意事项

  • 确保你使用的 CDN 提供了你需要的图标集和图标。
  • 图标的可用性和名称可能因 CDN 和图标集的不同而有所不同。
  • presetIcons 提供了一种便捷的方式来使用 SVG 图标，但你应该确保这符合你项目的性能和优化需求。

通过使用 presetIcons，你可以轻松地在项目中引入和使用各种 SVG 图标，从而增强用户界面的视觉效果和交互体验。

如果你想在 UnoCSS 中使用特定的图标库，如 Carbon Icons，你通常需要在 presetIcons 预设中指定相关的 CDN 或图标集。不过，具体的配置方式取决于 UnoCSS 的版本和你所使用的 CDN 服务。

对于大多数情况，你不需要显式地指定使用 Carbon Icons，因为大多数图标 CDN（如 https://esm.sh/）已经包含了多个流行的图标库，包括 Carbon Icons。在这种情况下，你只需要确保正确地使用了图标的类名。

下面是一个基本的示例来说明如何在 UnoCSS 配置中设置 presetIcons：

import { defineConfig, presetIcons } from 'unocss';

export default defineConfig({
  presets: [
    presetIcons({
      // 这里可以设置 CDN，如果需要的话
      // 例如，使用 esm.sh CDN
      cdn: 'https://esm.sh/',
    }),
    // ...其他预设
  ],
  // ...其他配置
});

使用 Carbon Icons 的方法是在类名中指定图标库和图标名称。例如，要使用 Carbon Icons 中的 alarm 图标，你可以在 HTML 中这样写：

<div class="i-carbon:alarm"></div>

这里，i- 是表示这是一个图标的前缀，carbon 指定了图标库，而 alarm 是图标的具体名称。

查找具体的图标名称

要找到 Carbon Icons 中具体的图标名称，你可以访问 Carbon Icons 的官方网站，在那里你可以浏览和搜索不同的图标，并获取它们的名称。

注意事项

  • 确保你所使用的 CDN 支持 Carbon Icons。
  • 如果你使用的 CDN 或 UnoCSS 版本需要特殊的配置来支持特定图标库，请参考相应的文档进行配置。
  • 图标的命名和可用性可能随着图标库版本的更新而变化，因此建议定期查看最新的图标库文档。

presetAttributify() 是 UnoCSS 中的一个预设（preset），它允许你通过 HTML 属性的方式来应用样式，而不是传统的类名（class name）方法。这种方法提供了一种更直观、更快捷的方式来使用原子 CSS 类。

主要特点

  1. 简洁的语法： 使用 HTML 属性而不是类名来应用样式，使得代码更加简洁和直观。

  2. 易于理解和维护： 直接在元素上看到应用的样式，而不需要在 CSS 文件或类名中寻找定义。

  3. 高度自定义： 支持自定义属性名称，使其适应不同的编码风格或项目需求。

如何使用 presetAttributify()

  1. 在配置文件中启用 presetAttributify()：

    在 UnoCSS 配置文件中引入并启用 presetAttributify() 预设：

    import { defineConfig, presetAttributify } from 'unocss';

export default defineConfig({
  presets: [
    presetAttributify(),
    // ...其他预设
  ],
});

  2. 在 HTML 中应用样式：

    使用属性而不是类名来设置样式。例如，传统的类名方法如下：

    <div class="text-center p-4 m-2 bg-blue-500"></div>

    使用 presetAttributify() 后，相同的样式可以这样应用：

    <div text="center" p="4" m="2" bg="blue-500"></div>

    这里，text="center"、p="4"、m="2"、bg="blue-500" 等都是直接作为属性应用到 HTML 元素上。

注意事项

  • 兼容性和可维护性： 虽然 presetAttributify() 提供了一种更简洁的语法，但在某些情况下，它可能会与已有的 HTML 属性或 JavaScript 框架产生冲突。在使用之前，确保它适合你的项目环境。
  • 性能考虑： 使用属性的方式可能会略微增加 HTML 的体积，尤其是在有大量样式应用时。但对于大多数现代 web 应用来说，这种增加通常是微不足道的。

通过 presetAttributify()，UnoCSS 为原子 CSS 提供了一种新的、更直观的使用方式，这对于快速开发和原型制作尤其有用。

presetUno() 是 UnoCSS 的一个核心预设（preset），它提供了一套丰富的原子 CSS 类，用于快速构建和应用样式。这个预设包含了大量的实用类（utility classes），涵盖了布局、间距、颜色、排版、边框等多方面的样式。

主要特点

  1. 丰富的实用类： 提供了大量的原子 CSS 类，涵盖了绝大多数常见的 CSS 属性和用例。

  2. 按需生成： 与 UnoCSS 的核心理念一致，presetUno() 只会生成你在项目中实际使用的类。

  3. 易于扩展： 可以根据项目的特定需求定制和扩展这些实用类。

  4. 快速原型开发： 适合于快速构建原型和布局，减少编写和维护大量自定义 CSS 的需要。

如何使用 presetUno()

  1. 在 UnoCSS 配置文件中启用 presetUno()：

    在你的 UnoCSS 配置文件（通常是 unocss.config.js 或类似的文件）中引入并使用 presetUno()：

    import { defineConfig, presetUno } from 'unocss';

export default defineConfig({
  presets: [
    presetUno(),
    // ...其他预设
  ],
});

  2. 在项目中使用实用类：

    使用 presetUno() 提供的实用类来快速应用样式。例如：

    <div class="p-4 m-2 text-center bg-blue-500 text-white">
  Hello, UnoCSS!
</div>

    在这个例子中，p-4（padding），m-2（margin），text-center（文本居中），bg-blue-500（背景色），和 text-white（文字颜色）都是 presetUno() 提供的实用类。

注意事项

  • 学习曲线： 对于不熟悉原子 CSS 方法的开发者来说，可能需要一段时间来适应使用大量实用类的方式。
  • 项目兼容性： 在某些项目中，过度依赖原子 CSS 可能会导致代码难以理解和维护。确保这种方法适合你的项目和团队。
  • 定制性： 虽然 presetUno() 提供了大量的实用类，但你可能仍需要根据项目需求进行一些定制。

通过使用 presetUno()，你可以利用 UnoCSS 强大的按需生成能力，快速构建具有响应式和高度定制的 UI，同时保持项目的轻量和高效。

presetTypography 是 UnoCSS 的一个预设，专门用于处理和优化排版相关的样式。这个预设提供了一系列实用的 CSS 类，用于设置文本的大小、行高、字体、颜色等排版属性，使得处理网页文本内容的样式变得更加简单和高效。

主要特点

  1. 排版优化： 预设包括用于文字大小、行高、字体、颜色等的实用类，方便进行快速的文本排版。

  2. 易于使用： 与其他 UnoCSS 预设一样，presetTypography 提供的类可以直接应用于 HTML 元素，无需编写额外的 CSS 代码。

  3. 高度可配置： 可以根据项目需求自定义预设的行为，例如，添加额外的字体大小或调整默认的行高。

如何使用 presetTypography

  1. 在 UnoCSS 配置文件中启用 presetTypography：

    在你的 UnoCSS 配置文件中引入并配置 presetTypography 预设：

    import { defineConfig, presetTypography } from 'unocss';

export default defineConfig({
  presets: [
    presetTypography({
      // 可选的配置参数
      cssExtend: {
        // 自定义或扩展排版样式
      },
    }),
    // ...其他预设
  ],
});

  2. 在项目中应用排版样式：

    使用 presetTypography 提供的类来设置文本样式。例如，设置文本大小、行高：

    <p class="text-lg leading-relaxed">
  This is a paragraph with large text and relaxed line height.
</p>

注意事项

  • 样式覆盖： 在某些情况下，presetTypography 提供的样式可能与其他 CSS 规则冲突。确保理解优先级和覆盖规则。

  • 性能考虑： 尽管 UnoCSS 通过按需生成来优化性能，但过度使用大量不同的排版样式可能会增加生成的 CSS 文件的大小。

  • 学习曲线： 对于习惯于传统 CSS 编写方式的开发者，可能需要一段时间来适应使用原子类进行排版设计。

presetTypography 通过为常见的文本排版问题提供快速、一致的解决方案，简化了前端开发过程中的排版工作。通过合理配置和使用，它可以显著提高网页文本内容的可读性和美观性。

transformerVariantGroup() 是 UnoCSS 中的一个转换器（transformer），用于支持变体组合（variant groups）。这个功能允许开发者将多个响应式或状态变体（如悬浮、聚焦等）应用于一组样式，而不是单独对每个类进行重复定义。它使得编写具有多种状态的 CSS 类更加简洁和高效。

主要特点

  1. 组合多个变体： 允许在单个声明中组合多个响应式或状态变体，例如悬浮（hover）、聚焦（focus）等。

  2. 简化代码： 减少重复和冗余的代码，使 HTML 更加清晰和简洁。

  3. 提高可读性： 通过将相关的变体放在一起，提高了代码的可读性和维护性。

如何使用 transformerVariantGroup

  1. 在 UnoCSS 配置文件中启用 transformerVariantGroup：

    在你的 UnoCSS 配置文件中引入并启用 transformerVariantGroup：

    import { defineConfig, transformerVariantGroup } from 'unocss';

export default defineConfig({
  transformers: [
    transformerVariantGroup(),
    // ...其他转换器
  ],
});

  2. 在项目中使用变体组合：

    使用括号 () 来组合多个变体。例如，如果你想要一个按钮在悬浮时改变背景颜色和文字颜色，你可以这样写：

    <button class="bg-blue-500 text-white (hover:bg-green-500 hover:text-black)">
  Click me
</button>

    在这个例子中，hover:bg-green-500 和 hover:text-black 被组合在一起，当按钮悬浮时，这两个样式都会被应用。

注意事项

  • 避免过度使用： 虽然变体组合很强大，但过度使用可能会使代码变得难以理解。在可能的情况下保持简洁。

  • 与其他转换器的兼容性： 确保 transformerVariantGroup 与你的其他 UnoCSS 配置和转换器兼容。

transformerVariantGroup 是一个强大的工具，特别适合那些需要在多种状态和响应式布局中快速应用一组样式的场景。通过合理使用，它可以极大地提升前端开发的效率和代码的整洁度。

transformerDirectives() 是 UnoCSS 中的一个功能强大的转换器（transformer），它允许开发者在 HTML 中直接使用特殊的指令（directives）来应用复杂的 CSS 逻辑。这种方法可以使得样式的应用更加灵活和动态，特别是在处理响应式布局、状态变化或其他复杂的样式逻辑时。

主要特点

  1. 直接在 HTML 中应用复杂的 CSS 逻辑： 使用特殊的指令来控制样式的应用，无需编写额外的 CSS 或 JavaScript。

  2. 提高代码的可读性和维护性： 通过将样式逻辑内联在 HTML 中，可以使样式的应用更加直观和易于维护。

  3. 支持动态和条件样式： 特别适合于实现基于条件的样式变化，如响应式设计、悬浮状态、聚焦状态等。

如何使用 transformerDirectives

  1. 在 UnoCSS 配置文件中启用 transformerDirectives：

    在你的 UnoCSS 配置文件中引入并启用 transformerDirectives：

    import { defineConfig, transformerDirectives } from 'unocss';

export default defineConfig({
  transformers: [
    transformerDirectives(),
    // ...其他转换器
  ],
});

  2. 在项目中使用指令：

    使用特殊的指令语法来应用样式。指令通常以 @ 开头，后跟指令名称和参数。例如，实现一个基于屏幕宽度的响应式设计：

    <div class="@sm:bg-red-500 @md:bg-green-500 @lg:bg-blue-500">
  Responsive Background Color
</div>

    在这个例子中，根据屏幕宽度的不同，背景颜色会在红色、绿色和蓝色之间切换。

注意事项

  • 学习曲线： 对于不熟悉指令语法的开发者，可能需要一些时间来适应这种方式。

  • 避免过度复杂化： 尽管 transformerDirectives 提供了很大的灵活性，但过度使用或滥用可能会使代码难以理解和维护。合理使用是关键。

transformerDirectives 提供了一种强大的方法来直接在 HTML 中处理复杂的样式逻辑，这使得开发更加灵活，同时能够保持代码的整洁和可维护性。通过合理利用这个工具，你可以在前端项目中实现更加动态和响应性强的设计。

UnoCSS 的 transformerDirectives 允许开发者在 HTML 中直接使用特殊指令来控制样式的应用。这些指令的种类和数量可能会根据 UnoCSS 的版本和你的配置而有所不同。通常，这些指令用于处理响应式设计、状态变化（如悬浮、聚焦）、主题切换等场景。

下面是一些常见的指令类型，你可能会在使用 transformerDirectives 时遇到：

响应式设计指令

  • 屏幕宽度指令： 如 @sm、@md、@lg、@xl，用于根据不同的屏幕宽度应用不同的样式。

    例子：

    <div class="@sm:text-sm @md:text-base @lg:text-lg">
  Responsive Text Size
</div>

状态变化指令

  • 悬浮（Hover）指令： 如 @hover，用于定义元素在悬浮状态下的样式。

    例子：

    <button class="@hover:bg-blue-500">
  Hover Me
</button>

  • 聚焦（Focus）指令： 如 @focus，用于定义元素在聚焦状态下的样式。

    例子：

    <input class="@focus:border-blue-500" type="text">

主题相关指令

  • 暗模式（Dark Mode）指令： 如 @dark，用于定义暗模式下的样式。

    例子：

    <div class="@dark:bg-gray-800">
  Dark Mode Background
</div>

其他条件性指令

  • 分组指令： 用于将多个样式应用于同一条件，通常与 transformerVariantGroup 配合使用。

    例子：

    <div class="@sm:(p-4 bg-red-500)">
  Small Screen Styles
</div>

注意事项

  • 这些指令的具体可用性和语法可能取决于你的 UnoCSS 配置和所使用的版本。
  • 有些指令可能需要特定的预设或配置才能使用。
  • 指令的使用应该根据项目的需求和代码维护的方便程度来决定。过度使用或不当使用可能会使代码变得复杂和难以维护。

为了获得最准确和最新的指令信息，建议查阅 UnoCSS 的官方文档或源代码。在实际使用中，也可以根据项目的具体需求自定义或扩展指令。

在 UnoCSS 中，shortcuts 是一种配置项，允许你为一组或多个实用类（utility classes）定义简短的别名。这使得在开发过程中能够快速应用复合样式，同时保持代码的简洁和可读性。

主要特点

  1. 简化类名： 通过定义短别名，减少了在 HTML 中重复书写长串类名的需要。
  2. 提高开发效率： 快捷方式可以让你快速应用常用的样式组合，加速开发过程。
  3. 提高代码的可维护性： 简化的别名使得 HTML 更加清晰易读，同时易于在项目中统一管理样式。

如何使用 shortcuts

  1. 在 UnoCSS 配置文件中定义 shortcuts：

    在你的 UnoCSS 配置文件中，你可以定义一系列的快捷方式，每个快捷方式都是一个键值对，键是简短的别名，值是一组或单个的类名。

    import { defineConfig } from 'unocss';

export default defineConfig({
  shortcuts: [
    {
      'btn': 'py-2 px-4 font-semibold rounded-lg shadow-md',
      'btn-blue': 'text-white bg-blue-500 hover:bg-blue-700',
      // ...更多快捷方式
    },
  ],
});

  2. 在 HTML 中使用快捷方式：

    在 HTML 或其他模板中，你可以直接使用定义的快捷方式作为类名。

    <button class="btn btn-blue">Click me</button>

    在这个例子中，btn 和 btn-blue 分别应用了一组预定义的样式。

注意事项

  • 避免过度使用： 虽然快捷方式可以提高效率，但过度使用可能会使得样式难以跟踪和管理。合理平衡直接使用实用类和快捷方式是很重要的。
  • 命名冲突： 在定义快捷方式时，要小心避免与已有的类名或第三方库中的类名产生冲突。
  • 一致性： 在团队项目中，确保所有开发者对快捷方式的命名和使用保持一致，以避免混乱。

通过合理使用 shortcuts，你可以在保持代码整洁的同时，提升开发效率和样式的可维护性。