主题变量和颜色

本库设计了一套完整的主题配置系统，包含空间大小、颜色和文本样式等配置，全局配置值，组件动态读取。

你可以根据需要进行自定义修改扩展。

主题配置系统可以通过全局配置/局部配置，可以响应式修改主题变量，从而实现动态切换主题。

提示

本库的组件默认单位为 rpx。

默认主题说明

默认主题配置文件位于 /components/theme/Theme.ts，该文件定义了默认的主题配置项。

默认主题配置主要包含三个部分：空间大小配置定义了组件中使用的标准间距尺寸

颜色配置 (colorConfigs): 颜色配置分为多个分类，每个分类下定义了不同场景使用的颜色，请参考示例页面查看具体颜色值。

默认颜色 (default)
按下颜色 (pressed)
遮罩颜色 (mask)
背景颜色 (background)
文本颜色 (text)
边框颜色 (border)

文字配置 (textConfigs): 文字配置定义了组件中使用的标准字体尺寸，当使用 Text 组件时，可以快速选择预设好的文字配置。
主题变量默认设置 (varOverrides):

间距预设 (spaceSize): 用于 Width, Height 等属性的值。
字体大小 (fontSize)：字体大小配置定义了组件中使用的标准字体尺寸。

修改主题

你可以在 \src\components\theme\Theme.ts 中直接修改主题配置，但考虑到您后续如果需要更新库版本，可能会覆盖您的修改，建议通过 configTheme 函数在 App.vue 中修改主题配置：

vue

<script setup lang="ts">
import { configTheme } from './components/theme/ThemeDefine';

//修改默认主题颜色
configTheme((theme) => {
  // 修改主要颜色
  theme.colorConfigs.default.primary = '#ff8719';
  theme.colorConfigs.pressed.primary = '#b86212';
  
  // 修改文本颜色
  theme.colorConfigs.text.title = '#333333';
  
  // 修改字体大小
  theme.varOverrides.fontSize.large = 42;
  
  return theme;
});
</script>

主题变量/颜色

主题变量：每个组件可以设置自己的主题变量，用于从全局或者局部读取配置来自定义组件的样式。

通过主题变量可以方便实现：

修改内置组件的样式或者颜色
批量修改某块组件的样式
动态颜色

本库的组件主题变量都是以组件名称开头的，例如 ProgressTextFontSize 是进度条组件的字体大小变量。关于具体组件的主题变量，请参考各组件文档中的主题变量部分。

如果您在组件中需要使用主题变量，可以使用 propGetThemeVar、resolveThemeColor、DynamicColor 等函数来获取主题变量：

propGetThemeVar

用于组件中的props获取主题变量作为默认值。

import { propGetThemeVar } from '../theme/ThemeDefine';
const props = withDefaults(defineProps<AvatarProps>(), {
  background: () => propGetThemeVar('AvatarBackground', 'background.imageBox'),
  textColor: () => propGetThemeVar('AvatarTextColor', 'text.content'),
  size: () => propGetThemeVar('AvatarSize', 70),
  radius: () => propGetThemeVar('AvatarRadius', 0),
  round: () => propGetThemeVar('AvatarRound', true),
});

themeContext.xxx

手动获取获取主题变量，颜色，大小。建议包裹在 computed 中使用。

resolveThemeSize：获取主题变量，大小。
resolveThemeColor：获取主题颜色。

getVar：获取主题变量。

import { useTheme } from '../theme/ThemeDefine';

const themeContext = useTheme();
const barColor = computed(() => themeContext.resolveThemeColor('ProgressProgressColor', 'primary'));

DynamicXXX

DynamicXXX 系列函数需要与 useThemeStyle，useThemeStyles 函数配合使用，可以组建动态响应式样式。

DynamicColor：获取主题颜色。
DynamicVar：获取主题变量。
DynamicSize：获取主题变量，大小。
DynamicSize2：获取主题变量，大小，适用于 padding, margin 等有两个值的情况。

const themeStyles = themeContext.useThemeStyles({
  progressTextPill: {
    width: DynamicSize('ProgressTextWidth', 80),
    textAlign: DynamicVar('ProgressTextAlign', 'center'),
    padding: DynamicSize2('ProgressTextPaddingVertical', 'ProgressTextPaddingHorizontal', 2, 2),
    borderRadius: DynamicSize('ProgressTextBorderRadius', 20),
    fontSize: DynamicSize('ProgressTextFontSize', 24),
    color: DynamicColor('ProgressTextColor', 'white'),
  },
});

组件级主题变量/颜色

你也可以使用 ProvideVar 组件在局部统一覆盖组件的主题变量，例如下方代码 ProvideVar 下的 GridItem 组件全部使用提供的主题变量：

vue

<template>
  <ProvideVar :vars="{
    GridItemIconSize: 90,
    GridItemBackgroundColor: 'transparent',
  }">
    <Grid :borderGrid="false" :mainAxisCount="4">
      <GridItem title="地图" icon="https://mn.wenlvti.net/uploads/20250326/75fad9e48686483dad24144b62bc5b13.png" touchable @click="navTo('/pages/inhert/map/index')" />
      <GridItem title="文物" icon="https://mn.wenlvti.net/uploads/20250326/bae40c527a2e517f59e2f39835ea6993.png" touchable @click="navTo('/pages/inhert/artifact/list')" />
      <GridItem title="非遗" icon="https://mn.wenlvti.net/uploads/20250326/cb0ebed5768e6cedb51492916678b90e.png" touchable @click="navTo('/pages/inhert/intangible/list')" />
    </Grid>
  </ProvideVar>
</template>

<script setup lang="ts">
import ProvideVar from './components/theme/ProvideVar.vue';
</script>

主题变量和颜色 ​

提示 ​

默认主题说明 ​

修改主题 ​

主题变量/颜色 ​

propGetThemeVar ​

themeContext.xxx ​

DynamicXXX ​

组件级主题变量/颜色 ​