Skip to content

color 颜色配置 ​

17:43

说明 ​

$u.color 是响应式主题色对象,包含各语义色的主色、按压、禁用、浅底档位以及文字、背景、边框等令牌;hexToRgba、mixColor 负责色值运算,isThemeColor、getThemeColor 负责预设主题名的判断与取色。

示例 ​

六个色板小节复用同一段 codes.palette 源码,实际读取的字段不同。

主色 ​

列出 primary、primaryDisabled、primaryDark、primaryLight 四个主色档位,并以色块展示实际色值。

查看源码
vue
<template>
    <ux-cell-group :border="false">
        <ux-cell-item
            v-for="(item, index) in primaryColors"
            :key="index"
            :title="item.name"
            :value="item.value"
            :arrow="false"
            :border-bottom="!item.last"
        >
            <template #icon>
                <view class="demo-swatch" :style="{ backgroundColor: item.value }"></view>
            </template>
        </ux-cell-item>
    </ux-cell-group>
</template>

<script setup lang="ts">
import { $u } from '@/uni_modules/uview-pro-x';

type ColorRow = {
    name: string;
    value: string;
    last: boolean;
};

// 同一结构复用于 primary / success / warning / error / info / text 六组
const primaryColors: ColorRow[] = [
    { name: 'primary', value: $u.color.primary ?? '', last: false },
    { name: 'primaryDisabled', value: $u.color.primaryDisabled ?? '', last: false },
    { name: 'primaryDark', value: $u.color.primaryDark ?? '', last: false },
    { name: 'primaryLight', value: $u.color.primaryLight ?? '', last: true }
];
</script>

<style lang="scss">
/* 色块需真实渲染色值,属必要例外:仅 background-color 走内联 */
.demo-swatch {
    width: 20px;
    height: 20px;
    border-radius: 4px;
    border: 1px solid $u-border-color;
}
</style>

成功色 ​

同一色板结构改用 success、successDisabled、successDark、successLight 四个字段。

查看源码
vue
<template>
    <ux-cell-group :border="false">
        <ux-cell-item
            v-for="(item, index) in primaryColors"
            :key="index"
            :title="item.name"
            :value="item.value"
            :arrow="false"
            :border-bottom="!item.last"
        >
            <template #icon>
                <view class="demo-swatch" :style="{ backgroundColor: item.value }"></view>
            </template>
        </ux-cell-item>
    </ux-cell-group>
</template>

<script setup lang="ts">
import { $u } from '@/uni_modules/uview-pro-x';

type ColorRow = {
    name: string;
    value: string;
    last: boolean;
};

// 同一结构复用于 primary / success / warning / error / info / text 六组
const primaryColors: ColorRow[] = [
    { name: 'primary', value: $u.color.primary ?? '', last: false },
    { name: 'primaryDisabled', value: $u.color.primaryDisabled ?? '', last: false },
    { name: 'primaryDark', value: $u.color.primaryDark ?? '', last: false },
    { name: 'primaryLight', value: $u.color.primaryLight ?? '', last: true }
];
</script>

<style lang="scss">
/* 色块需真实渲染色值,属必要例外:仅 background-color 走内联 */
.demo-swatch {
    width: 20px;
    height: 20px;
    border-radius: 4px;
    border: 1px solid $u-border-color;
}
</style>

警告色 ​

同一色板结构改用 warning、warningDisabled、warningDark、warningLight 四个字段。

查看源码
vue
<template>
    <ux-cell-group :border="false">
        <ux-cell-item
            v-for="(item, index) in primaryColors"
            :key="index"
            :title="item.name"
            :value="item.value"
            :arrow="false"
            :border-bottom="!item.last"
        >
            <template #icon>
                <view class="demo-swatch" :style="{ backgroundColor: item.value }"></view>
            </template>
        </ux-cell-item>
    </ux-cell-group>
</template>

<script setup lang="ts">
import { $u } from '@/uni_modules/uview-pro-x';

type ColorRow = {
    name: string;
    value: string;
    last: boolean;
};

