更新记录

1.0.1（2026-04-18）

修改为组合式

1.0.0（2026-04-18）

UniApp 主题设置插件，支持字体缩放（7级）、主题色切换（5种）、深色/浅色模式

平台兼容性

uni-app(4.62)

其他

# YxTheme Plugin - 主题设置插件

简介

uni-app 主题设置插件，支持：

• 字体大小：7级字体缩放（20-40rpx 基准，7级偏移）
• 深浅模式：浅色/深色主题切换
• 主题色：5种预设主题色（蓝/橙/红/绿/紫）
• 语义化颜色：9种语义化颜色（主色/辅助/点缀/成功/警告/危险/信息/浅色/深色），每种5级阶梯

安装

1. 将 uni_modules/yx-theme 复制到你的 uni-app 项目中
2. 在 App.vue 中引入公共样式：

<style>
@import '@/uni_modules/yx-theme/css/theme.css';
</style>

3. 在 pages.json 中配置 easycom（可选，组件自动引入）：

{
  "easycom": {
    "autoscan": true,
    "custom": {
      "^theme-(.*)": "@/uni_modules/yx-theme/components/theme-$1/theme-$1.vue"
    }
  }
}

快速开始

1. 页面根组件注入 CSS 变量

每个页面的根组件需要绑定 :style="themeStore.getStyle()"：

<template>
  <view class="page" :style="themeStore.getStyle()">
    <!-- 页面内容 -->
    <text class="font-base text-1">示例文字</text>
    <view class="bg-2 p-20">
      <text class="primary-text">主色文字</text>
    </view>
  </view>
</template>

<script setup>
import { createThemeStore } from '@/uni_modules/yx-theme/js_sdk'

const themeStore = createThemeStore()
</script>

2. 使用设置组件

<template>
  <view :style="themeStore.getStyle()">
    <!-- 设置组件 -->
    <yx-theme @change="onSettingsChange" />
  </view>
</template>

<script setup>
import { createThemeStore } from '@/uni_modules/yx-theme/js_sdk'

const themeStore = createThemeStore()

const onSettingsChange = (settings) => {
  // 设置变化时自动刷新
  themeStore.refresh()
}
</script>

3. JS API 直接设置

import { 
  setDarkMode, 
  setThemeColor, 
  setBaseFontSize,
  initThemeSettings 
} from '@/uni_modules/yx-theme/js_sdk'

// 初始化（自动应用导航栏颜色）
initThemeSettings()

// 设置深色模式
setDarkMode(true)

// 设置主题色
setThemeColor('red')  // blue/orange/red/green/purple

// 设置基准字体大小
setBaseFontSize(32)  // 范围：20-40

公共样式类参考

字体大小类（7级）

使用示例：

<text class="font-base">标准文字</text>
<text class="font-lg">大文字</text>

中性背景色类（跟随深浅模式）

使用示例：

<view class="bg-1">页面背景</view>
<view class="bg-2 p-20">卡片内容</view>

中性文字色类（跟随深浅模式）

使用示例：

<text class="text-1 font-base">主要标题</text>
<text class="text-3 font-sm">辅助说明</text>

9种语义化颜色类

每种颜色包含：

• 基准背景：.primary、.secondary、.success ...
• 5级阶梯背景：.primary-1 ~ .primary-5
• 基准文字：.primary-text、.secondary-text ...
• 5级阶梯文字：.primary-text-1 ~ .primary-text-5

使用示例：

<!-- 基准色按钮 -->
<view class="demo-btn primary">
  <text class="demo-btn-text font-md primary-text">主按钮</text>
</view>

<!-- 阶梯色展示 -->
<view class="color-step-item primary-1">
  <text class="step-text font-md primary-text-1">1</text>
</view>
<view class="color-step-item primary-3">
  <text class="step-text font-md primary-text-3">3</text>
</view>

布局类

/* Flex 布局 */
.row          /* 水平排列 */
.col          /* 垂直排列 */
.center       /* 水平垂直居中 */
.between      /* 两端对齐 */
.around       /* 平均分布 */
.flex-1       /* flex: 1 */
.wrap         /* 自动换行 */

