Skip to content

color — Color Config ​

17:43

Description ​

$u.color is a reactive theme color object holding the main, pressed, disabled and light variants of each semantic color, plus text, background, border and other tokens. hexToRgba and mixColor handle color math, while isThemeColor and getThemeColor check and resolve preset theme names.

Examples ​

The six palette sections reuse the same codes.palette source; only the fields read at runtime differ.

Primary ​

Lists the four primary shades primary, primaryDisabled, primaryDark and primaryLight, with a swatch showing each value.

View source
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 ​

The same palette structure uses the success, successDisabled, successDark and successLight fields.

View source
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 ​

The same palette structure uses the warning, warningDisabled, warningDark and warningLight fields.

View source
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 ​

The same palette structure uses the error, errorDisabled, errorDark and errorLight fields.

View source
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 ​

The same palette structure uses the info, infoDisabled, infoDark and infoLight fields.

View source
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>

Text ​

Lists the four text levels mainColor, contentColor, tipsColor and lightColor.

View source
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>

Color math ​

hexToRgba accepts 3- and 6-digit hex values and appends an alpha channel, while the ratio of mixColor is the weight of the target color (0-1).

View source
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>

Theme color check & lookup ​

isThemeColor only accepts preset names in the config.type whitelist, while getThemeColor resolves the main / dark / light tone and falls back for non-preset names.

View source
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 is a reactive<ThemeColor> that is replaced whenever the theme changes.

Returns (object fields):

FieldDescriptionType
primaryPrimary colorstring | null
primaryDarkPrimary pressed statestring | null
primaryDisabledPrimary disabled statestring | null
primaryLightPrimary light backgroundstring | null
successSuccess colorstring | null
successDarkSuccess pressed statestring | null
successDisabledSuccess disabled statestring | null
successLightSuccess light backgroundstring | null
warningWarning colorstring | null
warningDarkWarning pressed statestring | null
warningDisabledWarning disabled statestring | null
warningLightWarning light backgroundstring | null
errorError colorstring | null
errorDarkError pressed statestring | null
errorDisabledError disabled statestring | null
errorLightError light backgroundstring | null
infoInfo colorstring | null
infoDarkInfo pressed statestring | null
infoDisabledInfo disabled statestring | null
infoLightInfo light backgroundstring | null
whiteColorWhitestring | null
blackColorBlackstring | null
mainColorPrimary text colorstring | null
contentColorRegular text colorstring | null
tipsColorTip text colorstring | null
lightColorSecondary text colorstring | null
borderColorBorder colorstring | null
dividerColorDivider colorstring | null
maskColorMask colorstring | null
shadowColorShadow colorstring | null
bgColorPage backgroundstring | null
bgWhiteWhite backgroundstring | null
bgGrayLightLight gray backgroundstring | null
bgGrayDarkDark gray backgroundstring | null
bgBlackBlack backgroundstring | null

hexToRgba ​

Parameters:

ParameterDescriptionTypeDefaultVersion
hexHex color, #fff and #ffffff supportedstring--
opacityOpacity (0-1)number1-

Returns:

TypeDescription
stringAn rgba(r, g, b, opacity) string; invalid or empty input is returned as-is

mixColor ​

Parameters:

ParameterDescriptionTypeDefaultVersion
fromStart color, #rgb or #rrggbbstring | null | undefined--
toTarget color, #rgb or #rrggbbstring | null | undefined--
ratioWeight of to in the mix (0-1)number--

Returns:

TypeDescription
stringThe mixed #rrggbb; when any input is invalid or empty it falls back to to, then to #2979ff

isThemeColor ​

Parameters:

ParameterDescriptionTypeDefaultVersion
typeTheme name to checkstring | null--

Returns:

TypeDescription
booleanWhether the name is one of the preset themes in config.type

getThemeColor ​

Parameters:

ParameterDescriptionTypeDefaultVersion
typeTheme name (primary / success / error / warning / info)string--
toneWhich tone to resolve: main, dark (pressed) or light'main' | 'dark' | 'light'--
fallbackFallback for non-preset themes or an empty tonestring | null--

Returns:

TypeDescription
stringThe resolved theme color; returns fallback when nothing matches

Notes ​

  • Every $u.color field is typed string | null, so use ?? '' or $u.strOr as a fallback when reading colors.
  • isThemeColor relies on the config.type whitelist, so hex values and custom theme names both return false.
  • mixColor treats ratio as the weight of to: 0 yields from, 1 yields to; results are rounded and clamped to 0-255.
  • hexToRgba only accepts 3-digit or 6-digit hex values and returns other input as-is; opacity is not clamped.