// 同一结构复用于 primary / success / warning / error / info / text 六组
const primaryColors: ColorRow[] = [
    { name: 'primary', value: $u.color.primary ?? '', last: false },
    { name: 'primaryDisabled', value: $u.color.primaryDisabled ?? '', last: false },
    { name: 'primaryDark', value: $u.color.primaryDark ?? '', last: false },
    { name: 'primaryLight', value: $u.color.primaryLight ?? '', last: true }
];
</script>

<style lang="scss">
/* 色块需真实渲染色值,属必要例外:仅 background-color 走内联 */
.demo-swatch {
    width: 20px;
    height: 20px;
    border-radius: 4px;
    border: 1px solid $u-border-color;
}
</style>

错误色 ​

同一色板结构改用 error、errorDisabled、errorDark、errorLight 四个字段。

查看源码
vue
<template>
    <ux-cell-group :border="false">
        <ux-cell-item
            v-for="(item, index) in primaryColors"
            :key="index"
            :title="item.name"
            :value="item.value"
            :arrow="false"
            :border-bottom="!item.last"
        >
            <template #icon>
                <view class="demo-swatch" :style="{ backgroundColor: item.value }"></view>
            </template>
        </ux-cell-item>
    </ux-cell-group>
</template>

<script setup lang="ts">
import { $u } from '@/uni_modules/uview-pro-x';

type ColorRow = {
    name: string;
    value: string;
    last: boolean;
};

// 同一结构复用于 primary / success / warning / error / info / text 六组
const primaryColors: ColorRow[] = [
    { name: 'primary', value: $u.color.primary ?? '', last: false },
    { name: 'primaryDisabled', value: $u.color.primaryDisabled ?? '', last: false },
    { name: 'primaryDark', value: $u.color.primaryDark ?? '', last: false },
    { name: 'primaryLight', value: $u.color.primaryLight ?? '', last: true }
];
</script>

<style lang="scss">
/* 色块需真实渲染色值,属必要例外:仅 background-color 走内联 */
.demo-swatch {
    width: 20px;
    height: 20px;
    border-radius: 4px;
    border: 1px solid $u-border-color;
}
</style>

信息色 ​

同一色板结构改用 info、infoDisabled、infoDark、infoLight 四个字段。

查看源码
vue
<template>
    <ux-cell-group :border="false">
        <ux-cell-item
            v-for="(item, index) in primaryColors"
            :key="index"
            :title="item.name"
            :value="item.value"
            :arrow="false"
            :border-bottom="!item.last"
        >
            <template #icon>
                <view class="demo-swatch" :style="{ backgroundColor: item.value }"></view>
            </template>
        </ux-cell-item>
    </ux-cell-group>
</template>

<script setup lang="ts">
import { $u } from '@/uni_modules/uview-pro-x';

type ColorRow = {
    name: string;
    value: string;
    last: boolean;
};

// 同一结构复用于 primary / success / warning / error / info / text 六组
const primaryColors: ColorRow[] = [
    { name: 'primary', value: $u.color.primary ?? '', last: false },
    { name: 'primaryDisabled', value: $u.color.primaryDisabled ?? '', last: false },
    { name: 'primaryDark', value: $u.color.primaryDark ?? '', last: false },
    { name: 'primaryLight', value: $u.color.primaryLight ?? '', last: true }
];
</script>

<style lang="scss">
/* 色块需真实渲染色值,属必要例外:仅 background-color 走内联 */
.demo-swatch {
    width: 20px;
    height: 20px;
    border-radius: 4px;
    border: 1px solid $u-border-color;
}
</style>

文字色 ​

列出 mainColor、contentColor、tipsColor、lightColor 四个文字层级色。

查看源码
vue
<template>
    <ux-cell-group :border="false">
        <ux-cell-item
            v-for="(item, index) in primaryColors"
            :key="index"
            :title="item.name"
            :value="item.value"
            :arrow="false"
            :border-bottom="!item.last"
        >
            <template #icon>
                <view class="demo-swatch" :style="{ backgroundColor: item.value }"></view>
            </template>
        </ux-cell-item>
    </ux-cell-group>
