TechUI Docs

简中

EN

简中

EN

主题

切换控制 ​

TechUI 的主题切换是纯运行时的。这意味着当主题发生改变时，页面不需要刷新。系统会利用 Vue 的响应式机制和 CSS 变量的继承特性，瞬间更新整个应用的所有视觉元素，包括 DOM 结构和 Canvas 图表。

切换方式 ​

TechUI 提供了三个维度的切换控制能力，从开箱即用的 UI 组件到底层的 API 调用。

使用切换组件 (TuiThemeToggle) ​

<TuiThemeToggle> 是一个专用的轻量级按钮组件，通常放置在导航栏、登录页角落或侧边栏底部。

基础用法：

html
<template>
  <TuiThemeToggle />
  
  <TuiThemeToggle direction="v" />
</template>

行为逻辑： 点击该组件时，它会在所有已注册的主题之间循环切换。

使用控制面板 (Control Panel) ​

TechUI 内置了一个全局配置面板 <TuiControlPanel>，其中包含了更详细的主题选择器。用户可以在此面板中直观地看到每个主题的预览色块（由注册时的 colors 字段定义）。

呼出方式： 通常通过调用全局方法 controlPanelToggle() 来显示或隐藏面板。

javascript
import { inject } from 'vue';

const { controlPanelToggle } = inject('$global');

// 绑定到某个设置按钮
const openSettings = () => {
  controlPanelToggle();
};

编程控制 (API) ​

在业务逻辑中，如果您需要根据特定条件（如时间、用户偏好配置）强制切换主题，可以使用全局服务提供的 themeToggle 函数。

函数签名： themeToggle(themeName: String, themeScheme: String)

使用示例：

javascript
import { inject } from 'vue';

const { themeToggle } = inject('$global');

const switchToDark = () => {
  // 参数1: 主题的注册名称 (value)
  // 参数2: 配色方案类型 ('light' 或 'dark')
  themeToggle('darkBlue', 'dark');
};

转场动画： 值得注意的是，通过 themeToggle 切换主题时，系统会自动触发 View Transition（视图转场动画）。TechUI 默认使用圆形扩散或淡入淡出效果，让主题切换过程显得平滑且充满科技感，而非生硬的颜色跳变。

智能策略 ​

单/多主题自动适配 ​

TechUI 的 UI 组件（包括 <TuiThemeToggle> 和控制面板中的主题模块）具有智能感知能力：

  • 单主题模式：如果在 main.js 中仅引入了一个主题文件（例如只引入了 lightBlue），系统会判断当前无需切换。此时，<TuiThemeToggle> 会自动隐藏（渲染为注释），控制面板中的主题选项也会隐藏。
  • 多主题模式：一旦引入了两个及以上的主题，相关 UI 控件会自动显示。

这种设计允许开发者在开发阶段引入多个主题进行调试，而在发布阶段若只想保留一个主题，只需注释掉 import 语句即可，无需修改任何 UI 代码。

持久化存储 ​

主题的状态具有持久化能力。

  1. 自动保存：当用户切换主题后，TechUI 会自动将最新的主题名称 (theme) 和方案 (themeScheme) 保存到浏览器的本地存储（LocalStorage 或 SessionStorage，取决于全局配置）。
  2. 自动恢复：当用户刷新页面或下次访问时，TuiProvider 会在初始化阶段优先读取本地存储中的配置，自动应用上次选中的主题，确保用户体验的一致性。

常见问题 ​

Q: 为什么调用 themeToggle 后页面没有变化？A: 请检查以下两点：

  1. 传递的 themeName 是否与主题文件中注册的 value 字段完全一致（区分大小写）。
  2. 目标主题文件是否已经在 main.js 中被 import 引入。未引入的主题不会被注册到系统中。

Q: 如何关闭切换时的转场动画？A: 可以在全局配置中将 transition 设置为 false，或者在调用 themeToggle 前临时修改转场配置。但在大多数场景下，保留动画能提供更好的用户体验。