更新记录

1.1.0（2026-11-10） 下载此版本

新增

• y-scss 组件升级为局部主题容器：新增 theme 属性，支持 auto（默认，跟随全局）、light、dark，可在指定区域强制明暗主题，内置完整的 --y-* 变量覆盖。
• 新增 --y-shadow 变量：亮色 rgba(0, 0, 0, 0.08)，暗色 rgba(0, 0, 0, 0.6)。

变更

• 边框色类统一到 --y-* 体系：bc-container / bc-secondary / bc-stress / bc-title / bc-text / bc-disable / bc-success / bc-warning / bc-error / bc-white / bc-black 改用 rgb(var(--y-*))，不再依赖未定义的 --xh-*-hex。
• bc-default、bc-default-*、bc-text-* 改用 --y-mask / --y-text。
• 全部阴影类由 --xh-shadow 改为 --y-shadow。
• 页面配置变量 --xh-background-color 改为 --y-background-color，theme.json 与 pages.json 引用同步更新。
• package.json 的 dcloudext.darkmode 标记改为支持暗色。

修复

• 修复暗色主题 --y-error 误用 $light-error-rgb 的问题，改用 $dark-error-rgb（#FF3300）。
• 修复边框色类、阴影类因变量未定义而完全不生效的问题。

文档

• 重写 README：补充安装接入、设计变量表、工具类速查、主题定制、体积与裁剪、已知限制与升级说明、FAQ、二次开发。
• 补充 y-scss 主题容器组件的用法和示例。

平台兼容性

uni-app(5.0)

其他

y-scss

y-scss 是一套面向 uni-app（Vue 3） 的 SCSS 设计变量 + 原子化工具类库。它用一套 CSS 变量驱动明暗两套主题，并提供背景、文字、边框、圆角、阴影、Flex、间距、尺寸、定位、变换、层级等常用工具类，适合按 750 设计稿快速搭建小程序页面。

• 当前版本：1.1.0
• 运行依赖：无（纯 SCSS，编译期生效）
• 已验证环境：微信小程序（Vue 3，manifest.json 开启 darkmode）
• 样式单位：rpx

特性

• 一套变量，两套主题：--y-* CSS 变量 + prefers-color-scheme 自动切换明暗色。
• 原子类覆盖常用场景：颜色、间距、尺寸、Flex、边框、圆角、阴影、文本、变换、层级。
• 两级定制：改 SCSS 变量（编译期）或覆写 CSS 变量（运行时）。
• 零运行时：不引入 JS 逻辑，不增加小程序运行时代码体积。
• 按 750 设计稿取数：类名中的数字即 rpx 值，如 mt-24 = margin-top: 24rpx。
• 可选局部主题：<y-scss theme="dark"> 可在指定区域强制明暗主题，不影响全局。

兼容性

插件在 package.json 中的平台声明为「仅微信小程序 Vue 3 已验证」，其他端请以实际测试为准。

目录结构

uni_modules/y-scss/
├── index.scss                    # 入口：工具类 + 明暗主题
├── theme.json                    # pages.json 主题变量模板（需复制到项目根目录）
├── package.json                  # uni_modules 元信息
├── changelog.md                  # 更新日志
├── readme.md
├── components/
│   └── y-scss/y-scss.vue         # 可选主题容器组件（局部明暗切换）
├── theme/
│   ├── light.scss                # 亮色 CSS 变量（声明在 page 上）
│   └── dark.scss                 # 暗色 CSS 变量（声明在 page 上）
└── styles/
    ├── index.scss                # 工具类汇总入口
    ├── default/
    │   ├── color.scss            # 明暗色 SCSS 变量（RGB 三元组）
    │   └── numerical.scss        # 字号等数值 SCSS 变量
    └── global/
        ├── background.scss       # 背景色 / 背景尺寸
        ├── border.scss           # 边框样式 / 颜色 / 宽度 / 圆角
        ├── box.scss              # box-sizing
        ├── box_shadow.scss       # 阴影
        ├── color.scss            # 文字颜色
        ├── display.scss          # display / overflow
        ├── flex.scss             # Flex 布局
        ├── font.scss             # 字号 / 字重 / 字体样式
        ├── height.scss           # 高度
        ├── margin.scss           # 外边距
        ├── other.scss            # 杂项
        ├── padding.scss          # 内边距
        ├── position.scss         # 定位
        ├── preset_css.scss       # 预设样式（按钮、滚动条、玻璃拟态等）
        ├── text.scss             # 文本对齐 / 装饰 / 行高
        ├── transform.scss        # 旋转 / 缩放 / 过渡 / 动画
        ├── width.scss            # 宽度
        └── z_index.scss          # 层级

