TechUI Docs

简中

EN

简中

EN

主题

加载 ​

⚡WASM 驱动

TechUI 提供了一套高性能的 Loading 加载系统。与传统的 GIF 或 CSS 动画不同，TechUI 的加载图标源自 WebAssembly (WASM) 模块内置的 SVG 序列。

系统采用 CSS Mask (遮罩) 技术进行渲染，这意味着所有的加载图标都能自动适配当前的主题颜色，无需额外的图片资源。

核心组件 ​

加载系统包含两个核心组件：

  1. TuiLoadingFull: 全屏/全局加载遮罩，通常用于页面跳转或应用初始化。支持组件式和函数式两种调用方式。
  2. TuiLoadingArea: 局部/容器加载遮罩，通常用于表格、卡片等特定区域的数据刷新。

全局配置 ​

所有的加载样式默认通过全局配置 $spinnerConfig 进行管理。您可以在应用初始化时指定默认的加载动画类型和尺寸。

配置结构 ​

javascript
// 在 Global Config 或 TuiProvider 中
const spinnerConfig = {
  // 全屏加载配置
  full: { 
    name: "blocksA", // 动画名称 (见下方列表)
    size: 100        // 尺寸 (px)
  },
  
  // 局部加载配置
  area: { 
    name: "pointA",  // 动画名称
    size: 40         // 尺寸 (px)
  }
};

动态修改 ​

在应用运行时，通过修改配置并调用 initSpinner 方法可实时更新加载动画样式。

javascript
import { inject } from 'vue';

const { $tState, initSpinner } = inject('$global');

const changeSpinnerStyle = () => {
  $tState.spinnerConfig.full.name = "ringA";
  initSpinner($tState.spinnerConfig);
};

全屏加载 LoadingFull ​

全局方法调用 (推荐) ​

在业务逻辑（如 API 请求拦截器、路由守卫）中，推荐使用全局方法 $tLoading。

javascript
import { inject } from 'vue';

const { $tLoading, $tLoadingClose } = inject('$global');

const handleFetch = async () => {
  // 开启加载
  $tLoading({
    desc: "正在同步数据...", // 加载文案
    appendTo: "#app",      // 指定挂载节点
    visible: true
  });

  try {
    await api.getData();
  } finally {
    // 关闭加载
    $tLoadingClose();
  }
};

组件方式调用 ​

在 Vue 模板中，也可以直接使用组件形式。

html
<template>
  <TuiLoadingFull 
    :visible="isLoading" 
    desc="系统初始化中" 
    :zIndex="9999"
  />
</template>

局部加载 LoadingArea ​

局部加载主要以组件形式存在，用于覆盖父容器。

注意：使用 <TuiLoadingArea> 时，其父容器（Parent Element）的 CSS position 属性必须设置为 relative、absolute 或 fixed，否则遮罩将无法正确覆盖区域。

html
<template>
  <div class="data-card" style="position: relative; min-height: 200px;">
    <DataList />

    <TuiLoadingArea 
      :visible="isCardLoading" 
      :mask="true" 
      :size="50"
    />
  </div>
</template>

动画图形库 ​

系统内置了 19 种 SVG 动画图形，您可以在配置的 name 字段中使用以下 Key 值：

条形与方块 ​

  • barsA, barsB, barsC
  • blocksA, blocksB, blocksC

点阵与时钟 ​

  • pointA, pointB, pointC
  • clock (时钟倒计时)

脉冲与圆环 ​

  • pulseDotA, pulseDotB, pulseDotC
  • pulseRingA, pulseRingB, pulseRingC
  • ringA, ringB, ringC

API 参考 ​

TuiLoadingFull (全屏加载) ​

支持组件属性或 $tLoading(options) 参数对象。

属性名类型默认值说明
visibleBooleantrue控制显示与隐藏。
descString""加载图标下方的描述文字。
appendToStringnull指定挂载的目标 DOM 选择器（如 #app, body）。仅在动态渲染模式下有效。
dynamicRenderBooleanfalse是否开启动态渲染模式（通常由函数调用内部处理）。
sizeNumber-覆盖全局配置的图标尺寸 (px)。
colorString-覆盖默认颜色。
zIndexNumber-自定义层级 (z-index)。
updateBoolean-设置为 true 可强制更新/重绘动画组件。

注：tuiService, tMask, tMaskClose, destroy 为内部依赖注入参数，通常无需手动传递。

TuiLoadingArea (局部加载) ​

属性名类型默认值说明
visibleBooleantrue控制显示与隐藏。
maskBoolean-是否显示背景模糊/变暗遮罩层。
sizeNumber-覆盖全局配置的图标尺寸 (px)。
colorString-覆盖默认颜色。
zIndexNumber-自定义层级 (z-index)。
updateBoolean-设置为 true 可强制更新/重绘动画组件。

全局方法 ​

  • $tLoading(options): 创建并显示全屏加载。options 参数同 TuiLoadingFull 属性。
  • $tLoadingClose(): 关闭当前激活的全屏加载实例。

致谢 ​

n3r4zzurr0
n3r4zzurr0
Github

本组件中核心的 SVG 动态图形资产，源自开源项目 svg-spinners ！

在此，向作者 n3r4zzurr0 致以诚挚的谢意与敬意！