更新记录

1.0.0（2026-01-20） 下载此版本

新功能

平台兼容性

uni-app(4.84)

其他

Shadcn UI 主题系统 for Uni-app

将现代化的 Shadcn UI 设计体系引入 uni-app 生态。

为什么选择此方案？

1. 跨端基座：Uni-app

利用 Uni-app 强大的跨端能力，编写一套代码即可发布到 iOS、Android、Web 及各大主流小程序平台。

2. 设计语言：Shadcn UI

采用目前 SaaS 与 AI 领域最流行的极简美学设计。告别传统组件库的沉重感，拥抱 Clean Design。

3. 完美融合：Lrb Shadcn Theme

本插件是连接二者的桥梁。我们没有重新造轮子编写一套新的组件库，而是通过深度定制的 CSS 变量和样式覆盖，将 uni-app 原生组件和 uni-ui 扩展组件“整容”为 Shadcn 风格。

优势：

• 🚀 零成本迁移：已有使用 uni-ui 的项目可直接接入，无需改动业务逻辑。
• ⚡ 原生性能：底层依然是官方组件，保持最佳的兼容性和性能。
• 🎨 完整主题：内置 Light/Dark 模式及 Catppuccin 多彩主题。

特性

• 🎨 Shadcn 风格化：通过 CSS 变量覆盖 uni-app 内置组件和 uni-ui 组件
• 🌙 多主题支持：内置 Shadcn Default (亮/暗) + Catppuccin (4 种风格)
• 🌈 14 种强调色：Catppuccin 主题支持 14 种 accent 颜色
• 💾 持久化存储：主题偏好自动保存到本地
• 📱 跨平台：支持 H5、微信小程序、支付宝小程序、App
• 🔄 跟随系统：可选跟随系统暗色模式

安装

通过 HBuilderX 插件市场导入，或手动复制到项目的 uni_modules/ 目录。

前置配置

1. manifest.json 配置

为了支持系统主题检测，需要在 manifest.json 中开启 darkmode：

{
  "app-plus": {
    "darkmode": true
  },
  "mp-weixin": {
    "darkmode": true
  },
  "h5": {
    "darkmode": true
  }
}

2. PostCSS 配置（可选）

如果使用 OKLCH 颜色格式，需要配置 PostCSS 转换：

bun add -d @csstools/postcss-oklab-function

// vite.config.ts
import postcssOklabFunction from '@csstools/postcss-oklab-function'

export default defineConfig({
  css: {
    postcss: {
      plugins: [postcssOklabFunction({ preserve: false })]
    }
  }
})

使用方法

1. 导入样式

在 App.vue 的 <style> 中导入：

/* 完整样式（推荐） */
@import '@/uni_modules/lrb-shadcn-theme/common/styles/index.css';

/* 或仅导入主题变量 */
@import '@/uni_modules/lrb-shadcn-theme/common/styles/themes/index.css';

2. 初始化主题

在 App.vue 中：

<script setup lang="ts">
import { onLaunch, onShow } from '@dcloudio/uni-app'
import { useTheme } from '@/uni_modules/lrb-shadcn-theme/composables'

const { initTheme, watchSystemTheme, startDOMObserver, applyThemeToDOM } = useTheme()

onLaunch(() => {
  initTheme()
  watchSystemTheme()
  startDOMObserver() // H5 端自动应用主题到新页面
})

onShow(() => {
  applyThemeToDOM()
})
</script>

3. 使用主题切换组件

全局浮动主题按钮（推荐）

项目内置了 theme-floating-button 组件，支持拖拽悬浮和主题选择。

<template>
  <theme-floating-button />
</template>

主题选择器（仅面板）

如果你需要自定义触发方式，可以直接使用核心选择器组件：

<template>
  <button @click="openPicker">选择主题</button>
  <theme-picker ref="pickerRef" />
</template>

<script setup>
import { ref } from 'vue'
const pickerRef = ref(null)
const openPicker = () => pickerRef.value?.open()
</script>

4. 编程式切换

import { useTheme } from '@/uni_modules/lrb-shadcn-theme/composables'

const { setTheme, setAccent, toggleDarkMode, isDark } = useTheme()

// 切换亮/暗模式
toggleDarkMode()