</template>

<script setup lang="ts">
import { $u } from '@/uni_modules/uview-pro-x';

type ColorRow = {
    name: string;
    value: string;
    last: boolean;
};

// 同一结构复用于 primary / success / warning / error / info / text 六组
const primaryColors: ColorRow[] = [
    { name: 'primary', value: $u.color.primary ?? '', last: false },
    { name: 'primaryDisabled', value: $u.color.primaryDisabled ?? '', last: false },
    { name: 'primaryDark', value: $u.color.primaryDark ?? '', last: false },
    { name: 'primaryLight', value: $u.color.primaryLight ?? '', last: true }
];
</script>

<style lang="scss">
/* 色块需真实渲染色值,属必要例外:仅 background-color 走内联 */
.demo-swatch {
    width: 20px;
    height: 20px;
    border-radius: 4px;
    border: 1px solid $u-border-color;
}
</style>

色值运算 ​

hexToRgba 支持 3 位与 6 位十六进制并追加透明度,mixColor 的 ratio 是目标色的权重(0-1)。

查看源码
vue
<template>
    <ux-cell-group :border="false">
        <ux-cell-item
            v-for="(item, index) in mixRows"
            :key="index"
            :title="item.desc"
            :value="item.result"
            :arrow="false"
            :border-bottom="!item.last"
        >
            <template #icon>
                <view class="demo-swatch" :style="{ backgroundColor: item.result }"></view>
            </template>
        </ux-cell-item>
    </ux-cell-group>
</template>

<script setup lang="ts">
import { $u } from '@/uni_modules/uview-pro-x';

type MixRow = {
    desc: string;
    result: string;
    last: boolean;
};

const mixRows: MixRow[] = [
    // 十六进制转 rgba:用于主题色半透明底色
    { desc: "$u.hexToRgba('#2979ff', 0.3)", result: $u.hexToRgba('#2979ff', 0.3), last: false },
    // 支持 3 位简写
    { desc: "$u.hexToRgba('#fff', 0.5)", result: $u.hexToRgba('#fff', 0.5), last: false },
    // 按比例混色:ratio 为 to 的权重(0-1)
    { desc: "$u.mixColor('#2979ff', '#000000', 0.5)", result: $u.mixColor('#2979ff', '#000000', 0.5), last: false },
    { desc: "$u.mixColor('#ffffff', '#000000', 0.1)", result: $u.mixColor('#ffffff', '#000000', 0.1), last: true }
];
</script>

主题色判断与取值 ​

isThemeColor 只认 config.type 白名单内的预设名,getThemeColor 按 main / dark / light 档位取值,非预设名回退到 fallback。

查看源码
vue
<template>
    <ux-cell-group :border="false">
        <ux-cell-item
            v-for="(item, index) in themeFlagRows"
            :key="index"
            :title="item.desc"
            :arrow="false"
            :border-bottom="!item.last"
        >
            <ux-tag
                size="mini"
                :type="item.result ? 'success' : 'error'"
                :text="item.result ? 'true' : 'false'"
            />
        </ux-cell-item>
    </ux-cell-group>
    <ux-gap :height="12" />
    <ux-cell-group :border="false">
        <ux-cell-item
            v-for="(item, index) in themeColorRows"
            :key="index"
            :title="item.desc"
            :value="item.result"
            :arrow="false"
            :border-bottom="!item.last"
        >
            <template #icon>
                <view class="demo-swatch" :style="{ backgroundColor: item.result }"></view>
            </template>
        </ux-cell-item>
    </ux-cell-group>
</template>

<script setup lang="ts">
import { $u } from '@/uni_modules/uview-pro-x';

type FlagRow = {
    desc: string;
    result: boolean;
    last: boolean;
};

type ColorRow = {
    desc: string;
    result: string;
    last: boolean;
};