/* 对齐 */
.align-start / .align-center / .align-end
.justify-start / .justify-center / .justify-between

/* 尺寸 */
.w-full / .h-full     /* 100% */
.w-screen / .h-screen /* 100vw/vh */

/* 间距 */
.p-20 / .px-20 / .py-20   /* padding */
.m-20 / .mt-20 / .mb-20   /* margin */

/* 圆角 */
.radius-4 / .radius-8 / .radius-12 / .radius-full

/* 文字 */
.bold / .normal
.text-left / .text-center / .text-right
.text-ellipsis / .text-ellipsis-2

完整使用示例

<template>
  <view class="page col" :style="themeStore.getStyle()">
    <!-- 设置组件 -->
    <yx-theme @change="onSettingsChange" />

    <!-- 页面内容 -->
    <scroll-view class="flex-1" scroll-y>
      <view class="p-20">
        <!-- 卡片示例 -->
        <view class="bg-2 radius-12 p-24 mb-20">
          <text class="font-lg bold text-1 mb-16">卡片标题</text>
          <text class="font-base text-2">这是卡片内容，使用中性背景色和文字色。</text>
        </view>

        <!-- 按钮组 -->
        <view class="row wrap gap-16">
          <view class="demo-btn primary">
            <text class="font-md primary-text">确定</text>
          </view>
          <view class="demo-btn secondary">
            <text class="font-md secondary-text">取消</text>
          </view>
          <view class="demo-btn success">
            <text class="font-md success-text">成功</text>
          </view>
          <view class="demo-btn danger">
            <text class="font-md danger-text">删除</text>
          </view>
        </view>

        <!-- 文字大小展示 -->
        <view class="bg-2 radius-12 p-24 mt-20">
          <text class="font-xs text-3">最小文字 xs</text>
          <text class="font-base text-1">标准文字 base</text>
          <text class="font-xl text-1">较大文字 xl</text>
        </view>
      </view>
    </scroll-view>
  </view>
</template>

<script setup>
import { createThemeStore } from '@/uni_modules/yx-theme/js_sdk'

const themeStore = createThemeStore()

const onSettingsChange = (settings) => {
  themeStore.refresh()
}
</script>

<style>
.demo-btn {
  padding: 20rpx 40rpx;
  border-radius: 8rpx;
}
</style>

API 参考

createThemeStore()

创建 themeStore 实例，用于页面中响应式获取 CSS 变量。

const themeStore = createThemeStore()

// 在模板中使用
// <view :style="themeStore.getStyle()">

// 设置变化后刷新
themeStore.refresh()

// 监听设置变化
themeStore.onChange((settings) => {
  console.log('设置变化:', settings)
})

setDarkMode(isDark, options)

设置深色/浅色模式。

setDarkMode(true)  // 深色模式
setDarkMode(false) // 浅色模式

setThemeColor(colorKey)

设置主题色。

setThemeColor('blue')    // 蓝色
setThemeColor('orange')  // 橙色
setThemeColor('red')     // 红色
setThemeColor('green')   // 绿色
setThemeColor('purple')  // 紫色

setBaseFontSize(size)

设置基准字体大小。

setBaseFontSize(28)  // 范围：20-40

initThemeSettings(options)

初始化插件，自动应用导航栏颜色。

// 在 App.vue 的 onLaunch 中调用
import { initThemeSettings } from '@/uni_modules/yx-theme/js_sdk'

onLaunch() {
  initThemeSettings()
}

文件结构

uni_modules/yx-theme/
├── js_sdk/
│   └── index.js          # JS SDK，包含所有 API
├── css/
│   └── theme.css         # 公共样式类
├── components/
│   └── yx-theme/
│       └── yx-theme.vue  # 设置组件
└── README.md             # 本文件

注意事项

1. 必须在每个页面根组件使用 :style="themeStore.getStyle()" 注入 CSS 变量
2. 所有样式通过公共类名使用，不要在组件中写死颜色或字体大小
3. 设置组件的 @change 事件中调用 themeStore.refresh() 刷新样式
4. 深色/浅色模式只影响中性背景色（.bg-1~.bg-5），不影响语义化颜色