@cimom/vben-core-preferences

用户偏好设置管理工具，提供了完整的偏好设置管理功能，包括主题、语言、布局等系统配置的存储、读取和更新。

安装

npm install @cimom/vben-core-preferences

基本使用

import {
  preferences,
  updatePreferences,
  resetPreferences,
  initPreferences,
  usePreferences,
} from '@cimom/vben-core-preferences';

// 初始化偏好设置（应用启动时调用）
initPreferences();

// 读取偏好设置
console.log(preferences.theme.mode); // 'light' | 'dark'

// 更新偏好设置
updatePreferences({
  theme: {
    mode: 'dark',
  },
});

// 重置偏好设置为默认值
resetPreferences();

// 在组件中使用
const { theme, updateTheme } = usePreferences();

API 参考

核心函数

| 函数名 | 参数 | 返回值 | 说明 | | --- | --- | --- | --- | | initPreferences | options?: PreferencesOptions | void | 初始化偏好设置 | | updatePreferences | newPreferences: DeepPartial<Preferences> | void | 更新偏好设置 | | resetPreferences | - | void | 重置偏好设置为默认值 | | clearPreferencesCache | - | void | 清除偏好设置缓存 |

偏好设置对象

preferences 是一个响应式对象，包含所有用户偏好设置。

// 偏好设置结构
interface Preferences {
  // 主题相关设置
  theme: {
    // 主题模式: 'light' | 'dark'
    mode: ThemeModeType;
    // 主题颜色
    primaryColor: string;
    // 主题颜色预设
    primaryColorPresets: string[];
    // 内容宽度: 'full' | 'fixed'
    contentWidth: ContentWidthType;
    // 是否使用顶栏
    useTopbar: boolean;
    // 是否使用面包屑
    useBreadcrumb: boolean;
    // 是否使用标签页
    useTabbar: boolean;
    // 是否使用页脚
    useFooter: boolean;
    // 色弱模式
    colorWeak: boolean;
    // 灰色模式
    grayMode: boolean;
  };

  // 多语言设置
  locale: {
    // 当前语言: 'zh-CN' | 'en-US' | ...
    lang: string;
    // 是否跟随系统
    followSystem: boolean;
  };

  // 动画设置
  animation: {
    // 是否开启动画
    enable: boolean;
    // 动画类型
    type: AnimationType;
  };

  // 标签页设置
  tabs: {
    // 是否缓存标签页
    cache: boolean;
    // 是否显示快捷操作
    showQuick: boolean;
    // 是否显示刷新按钮
    showRefresh: boolean;
    // 标签页样式
    style: TabsStyleType;
  };

  // 头部设置
  header: {
    // 头部高度
    height: number;
    // 头部模式: 'fixed' | 'static' | 'auto' | 'auto-scroll'
    mode: HeaderModeType;
  };

  // 菜单设置
  menu: {
    // 菜单宽度
    width: number;
    // 菜单折叠时宽度
    collapsedWidth: number;
    // 混合菜单宽度
    mixedWidth: number;
    // 菜单模式: 'vertical' | 'horizontal' | 'inline'
    mode: MenuModeType;
    // 菜单主题: 'light' | 'dark'
    theme: ThemeModeType;
    // 是否折叠
    collapsed: boolean;
    // 是否悬停展开
    expandOnHover: boolean;
  };

  // 其他设置
  other: {
    // 是否保持在线
    keepAlive: boolean;
    // 是否显示面板设置
    showSettingPanel: boolean;
    // 是否显示返回顶部
    showBackTop: boolean;
    // 是否显示全屏按钮
    showFullScreen: boolean;
  };
}

组合式 API

usePreferences

提供了访问和更新偏好设置的组合式 API。

const {
  // 所有偏好设置
  preferences,

  // 主题相关
  theme,
  updateTheme,

  // 多语言相关
  locale,
  updateLocale,

  // 动画相关
  animation,
  updateAnimation,

  // 标签页相关
  tabs,
  updateTabs,

  // 头部相关
  header,
  updateHeader,

  // 菜单相关
  menu,
  updateMenu,

  // 其他设置相关
  other,
  updateOther,

  // 重置所有设置
  resetPreferences,
} = usePreferences();

示例：

import { usePreferences } from '@cimom/vben-core-preferences';

// 在组件中使用
const { theme, updateTheme } = usePreferences();

// 切换主题模式
function toggleTheme() {
  updateTheme({
    mode: theme.value.mode === 'light' ? 'dark' : 'light',
  });
}

// 更新主题颜色
function changeThemeColor(color: string) {
  updateTheme({
    primaryColor: color,
  });
}

常量和类型

主题模式

import { ThemeModeType } from '@cimom/vben-core-preferences';

// ThemeModeType = 'light' | 'dark'

内容宽度类型

import { ContentWidthType } from '@cimom/vben-core-preferences';

// ContentWidthType = 'full' | 'fixed'

头部模式类型

import { HeaderModeType } from '@cimom/vben-core-preferences';

// HeaderModeType = 'fixed' | 'static' | 'auto' | 'auto-scroll'

菜单模式类型

import { MenuModeType } from '@cimom/vben-core-preferences';

// MenuModeType = 'vertical' | 'horizontal' | 'inline'

动画类型

import { AnimationType } from '@cimom/vben-core-preferences';

// AnimationType = 'zoom-fade' | 'zoom-out' | 'fade-slide' | 'fade' | 'fade-bottom' | 'fade-scale'

标签页样式类型

