color 颜色配置
17:43说明
$u.color 是响应式主题色对象,包含各语义色的主色、按压、禁用、浅底档位以及文字、背景、边框等令牌;hexToRgba、mixColor 负责色值运算,isThemeColor、getThemeColor 负责预设主题名的判断与取色。
示例
六个色板小节复用同一段 codes.palette 源码,实际读取的字段不同。
主色
列出 primary、primaryDisabled、primaryDark、primaryLight 四个主色档位,并以色块展示实际色值。
查看源码
<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 四个字段。
查看源码
<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 四个字段。
查看源码
<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 四个字段。
查看源码
<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 四个字段。
查看源码
<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 四个文字层级色。
查看源码
<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)。
查看源码
<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。
查看源码
<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 与 #ffffff | string | - | - |
| opacity | 透明度(0-1) | number | 1 | - |
返回值:
| 类型 | 说明 |
|---|---|
string | rgba(r, g, b, opacity) 字符串;非法或空输入原样返回 |
mixColor
参数:
| 参数 | 说明 | 类型 | 默认值 | 版本 |
|---|---|---|---|---|
| from | 起始色,#rgb 或 #rrggbb | string | null | undefined | - | - |
| to | 目标色,#rgb 或 #rrggbb | string | null | undefined | - | - |
| ratio | to 的混合权重(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不做范围裁剪。