// 切换到指定主题
setTheme('catppuccin-mocha', 'blue')

// 仅切换强调色
setAccent('pink')

可用主题

内置主题

Catppuccin 主题包

Catppuccin 强调色

rosewater, flamingo, pink, mauve, red, maroon, peach, yellow, green, teal, sky, sapphire, blue, lavender

小程序端注意事项

小程序端需要在每个页面的根元素上绑定 themeClass：

<template>
  <view :class="themeClass">
    <!-- 页面内容 -->
  </view>
</template>

<script setup>
import { usePageTheme } from '@/uni_modules/lrb-shadcn-theme/composables'
const { themeClass } = usePageTheme()
</script>

H5 端使用 MutationObserver 自动检测，无需手动绑定。

API 参考

useTheme()

usePageTheme()

页面级主题初始化，简化版的 useTheme()。

import { usePageTheme } from '@/uni_modules/lrb-shadcn-theme/composables'

const { themeClass, applyThemeToDOM } = usePageTheme()

useThemeColors()

getSubpackageStaticPath()

处理分包静态资源路径的跨平台差异。

import { getSubpackageStaticPath } from '@/uni_modules/lrb-shadcn-theme/composables'

// 获取分包静态资源路径
const imagePath = getSubpackageStaticPath('pagesB', 'product.jpg')
// H5 dev: /src/pagesB/static/product.jpg
// H5 build: /static/product.jpg
// 小程序: /pagesB/static/product.jpg

getSubpackageStaticPaths()

批量获取分包静态资源路径。

import { getSubpackageStaticPaths } from '@/uni_modules/lrb-shadcn-theme/composables'

const paths = getSubpackageStaticPaths('pagesB', ['a.jpg', 'b.jpg', 'c.jpg'])
// { 'a.jpg': '/pagesB/static/a.jpg', 'b.jpg': '...', 'c.jpg': '...' }

usePickerMaskStyle()

为 picker-view 组件提供小程序端遮罩层主题适配。

问题背景：小程序端 picker-view 的遮罩层是原生渲染的，默认白色渐变在暗色主题下非常突兀，且无法通过 CSS 覆盖。

使用方式：

<template>
  <picker-view :mask-style="pickerMaskStyle" @change="onChange">
    <picker-view-column>
      <view v-for="item in options" :key="item.value">{{ item.label }}</view>
    </picker-view-column>
  </picker-view>
</template>

<script setup>
import { usePickerMaskStyle } from '@/uni_modules/lrb-shadcn-theme/composables'

const { pickerMaskStyle } = usePickerMaskStyle()
</script>

注意事项：

• H5 端已通过全局 CSS 处理，此 composable 主要用于小程序兼容
• 必须在模板中显式绑定 :mask-style，无法全局自动应用
• 自动跟随当前主题的背景色变化

useSwipeMouseSupport() (H5 专用)

为 uni-swipe-action 组件添加 H5 PC 端鼠标滑动支持。

问题背景：uni-ui 的 uni-swipe-action 组件只绑定了触摸事件，在 PC 浏览器上无法通过鼠标拖拽触发滑动。

使用方式：

<script setup>
import { onMounted, onUnmounted } from 'vue'

// #ifdef H5
let swipeCleanup: (() => void) | null = null
onMounted(async () => {
  const { useSwipeMouseSupport } = await import('@/uni_modules/lrb-shadcn-theme/composables/useSwipeMouseSupport')
  swipeCleanup = useSwipeMouseSupport()
})
onUnmounted(() => swipeCleanup?.())
// #endif
</script>

注意事项：

• 仅在 H5 PC 端生效，自动检测触摸屏环境
• 需要配合条件编译使用，避免小程序端报错
• 在使用 uni-swipe-action 的页面中调用

自定义主题

可以通过添加新的 CSS 文件扩展主题：

/* my-theme.css */
.theme-my-custom,
page.theme-my-custom {
  --background: #your-color;
  --foreground: #your-color;
  /* ... 其他变量 */
}

然后在 useTheme.ts 的 THEMES 数组中注册新主题。

其他

插件演示显示需要下载本人另一款图标插件 ·lrb-svg-icons·

许可证

MIT