组件/主题定制

主题定制

从全局 token 到单个组件的四层主题覆盖

自 0.4.0BETA

定制模型

组件不写死颜色,视觉全部读取 CSS 自定义属性,换主题只改样式表。四层由宽到窄,选能解决问题的最窄一层。

层级定义位置影响范围
全局 tokenbase.css 里的 :root全部
主题选择器[data-theme='dark']、[data-tx-contrast='high']整个模式
BUI token--tx-bui-*AI 套件
组件变量--tx-<component>-*单个组件,或某个子树

token 清单见《Design Foundations 设计基础》。

全局 token

在引入 base.css 之后重定义。组件绘制时才解析变量,覆盖对其下整棵子树生效。

EXAMPLE.CSS
@import '@talex-touch/tuffex/base.css';

:root {
  --tx-color-primary: #7c5cff;
  --tx-border-radius-base: 8px;
  --tx-transition-duration: 0.24s;
}

--tx-color-primary-soft、--tx-coloring-border-color 由 --tx-color-primary 经 color-mix() 派生,自动跟随;主色阶梯 --tx-color-primary-light-*、--tx-color-primary-dark-2 是固定色值(默认焦点环也取自其中),换品牌色时一并覆盖。

深色模式

深色是选择器,不是媒体查询:在任意祖先上设置 data-theme="dark" 或 dark class。

EXAMPLE.HTML
<html data-theme="dark">
<!-- 或 -->
<html class="dark">
  • 两种写法等价:Tailwind 应用(.dark)与 data-theme 应用都无需适配层。
  • 设在子树上,即可在浅色页面里开一块深色区域。
  • 深色下三档强调字重各调轻 40,抵消白字在暗底上的光渗膨胀:--tx-font-weight-medium 500 → 460、--tx-font-weight-semibold 600 → 560、--tx-font-weight-bold 700 → 660,正文 400 不变。自己写的样式以 var(--tx-font-weight-medium, 500) 读取即可跟随;覆盖时让暗色值落在(浅色值 − 100,浅色值]之内,否则静态字体会换成另一个字面,见《暗色视网膜光晕与字重微调补偿》。

视图过渡动效(View Transition)

切换深色/浅色时,Tuffex 提供了基于原生 View Transitions API 的平滑过渡封装 applyThemeTransition。默认预设为 circle-blur,以鼠标点击坐标为圆心,通过 SVG 高斯模糊遮罩向外扩散展开新主题,视觉轻盈柔和。

同时支持 circle(硬边裁切圆)、polygon(斜切光刃)、polygon-gradient(渐变光刃)、wipe(平推扫光)、fade(平滑淡入淡出)以及自定义 GIF 遮罩。

Loading demo...

预设变体与配置

变体名称 (variant)默认时长视觉特点
circle-blur (默认)450ms以点击坐标为原点,带柔和高斯模糊的圆形光晕展开
circle350ms以点击坐标为原点,clip-path: circle 锐利圆形裁切展开
polygon600ms对角线光刃斜切拉开新主题
polygon-gradient800ms线性渐变柔和边缘的光刃斜切
wipe400ms水平横向扫光推进
fade250ms经典跨主题淡入淡出(轻量回退)
circle-blur-top-left600ms从左上角原点以模糊圆展开
gif1500ms传入 maskUrl 使用动态图形展开新主题
  • 原点自动解析:origin 可传入原生 MouseEvent、{ clientX, clientY } 或 [x, y],未指定时默认从视口中心扩散。
  • 无障碍保障:系统检测到用户开启 prefers-reduced-motion 或浏览器不支持 View Transition 时,自动静默直切,无冗余动画。

高对比度

第四套调色板,在浅色与深色下都提高文本与边框对比度。

触发条件效果
html[data-tx-contrast='high'] 或 html.contrast显式开启
@media (prefers-contrast: more)跟随系统自动开启
html[data-tx-contrast='normal']退出上面的媒体查询

data-theme="dark" 与任一开启条件同时存在时,使用「深色高对比度」调色板,而不是两套主题叠加。

材质

高对比度下,组件不再透出页面:

部件高对比度下
材质面板:TxBaseSurface 除 plain 外的所有模式(Card、BaseAnchor 浮层、命令面板与各类对话框等都基于它;plain 本来不画材质,高对比度下也不加底色)、GlassSurface、Toast、NavBar、TabBar、Picker、Slider、RadioGroup 指示块、ProgressBar 遮罩、StatCard、Drawer 的透明面板、MotionTransition 的玻璃幕不透明底色,不模糊、不折射、没有边缘高光
遮罩:Modal、Drawer、BlowDialog保留压暗,去掉磨砂
盖在内容上的层:LoadingOverlay、Card 与 DataTable 的加载层、ImageUploader 的删除按钮不透明,遮住下面的内容
装饰:FlowLight、GlowText 的扫光、GradualBlur隐藏

组件内部的浅色叠层(悬停、选中、输入框底色)保持不变。规则写在 style/mixins.scss 的 tx-when-high-contrast 里,与调色板响应同一组触发条件。

AI 套件 token

--tx-bui-* 随 Beautiful UI 组件移植(surface、inset、field、ink,accent / green / orange / red / violet 及配套 tint),在同样的 [data-theme='dark'] / .dark 下有自己的深色块。AI 界面不继承品牌色时单独覆盖:

EXAMPLE.CSS
:root {
  --tx-bui-accent: #7c5cff;
  --tx-bui-accent-tint: #f0ecff;
}

组件变量

--tx-<component>-* 只改单个组件,不动全局调色板。命名可预期(--tx-collapse-header-bg、--tx-avatar-ring-color、--tx-progress-height),每个都有兜底值;它们可继承,设在外层容器上只作用于该子树。

EXAMPLE.VUE
<template>
  <section class="settings-panel">
    <TxCollapse v-model="open">
      <TxCollapseItem title="外观" name="appearance">…</TxCollapseItem>
    </TxCollapse>
  </section>
</template>

<style scoped>
.settings-panel {
  --tx-collapse-radius: 6px;
  --tx-collapse-header-bg: transparent;
  --tx-collapse-border: rgba(148, 163, 184, 0.24);
}
</style>

每个组件页列出它读取的变量。用变量,不用后代选择器改组件内部:自定义属性是对外接口,class 名不是。

注意

  • 组件已暴露填充变量时改 token,不写 background-color:有些填充是 background-image 渐变,background-color 只会画在渐变背后。
  • base.css 只引一次。引两份时以后加载的为准,通常不是你改的那份。

技术实现

  • token 与主题选择器:packages/tuffex/packages/components/style/variables.scss。
  • AI 套件 token:packages/tuffex/packages/components/style/bui-tokens.scss。
  • 运行时入口:@talex-touch/tuffex/base.css。