快速开始

1. 安装

将 y-scss 目录放入项目的 uni_modules/ 下（HBuilderX 可直接从插件市场导入）。无需 npm install。

2. 引入样式（必须，且只引一次）

在 App.vue 的全局样式中引入入口文件：

<!-- App.vue -->
<style lang="scss">
@import "@/uni_modules/y-scss/index.scss";
</style>

注意：

• 不要加 scoped，否则工具类无法作用于页面和子组件。
• 只引入一次。工具类是全局样式，重复引入会重复打包，增大 app.wxss。
• 如果你使用 CLI 工程且 @ 别名在 SCSS 中无法解析，改成相对路径： @import "./uni_modules/y-scss/index.scss";

3. 配置页面背景色（可选）

插件目录内的 theme.json 只是模板，uni-app 只读取项目根目录的 theme.json。需要让 pages.json 使用主题变量时，把文件复制到项目根目录（与 pages.json 同级）：

{
  "light": {
    "--y-background-color": "#F8F9FA"
  },
  "dark": {
    "--y-background-color": "#1A1A2E"
  }
}

然后在 pages.json 中引用：

{
  "globalStyle": {
    "backgroundColor": "@--y-background-color"
  }
}

theme.json 里的 --y-background-color 是 uni-app 页面配置变量，只用于 pages.json / manifest.json；它和样式里使用的 --y-* CSS 变量属于两套作用域，不能当作 CSS 变量使用。

4. 开启微信小程序暗色模式

// manifest.json
{
  "mp-weixin": {
    "darkmode": true
  }
}

开启后，微信小程序才会响应 @media (prefers-color-scheme: dark)。

5. 开始使用

<template>
  <view class="page bgc">
    <view class="card bgc-container br-16 p-24 mt-24">
      <text class="fs-30 c-title fw-bold">标题</text>
      <text class="fs-24 c-text mt-8">这是一段正文说明。</text>

      <view class="d-flex ai-center jc-between mt-16">
        <text class="fs-24 c-disable">次要信息</text>
        <view class="bgc-main br-8 plr-24 ptb-12">
          <text class="fs-24 c-white">操作</text>
        </view>
      </view>
    </view>
  </view>
</template>

设计变量

颜色

颜色以 RGB 三元组 形式定义（如 0, 179, 179），使用时配合 rgba()：

.card {
  background-color: rgba(var(--y-container), 1);
  color: rgba(var(--y-text), 0.8);
  border: 2rpx solid rgba(var(--y-main), 0.3);
}

这样写而不是 rgb(var(--y-main) / 0.5)，是为了兼容较低版本的微信基础库。

字号

字号同时提供 CSS 变量与 SCSS 变量：

另有 $size-xs ~ $size-4xl（4rpx ~ 32rpx）可供自定义 SCSS 使用。

只使用变量、不使用工具类

如果只需要设计变量，不想打包全部工具类，只引入变量文件即可（这两个文件只声明变量，不输出任何 CSS 规则，可以安全重复引入）：

// 任意 .scss 文件
@import "@/uni_modules/y-scss/styles/default/color.scss";
@import "@/uni_modules/y-scss/styles/default/numerical.scss";

.my-card {
  background: rgba(var(--y-container), 1); // 需要 App.vue 已引入主题
  padding: $size-lg;
  font-size: $size-base-text;
}

styles/index.scss 会输出全部工具类，不要在 uni.scss 或页面样式里重复引入。

工具类速查

命名规则

• 类名中的数字默认单位是 rpx：mt-24 → margin-top: 24rpx。
• 百分比类用 p 后缀：wp-50 → width: 50%，hp-50 → height: 50%。
• 透明度后缀 -1 ~ -9 对应 0.1 ~ 0.9：bgc-main-5 → 主色 50% 透明。
• 负值类名用双连字符：t--20 → top: -20rpx。
• 数值未做 0 值省略，mt-0 / p-0 均可用。

背景

白色、黑色、蒙版没有不透明基础类（没有 bgc-white），请用 bgc-white-9 这类透明度类，或自行写样式。

文字颜色

边框与圆角

bs-box（box-sizing: border-box）定义在 box.scss，和 bs-* 边框样式共用前缀，注意区分。

阴影

所有阴影类都使用 var(--y-shadow)，由 theme/light.scss（8% 黑）和 theme/dark.scss（60% 黑）内置定义。

Flex 布局

该文件只负责 Flex 子项属性，没有 d-flex；需要先加 d-flex。

