Back to Details

wot-ui-unocss-preset-guide

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Wot UnoCSS Preset 使用指南

Wot UnoCSS Preset 使用指南

适用场景

适用场景

当用户询问以下内容时，优先使用本 Skill：
  • 如何安装 
    @wot-ui/unocss-preset
  • 如何在 
    unocss.config.ts
    配置 
    presetWot
  • prefix
    、
    preflight
    、
    baseTokens
    怎么用
  • 为什么类名不生效、自动补全不出现、CI 与本地结果不一致
目标是给出可直接复制的最佳实践，帮助用户快速完成接入并稳定运行。
当用户询问以下内容时，优先使用本 Skill：
  • 如何安装 
    @wot-ui/unocss-preset
  • 如何在 
    unocss.config.ts
    配置 
    presetWot
  • prefix
    、
    preflight
    、
    baseTokens
    怎么用
  • 为什么类名不生效、自动补全不出现、CI 与本地结果不一致
目标是给出可直接复制的最佳实践，帮助用户快速完成接入并稳定运行。

最小安装步骤

最小安装步骤

bash
pnpm add -D unocss
pnpm add @wot-ui/unocss-preset
bash
pnpm add -D unocss
pnpm add @wot-ui/unocss-preset

推荐配置（完整示例）

推荐配置（完整示例）

ts
import { presetWot } from '@wot-ui/unocss-preset'
import { defineConfig } from 'unocss'

export default defineConfig({
  presets: [
    presetWot({
      prefix: 'wot',
      preflight: true,
      baseTokens: false,
    }),
  ],
})
ts
import { presetWot } from '@wot-ui/unocss-preset'
import { defineConfig } from 'unocss'

export default defineConfig({
  presets: [
    presetWot({
      prefix: 'wot',
      preflight: true,
      baseTokens: false,
    }),
  ],
})

配置项说明

配置项说明

  • prefix
    ：工具类前缀，默认 
    wot
    。示例：
    wot-text-primary
    、
    wot-m-main
    。
  • preflight
    ：是否注入 wot-ui CSS 变量，默认 
    true
    。
  • baseTokens
    ：是否开放基础色板和原始 token 类名，默认 
    false
    。
  • prefix
    ：工具类前缀，默认 
    wot
    。示例：
    wot-text-primary
    、
    wot-m-main
    。
  • preflight
    ：是否注入 wot-ui CSS 变量，默认 
    true
    。
  • baseTokens
    ：是否开放基础色板和原始 token 类名，默认 
    false
    。

常用类名示例

常用类名示例

  • 颜色：
    wot-text-primary
    、
    wot-bg-danger-surface
    、
    wot-border-border-main
  • 间距：
    wot-m-main
    、
    wot-gap-tight
    、
    wot-gap-x-loose
  • 内边距：
    wot-p-main
    、
    wot-px-tight
    、
    wot-pb-loose
  • 圆角：
    wot-rounded-md
    、
    wot-rounded-full
  • 字重：
    wot-font-medium
    、
    wot-font-semibold
  • 排版：
    wot-text-body-main
    、
    wot-text-title-large
  • 透明度：
    wot-opacity-disabled
  • 描边：
    wot-border-stroke-main
  • 颜色：
    wot-text-primary
    、
    wot-bg-danger-surface
    、
    wot-border-border-main
  • 间距：
    wot-m-main
    、
    wot-gap-tight
    、
    wot-gap-x-loose
  • 内边距：
    wot-p-main
    、
    wot-px-tight
    、
    wot-pb-loose
  • 圆角：
    wot-rounded-md
    、
    wot-rounded-full
  • 字重：
    wot-font-medium
    、
    wot-font-semibold
  • 排版：
    wot-text-body-main
    、
    wot-text-title-large
  • 透明度：
    wot-opacity-disabled
  • 描边：
    wot-border-stroke-main

上手示例（可复制）

上手示例（可复制）

1) 一个“卡片”示例（uni-app / Vue）

1) 一个“卡片”示例（uni-app / Vue）

vue
<template>
  <view class="wot-bg-filled-oppo wot-rounded-2xl wot-p-super-loose wot-border-border-main wot-border-stroke-main">
    <text class="wot-text-title-large wot-text-text-main wot-font-semibold">
      Wot UnoCSS Preset
    </text>

    <view class="wot-mt-tight">
      <text class="wot-text-body-main wot-text-text-secondary">
        wot-text-body-main + wot-text-text-secondary
      </text>
    </view>

    <view class="wot-mt-loose wot-bg-primary wot-rounded-full wot-px-main wot-py-extra-tight">
      <text class="wot-text-label-large wot-text-text-white wot-font-semibold">
        wot-bg-primary
      </text>
    </view>
  </view>
</template>
vue
<template>
  <view class="wot-bg-filled-oppo wot-rounded-2xl wot-p-super-loose wot-border-border-main wot-border-stroke-main">
    <text class="wot-text-title-large wot-text-text-main wot-font-semibold">
      Wot UnoCSS Preset
    </text>

    <view class="wot-mt-tight">
      <text class="wot-text-body-main wot-text-text-secondary">
        wot-text-body-main + wot-text-text-secondary
      </text>
    </view>

    <view class="wot-mt-loose wot-bg-primary wot-rounded-full wot-px-main wot-py-extra-tight">
      <text class="wot-text-label-large wot-text-text-white wot-font-semibold">
        wot-bg-primary
      </text>
    </view>
  </view>
</template>

2) 间距/布局示例（常见组合）

