@composy/color-vue

@composy/color-vue

@composy/color-vue 是 @composy/color-core 的 Vue 3 适配层，只负责在 Vue 运行时中封装核心能力，不重复实现颜色核心逻辑。

当前能力分析

当前 vue 包主要提供四类能力：

• Vue 组件：ThemeColorPicker、ThemeModeSwitcher。
• Vue composables：useColor、useColorTheme、useTheme、useThemeMode 等。
• 原生 Vue Plugin：createColorPlugin()。
• @composy/engine-core 适配插件：createColorEnginePlugin()。

本次整理后，所有运行时安装逻辑统一收敛到同一条链路：

• src/plugin/createColorRuntime.ts
• src/plugin/installColorApp.ts
• src/plugin/nativePlugin.ts
• src/plugins/enginePlugin.ts

这意味着：

• 原生 Vue Plugin 与 engine plugin 共用同一套 runtime 模型。
• app 上已安装过的颜色 runtime 会被 engine plugin 复用，不会重复创建状态实例。
• 组件注册、provide、全局属性挂载和卸载清理都走统一实现。

目录结构

src/
  index.ts
  components/
    themeColorPicker/
    themeModeSwitcher/
  composables/
  compat/
    paletteDisplay.ts
    themeProvider.ts
  context/
    index.ts
    injectionKeys.ts
  plugin/
    index.ts
    createColorRuntime.ts
    installColorApp.ts
    nativePlugin.ts
    types.ts
  plugins/
    index.ts
    enginePlugin.ts
  styles/
    index.less
  utils/
    index.ts
    themeModeDom.ts

结构约束：

• src/index.ts 是唯一根入口。
• Vue 特有能力只依赖 @composy/color-core 与 vue 本身。
• compat/ 仅保留历史兼容 re-export，不承载真实实现。

安装

pnpm add @composy/color-vue @composy/color-core vue

原生 Vue Plugin 用法

import { createColorPlugin } from '@composy/color-vue'
import { createApp } from 'vue'
import App from './App.vue'

const app = createApp(App)

app.use(
  createColorPlugin({
    primaryColor: '#1677ff',
    mode: 'auto',
    globalComponents: true,
    globalProperties: true,
    persistence: {
      enabled: true,
      key: 'demo-color-theme',
    },
  }),
)

app.mount('#app')

安装后可以直接使用：

import { useColor, useThemeMode } from '@composy/color-vue'

const { primaryColor, applyTheme } = useColor()
const { effectiveTheme, setDark } = useThemeMode()

void primaryColor
void applyTheme
void effectiveTheme
void setDark

@composy/engine-core plugin 用法

import { createColorEnginePlugin } from '@composy/color-vue/plugins'
import { createVueEngine } from '@composy/engine-vue'

const engine = createVueEngine({
  plugins: [
    createColorEnginePlugin({
      primaryColor: '#1677ff',
      mode: 'auto',
      globalComponents: true,
      persistence: {
        enabled: true,
        key: 'engine-color-theme',
      },
    }),
  ],
})

void engine

如何同时兼容原生 Vue Plugin 与 engine plugin

兼容策略如下：

1. createColorRuntime() 组合 Color Palette 适配器与 @composy/theme-core 的 ThemeModeManager；适配器复用同一个 Theme Core Runtime，不重复持有模式、系统偏好或 DOM 渲染器。
2. installColorApp() 负责把 runtime 安装到 Vue app，包括：
   • provide
   • 全局属性挂载
   • 全局组件注册
   • unmount 时的资源清理
3. createColorPlugin() 只是原生 Vue Plugin 外壳，内部调用 createColorRuntime() + installColorApp()。
4. createColorEnginePlugin() 在 engine 场景下会：
   • 优先复用已有 Vue app 上已安装的 runtime。
   • 如果 app 尚未创建，则等待 app:created 事件后再安装。
   • 把 Color Palette 状态同步回 engine state / events / plugin api。

因此，两种接入方式可以共存；Color 只维护颜色域状态，模式、系统偏好、主题 token 与 DOM 渲染由 Theme Core 统一维护。

现有 Runtime 的安装与所有权

installColorRuntime(app, runtime) 默认将传入实例视为 borrowed：App 卸载时会移除自身绑定，但不会销毁由调用方或 Engine 持有的 Runtime。若 Runtime 专属于该 App，可显式传入 { ownership: 'owned' }；此时会先运行 Vue 组件卸载钩子，再销毁 Runtime。createColorPlugin() 创建的 Runtime 自动采用 owned 生命周期。

同一个 Vue App 内，useThemeMode()、useColorTheme() 与 ThemeModeProvider 会复用 App 级的 ThemeModeManager，由它统一同步文档模式，避免多个 composable 重复写入 DOM。不同 App 各自持有独立的模式管理器。

useColorTheme() 会把 ColorInput（包括 RGB/HSL 对象、数组和 Color 实例）规范化为可持久化的 CSS 颜色字符串；无效或损坏的本地存储值会回退到 primaryColor 初始值，避免主题生成被坏数据中断。

Engine API 默认使用 register(apiObject)。若旧 Engine 只支持 register(name, apiObject)，请传入 apiRegistration: 'named'；已存在同名 API 时插件会拒绝安装，并保留原注册项。

import { createColorRuntime, installColorRuntime } from '@composy/color-vue'

const runtime = createColorRuntime({ prefix: 'brand', storageKey: 'brand-theme' })
installColorRuntime(app, runtime, { ownership: 'owned' })

构建产物

通过 @composy/builder 与工作区 postbuild 统一产出：

• dist/：UMD 单文件产物。
• es/：ESM + CSS 产物，适合直接消费。
• esm/：ESM + Less 产物，保留样式源码。
• lib/：CommonJS 产物。

测试

pnpm type-check
pnpm test:run
pnpm test:coverage
pnpm build

当前新增测试重点覆盖：

• 原生 Vue Plugin 注入链。
• engine plugin 的 runtime 复用与延迟挂载。
• ThemeColorPicker / ThemeModeSwitcher 的 UI 行为。
• runtime 复用场景对应的性能路径。

旧 Color 主题 API 迁移

通用主题运行时请从 @composy/theme-core 导入 ThemeManager。旧 Color API（BaseThemeAdapter、Color ThemeManager、ThemeModeManager）仍由 @composy/color-vue/theme 以弃用兼容 facade 提供；旧 Color Engine 插件由 @composy/color-vue/engine 提供。新的 Vue Engine 集成使用 @composy/color-vue/plugins。完整迁移映射见 Color Runtime Migration。

import { createColorEnginePlugin } from '@composy/color-vue/engine'
import { BaseThemeAdapter } from '@composy/color-vue/theme'
import { ThemeManager } from '@composy/theme-core'

void createColorEnginePlugin
void BaseThemeAdapter
void ThemeManager

Color Core 不再导出这些运行时类或旧 Engine 插件。

兼容导出

为了兼容历史导入路径，仍保留：

• @composy/color-vue/themeProvider
• @composy/color-vue/paletteDisplay
• @composy/color-vue/theme
• @composy/color-vue/engine

前两个入口只做薄 re-export，真实实现收敛在 plugin/ 与 components/。后两个入口是 deprecated facade，用于迁移旧 Color 主题与 Engine API。

🔗 相关链接

• @composy/color-core：框架无关的颜色核心层。
• 颜色家族根说明：packages/color 子模块总览与构建编排。