间距

尺寸

定位

文本

字号与字重

显示与溢出

变换与动画

transform 类会互相覆盖，同一元素只保留最后一个 transform。需要组合变换时请自定义样式。

层级

注意前缀是 zinx- 而不是 z-；!important 会让层级难以被页面样式覆盖，使用前确认必要性。

预设样式

styles/global/preset_css.scss 会输出以下全局规则：

• 隐藏 WebKit 滚动条（H5 生效，小程序 WXSS 不支持该伪元素）。
• scroll-view .wx-scroll-view 关闭惯性滚动与滚动链（依赖微信内部类名，基础库升级可能失效）。
• 重置 button 的 margin / padding / border-radius / line-height，并去掉 ::after 边框。
• button[disabled] 透明度 0.5。
• .button-hover 按下态颜色（硬编码灰色，暗色模式下不协调）。
• .glass-bg / .glass-bg-press 玻璃拟态背景。
• .bs-box 设置 box-sizing: border-box。
• .as-ratio-1 设置 aspect-ratio: 1 / 1。

主题与暗黑模式

自动跟随系统

index.scss 在编译时把两套变量分别包进媒体查询：

@media (prefers-color-scheme: light) {
  @import "@/uni_modules/y-scss/theme/light.scss";
}
@media (prefers-color-scheme: dark) {
  @import "@/uni_modules/y-scss/theme/dark.scss";
}

微信小程序需要 manifest.json 中 "mp-weixin": { "darkmode": true }，否则媒体查询不会按预期触发。

自定义主题

方式一：改 SCSS 变量（编译期）

编辑 styles/default/color.scss 中的 $light-*-rgb / $dark-*-rgb，重新编译即可。升级插件会覆盖此文件，建议记录改动。

方式二：覆写 CSS 变量（运行时）

在 App.vue 引入之后追加覆盖：

@import "@/uni_modules/y-scss/index.scss";

page {
  --y-main: 255, 87, 34;
  --y-container: 250, 250, 250;
}

方式三：局部切换（使用 y-scss 组件）

插件自带一个可选的主题容器组件，可在指定区域强制明暗主题：

<y-scss theme="dark">
  <view class="bgc p-24">
    <text class="c-title">这块区域始终使用暗色变量</text>
  </view>
</y-scss>

theme 可选 auto（默认，跟随全局）、light、dark。组件会包裹一层 view，在 Flex 布局中使用时请给组件加 class 控制尺寸。

不使用组件时，也可以自己给容器加 class 覆盖变量：

// 页面或全局样式
.theme-dark {
  --y-bg: 18, 20, 32;
  --y-container: 26, 26, 46;
  --y-main: 0, 255, 255;
  --y-title: 255, 255, 255;
  --y-text: 204, 204, 204;
}

<view :class="['page', theme === 'dark' ? 'theme-dark' : '']">
  <!-- 子元素会继承 .theme-dark 上的变量 -->
</view>

注意：page 元素自身的背景不会随容器 class 改变，页面根节点需要铺满并设置 bgc；这套方案也不会覆盖 pages.json 的原生窗口背景色。

体积与裁剪

工具类是全量生成的，全部规则都会进入 app.wxss，所有页面无条件加载。按源码估算（未编译验证）：

对体积敏感的项目可以：

1. 调步长：把 width.scss / height.scss 的 $i * 2 改为 $i * 4 或 $i * 8，规则数直接减半或降到 1/4。
2. 缩范围：把循环上限从 750 / 500 降到实际用到的最大值（如 200）。
3. 删文件：在 styles/index.scss 中注释掉整块未使用的模块（如 transform.scss、z_index.scss）。
4. 只引变量：完全不用工具类时，只引入 styles/default/*.scss。

小程序主包上限 2MB，样式全量注入会占用可观体积。上线前建议查看 unpackage/dist/**/app.wxss 的实际大小。

已知限制与升级说明

1. *边框与阴影变量已统一到 `--y-**：边框色使用rgb(var(--y-))，阴影使用var(--y-shadow)；--y-shadow已内置在theme/light.scss（8% 黑）和theme/dark.scss（60% 黑）。若从旧版本升级，旧前缀的自定义变量不再被引用，需要改为--y-`。

2. 主题变量没有默认值兜底：--y-* 只在 @media (prefers-color-scheme: ...) 内声明。在不触发媒体查询的环境（部分 H5、未开启 darkmode 的小程序、部分模拟器）中，所有颜色类都会失效。上线前请在目标端实测。