// 预设主题名判定:依赖 config.type 白名单,色值与自定义名均返回 false
const themeFlagRows: FlagRow[] = [
    { desc: "$u.isThemeColor('primary')", result: $u.isThemeColor('primary'), last: false },
    { desc: "$u.isThemeColor('#2979ff')", result: $u.isThemeColor('#2979ff'), last: false },
    { desc: "$u.isThemeColor('brand')", result: $u.isThemeColor('brand'), last: true }
];

// tone 必传:main 主色 / dark 按压态 / light 浅底
const themeColorRows: ColorRow[] = [
    {
        desc: "$u.getThemeColor('primary', 'main', fallback)",
        result: $u.getThemeColor('primary', 'main', $u.strOr($u.color.contentColor)),
        last: false
    },
    {
        desc: "$u.getThemeColor('primary', 'dark', fallback)",
        result: $u.getThemeColor('primary', 'dark', $u.strOr($u.color.contentColor)),
        last: false
    },
    // 非预设主题名走 fallback
    {
        desc: "$u.getThemeColor('brand', 'main', '#888888')",
        result: $u.getThemeColor('brand', 'main', '#888888'),
        last: true
    }
];
</script>

API ​

color ​

$u.color 是 reactive<ThemeColor>,主题切换时会被整体更新。

返回值(对象字段):

字段说明类型
primary主色string | null
primaryDark主色按压态string | null
primaryDisabled主色禁用态string | null
primaryLight主色浅底string | null
success成功色string | null
successDark成功色按压态string | null
successDisabled成功色禁用态string | null
successLight成功色浅底string | null
warning警告色string | null
warningDark警告色按压态string | null
warningDisabled警告色禁用态string | null
warningLight警告色浅底string | null
error错误色string | null
errorDark错误色按压态string | null
errorDisabled错误色禁用态string | null
errorLight错误色浅底string | null
info信息色string | null
infoDark信息色按压态string | null
infoDisabled信息色禁用态string | null
infoLight信息色浅底string | null
whiteColor白色string | null
blackColor黑色string | null
mainColor主要文字色string | null
contentColor常规文字色string | null
tipsColor提示文字色string | null
lightColor次要文字色string | null
borderColor边框色string | null
dividerColor分割线色string | null
maskColor遮罩色string | null
shadowColor阴影色string | null
bgColor页面背景色string | null
bgWhite白色背景string | null
bgGrayLight浅灰背景string | null
bgGrayDark深灰背景string | null
bgBlack黑色背景string | null

hexToRgba ​

参数:

参数说明类型默认值版本
hex十六进制颜色,支持 #fff 与 #ffffffstring--
opacity透明度(0-1)number1-

返回值:

类型说明
stringrgba(r, g, b, opacity) 字符串;非法或空输入原样返回

mixColor ​

参数:

参数说明类型默认值版本
from起始色,#rgb 或 #rrggbbstring | null | undefined--
to目标色,#rgb 或 #rrggbbstring | null | undefined--
ratioto 的混合权重(0-1)number--

返回值:

类型说明
string混合后的 #rrggbb;任一输入非法或为空时回退到 to,再回退到 #2979ff

isThemeColor ​

参数:

参数说明类型默认值版本
type待判断的主题名string | null--

返回值:

类型说明
boolean是否为 config.type 白名单中的预设主题名

getThemeColor ​

参数:

参数说明类型默认值版本
type主题名(primary / success / error / warning / info)string--
tone取哪一档:main 主色、dark 按压态、light 浅底'main' | 'dark' | 'light'--
fallback非预设主题或对应档位为空时的回退色string | null--

返回值:

类型说明
string该档位的主题色值;无法命中时返回 fallback

注意事项 ​

  • $u.color 各字段类型为 string | null,取色时用 ?? '' 或 $u.strOr 兜底。
  • isThemeColor 依赖 config.type 白名单,十六进制色值与自定义主题名都返回 false。
  • mixColor 的 ratio 是 to 的权重:0 取 from,1 取 to;结果会四舍五入并限制在 0-255。
  • hexToRgba 只接受 3 位或 6 位十六进制色值,其余输入原样返回,opacity 不做范围裁剪。