import { TabsStyleType } from '@cimom/vben-core-preferences';

// TabsStyleType = 'default' | 'chrome'

高级用法

自定义默认偏好设置

可以通过 defineOverridesPreferences 函数来覆盖默认的偏好设置。

// 在你的应用中
import { defineOverridesPreferences } from '@cimom/vben-preferences';

// 定义覆盖的默认偏好设置
const customPreferences = defineOverridesPreferences({
  theme: {
    mode: 'dark',
    primaryColor: '#1677ff',
  },
  locale: {
    lang: 'zh-CN',
  },
});

// 这些设置会覆盖 @cimom/vben-core-preferences 中的默认设置

监听偏好设置变化

可以通过 preferencesManager 来监听偏好设置的变化。

import { preferencesManager } from '@cimom/vben-core-preferences';

// 监听所有偏好设置变化
const unsubscribe = preferencesManager.subscribe((newPreferences) => {
  console.log('偏好设置已更新:', newPreferences);
});

// 取消监听
unsubscribe();

// 监听特定路径的偏好设置变化
const unsubscribeTheme = preferencesManager.subscribePath(
  'theme.mode',
  (newMode) => {
    console.log('主题模式已更新:', newMode);
  },
);

// 取消监听
unsubscribeTheme();

CSS 变量更新

偏好设置变化时会自动更新相关的 CSS 变量。

// 主题模式变化时，会自动更新以下 CSS 变量
document.documentElement.style.setProperty('--theme-mode', 'dark');

// 主题颜色变化时，会自动生成并更新颜色系列
document.documentElement.style.setProperty('--primary-color', '#1677ff');
document.documentElement.style.setProperty('--primary-color-hover', '#4096ff');
// ...其他颜色变量

示例

主题切换

<template>
  <div>
    <button @click="toggleTheme">
      {{ theme.mode === 'light' ? '切换到暗色模式' : '切换到亮色模式' }}
    </button>

    <div class="color-pickers">
      <div
        v-for="color in theme.primaryColorPresets"
        :key="color"
        :style="{ backgroundColor: color }"
        :class="{ active: theme.primaryColor === color }"
        @click="updateTheme({ primaryColor: color })"
      ></div>
    </div>
  </div>
</template>

<script setup lang="ts">
import { usePreferences } from '@cimom/vben-core-preferences';

const { theme, updateTheme } = usePreferences();

function toggleTheme() {
  updateTheme({
    mode: theme.value.mode === 'light' ? 'dark' : 'light',
  });
}
</script>

<style scoped>
.color-pickers {
  display: flex;
  gap: 8px;
  margin-top: 16px;
}

.color-pickers > div {
  width: 20px;
  height: 20px;
  border-radius: 4px;
  cursor: pointer;
  transition: transform 0.2s;
}

.color-pickers > div.active {
  transform: scale(1.2);
  box-shadow:
    0 0 0 2px white,
    0 0 0 4px currentColor;
}
</style>

语言切换

<template>
  <select v-model="currentLang" @change="changeLang">
    <option value="zh-CN">简体中文</option>
    <option value="en-US">English</option>
  </select>
</template>

<script setup lang="ts">
import { ref, watch } from 'vue';
import { usePreferences } from '@cimom/vben-core-preferences';

const { locale, updateLocale } = usePreferences();
const currentLang = ref(locale.value.lang);

function changeLang() {
  updateLocale({
    lang: currentLang.value,
    followSystem: false,
  });
}

// 监听语言变化
watch(
  () => locale.value.lang,
  (newLang) => {
    currentLang.value = newLang;
  },
);
</script>

布局设置面板

<template>
  <div class="settings-panel">
    <h3>布局设置</h3>

    <div class="setting-item">
      <span>内容宽度</span>
      <div class="setting-controls">
        <label>
          <input
            type="radio"
            :checked="theme.contentWidth === 'fixed'"
            @change="updateTheme({ contentWidth: 'fixed' })"
          />
          固定宽度
        </label>
        <label>
          <input
            type="radio"
            :checked="theme.contentWidth === 'full'"
            @change="updateTheme({ contentWidth: 'full' })"
          />
          流式宽度
        </label>
      </div>
    </div>

    <div class="setting-item">
      <span>显示标签页</span>
      <div class="setting-controls">
        <input
          type="checkbox"
          :checked="theme.useTabbar"
          @change="updateTheme({ useTabbar: !theme.useTabbar })"
        />
      </div>
    </div>

    <div class="setting-item">
      <span>菜单主题</span>
      <div class="setting-controls">
        <label>
          <input
            type="radio"
            :checked="menu.theme === 'light'"
            @change="updateMenu({ theme: 'light' })"
          />
          亮色
        </label>
        <label>
          <input
            type="radio"
            :checked="menu.theme === 'dark'"
            @change="updateMenu({ theme: 'dark' })"
          />
          暗色
        </label>
      </div>
    </div>

    <button @click="resetPreferences">恢复默认设置</button>
  </div>
</template>

<script setup lang="ts">
import { usePreferences } from '@cimom/vben-core-preferences';

const { theme, updateTheme, menu, updateMenu, resetPreferences } =
  usePreferences();
</script>

<style scoped>
.settings-panel {
  padding: 16px;
  border: 1px solid #eee;
  border-radius: 8px;
}

.setting-item {
  display: flex;
  justify-content: space-between;
  align-items: center;
  margin-bottom: 12px;
}

.setting-controls {
  display: flex;
  gap: 8px;
}
</style>