3. page 被附加了全局布局样式：theme/light.scss 与 theme/dark.scss 都给 page 设置了 height: 100%; display: flex;（flex-direction 当前拼写为 colmun，实际不生效）。这会影响所有页面的根布局，如与项目布局冲突，可在 App.vue 中覆盖：

   @import "@/uni_modules/y-scss/index.scss";
   
   page {
    display: block;
    height: auto;
   }

4. 拼写类名：bs-soild（应为 bs-solid）、ws-nowarp（应为 ws-nowrap）、td-line-inherit（值误写为 line-through）、t-rotate--*（未取负值）为 v1.0.0 的实际实现。修正版本会保留旧类名作为别名，避免升级破坏现有页面。

5. 全局手动切换未内置：插件默认只跟随系统主题；App.vue 里通过 uni.onThemeChange + Storage 记录的 theme 不会自动影响全局样式。需要局部切换时可用 <y-scss theme="light|dark">，全局切换仍需自行覆写 page 变量。

6. 短类名有冲突风险：c- / w- / h- / m- / p- / b- / l- / r- / t- 等前缀非常短，容易与 UI 库、Tailwind / UnoCSS 或业务样式冲突。引入前建议全局搜索这些前缀的使用情况。

7. H5 / App / 其他小程序未验证：page 选择器在 H5 的映射、::-webkit-scrollbar、overflow: overlay、backdrop-filter 等在不同端表现不同。nvue 不支持 CSS 变量，不能使用本插件。

8. 依赖 @/ 别名：index.scss 内部用 @/uni_modules/... 引入主题文件。纯 Sass CLI 或非 uni-app 构建环境无法解析该别名，需要改为相对路径。

常见问题

Q：bgc-white 没有效果？ A：白色、黑色、蒙版只提供透明度版本（bgc-white-1..9、bgc-black-1..9、bgc-mask-1..9），没有不透明基础类。用 bgc-white-9，或自己写 background: #fff。

Q：shadow-md 没有效果？ A：它使用 --y-shadow，插件已内置；如果仍不生效，检查是否被其他 box-shadow 覆盖，或主题文件是否被正确引入。

Q：暗色模式不切换？ A：依次检查：manifest.json 是否开启 "darkmode": true；系统 / 开发者工具是否切到暗色；目标端是否支持 prefers-color-scheme。当前版本不支持 App 内手动切换。

Q：类名数字是 px 还是 rpx？ A：固定 rpx。750 设计稿上量到 24px，直接用 p-24（即 24rpx）。

Q：可以在 <style scoped> 里用吗？ A：工具类是全局样式，模板里写 class 就能生效。但 scoped 样式无法覆盖全局类，需要覆盖时用 :deep() 或非 scoped 的全局样式。

Q：为什么 mt-24 和 mtb-24 的间距看起来不一样？ A：mt-24 只设上边距；mtb-24 是 margin: 24rpx 0，上下都设。mlr-24 同理是左右。

Q：可以只引变量、不引工具类吗？ A：可以。只引入 styles/default/color.scss 和 styles/default/numerical.scss，它们只声明变量，不输出 CSS。

Q：组件 y-scss 需要注册吗？ A：不需要，easycom 会自动注册。它是可选的主题容器：<y-scss theme="dark"> 可让局部区域强制使用暗色变量；不使用时不影响任何样式。

二次开发

新增一组工具类

1. 在 styles/global/ 下新建 xxx.scss。
2. 在 styles/index.scss 末尾追加 @import "./global/xxx.scss";。
3. 重新编译，确认 app.wxss 中出现对应规则。

调整生成范围

所有批量类都用 @for 生成，类名数字即属性值：

// 例：把宽度从 0..750、步长 2rpx 改为 0..400、步长 4rpx
@for $i from 0 through 100 {
  $value: $i * 4;
  .w-#{$value} { width: #{$value}rpx; }
}

修改时注意同步 min-w-* / max-w-* 的循环，避免类名与值不一致。

新增主题色

1. styles/default/color.scss：新增 $light-xxx-rgb 与 $dark-xxx-rgb。
2. theme/light.scss、theme/dark.scss：新增 --y-xxx: #{$light-xxx-rgb};。
3. styles/global/color.scss、background.scss、border.scss：按现有模式添加工具类。
4. 更新本 README 的变量表。

命名建议

现有类名没有统一前缀，新增类建议加 y- 前缀（如 y-p-24），降低与宿主项目、第三方库冲突的概率。

更新日志

见 changelog.md。

许可

本项目未声明开源许可证。如需商用、分发或二次发布，请先与作者确认授权方式。