2) 间距/布局示例（常见组合）

  • 外边距：
    wot-mt-tight
    、
    wot-mt-main
    、
    wot-mt-super-loose
  • 内边距：
    wot-p-loose
    、
    wot-px-main
    、
    wot-py-extra-tight
  • 横向/纵向组合：
    wot-mx-main
    、
    wot-my-loose
  • gap：
    wot-gap-tight
    、
    wot-gap-x-main
    、
    wot-gap-y-loose
  • 外边距：
    wot-mt-tight
    、
    wot-mt-main
    、
    wot-mt-super-loose
  • 内边距：
    wot-p-loose
    、
    wot-px-main
    、
    wot-py-extra-tight
  • 横向/纵向组合：
    wot-mx-main
    、
    wot-my-loose
  • gap：
    wot-gap-tight
    、
    wot-gap-x-main
    、
    wot-gap-y-loose

3) 语义色示例（背景/文字/边框）

3) 语义色示例（背景/文字/边框）

  • 背景：
    wot-bg-primary
    、
    wot-bg-success-surface
    、
    wot-bg-warning-surface
    、
    wot-bg-danger-surface
  • 文字：
    wot-text-text-main
    、
    wot-text-text-secondary
    、
    wot-text-primary
    、
    wot-text-success-main
  • 边框：
    wot-border-border-main
    、
    wot-border-success-main
    、
    wot-border-warning-main
    、
    wot-border-danger-main
  • 背景：
    wot-bg-primary
    、
    wot-bg-success-surface
    、
    wot-bg-warning-surface
    、
    wot-bg-danger-surface
  • 文字：
    wot-text-text-main
    、
    wot-text-text-secondary
    、
    wot-text-primary
    、
    wot-text-success-main
  • 边框：
    wot-border-border-main
    、
    wot-border-success-main
    、
    wot-border-warning-main
    、
    wot-border-danger-main

4) 暗黑模式示例

4) 暗黑模式示例

预设会输出暗色变量选择器 
.wot-theme-dark ...
，你只需要在根节点加 class：
vue
<template>
  <view :class="dark ? 'wot-theme-dark' : ''">
    <view class="wot-bg-filled-oppo wot-p-main wot-rounded-lg">
      <text class="wot-text-text-main">当前主题：{{ dark ? 'Dark' : 'Light' }}</text>
    </view>
  </view>
</template>
预设会输出暗色变量选择器 
.wot-theme-dark ...
，你只需要在根节点加 class：
vue
<template>
  <view :class="dark ? 'wot-theme-dark' : ''">
    <view class="wot-bg-filled-oppo wot-p-main wot-rounded-lg">
      <text class="wot-text-text-main">当前主题：{{ dark ? 'Dark' : 'Light' }}</text>
    </view>
  </view>
</template>

5) 打开 baseTokens（可选）

5) 打开 baseTokens（可选）

当你希望使用基础色板/原始 token 时启用：
ts
presetWot({
  baseTokens: true,
})
启用后会额外提供类似 
wot-base-black
这类 token（用于 
theme.colors
与颜色规则匹配）。
当你希望使用基础色板/原始 token 时启用：
ts
presetWot({
  baseTokens: true,
})
启用后会额外提供类似 
wot-base-black
这类 token（用于 
theme.colors
与颜色规则匹配）。

轻量提醒

轻量提醒

  • 历史项目若仍使用 
    w-
    前缀，可通过 
    prefix: 'w'
    兼容。
  • 若 playground/子包构建异常，优先检查是否：
    • 使用包名导入（如 
      @wot-ui/unocss-preset
      ）
    • 在依赖主包产物的场景下先执行主包构建
  • 若需要同步上游 wot-ui 变量，可使用： 
    • pnpm generate:css-vars:clone
  • 历史项目若仍使用 
    w-
    前缀，可通过 
    prefix: 'w'
    兼容。
  • 若 playground/子包构建异常，优先检查是否：
    • 使用包名导入（如 
      @wot-ui/unocss-preset
      ）
    • 在依赖主包产物的场景下先执行主包构建
  • 若需要同步上游 wot-ui 变量，可使用： 
    • pnpm generate:css-vars:clone

常见问题排查

常见问题排查

  1. 类名不生效
  • 确认项目已启用 UnoCSS 且 
    presetWot()
    已加入 
    presets
    。
  • 确认类名前缀与配置一致（默认 
    wot-
    ）。
  1. VS Code 没有自动补全
  • 确认安装 UnoCSS 官方扩展。
  • 确认编辑器能定位到项目 
    unocss.config.ts
    。
  • 确认类名写在扩展可扫描的文件类型内。
  1. CI 能复现但本地不复现（或反过来）
  • 对齐 Node/pnpm 版本与锁文件。
  • 对齐执行顺序（例如先构建主包，再构建依赖主包产物的 playground）。
  1. 类名不生效
  • 确认项目已启用 UnoCSS 且 
    presetWot()
    已加入 
    presets
    。
  • 确认类名前缀与配置一致（默认 
    wot-
    ）。
  1. VS Code 没有自动补全
  • 确认安装 UnoCSS 官方扩展。
  • 确认编辑器能定位到项目 
    unocss.config.ts
    。
  • 确认类名写在扩展可扫描的文件类型内。
  1. CI 能复现但本地不复现（或反过来）
  • 对齐 Node/pnpm 版本与锁文件。
  • 对齐执行顺序（例如先构建主包，再构建依赖主包产物的 playground）。

响应风格要求

响应风格要求

  • 输出简洁、可执行，优先给“可复制配置 + 最短排查路径”。
  • 当用户目标明确时，先给结论和配置，再补充原因说明。
  • 不擅自引入本项目未使用的额外工具链或复杂抽象。
  • 输出简洁、可执行，优先给“可复制配置 + 最短排查路径”。
  • 当用户目标明确时，先给结论和配置，再补充原因说明。
  • 不擅自引入本项目未使用的额外工具链或复杂抽象。