---
title: "GlowText 扫光"
description: "在文字或内容上扫过一道高光的动效"
category: Effects
status: beta
since: 0.3.4
tags: [glow, text, animation, highlight]
syncStatus: reviewed
verified: true
---

## 用法

### 文字
`mode="text-clip"` 把高光裁切到字形，渐变文字同样适用。
:::TuffDemoWrapper{demo="GlowTextGlowTextDemo" code-lang="vue"}
---
code: |
  <template>
    <TxGlowText mode="text-clip" :band-size="24" :duration-ms="1300" color="rgba(255, 255, 255, 0.98)">
      GlowText
    </TxGlowText>
    <TxGlowText mode="text-clip" :angle="18" :band-size="30" color="rgba(99, 102, 241, 0.9)">
      Sweep highlight over text
    </TxGlowText>
    <TxGlowText mode="text-clip" :band-size="34">
      <span class="gradient-text">Colorful text still shines</span>
    </TxGlowText>
  </template>
---
:::

### 图片与卡片
默认的 `adaptive` 模式扫过整个容器；包裹块级内容时设置 `tag="div"`。
:::TuffDemoWrapper{demo="GlowTextGlowTextOnImageDemo" code-lang="vue"}
---
code: |
  <template>
    <TxGlowText tag="div" :radius="14" :band-size="34" color="rgba(255, 255, 255, 0.95)">
      <div class="card card--dark" />
    </TxGlowText>
    <TxGlowText tag="div" :radius="12" :angle="-12" :band-size="40" :opacity="0.55" blend-mode="soft-light">
      <div class="card card--light" />
    </TxGlowText>
  </template>
---
:::

### 界面元素
`:repeat="false"` 只扫一次，可配合 `delayMs` 做一次性的新功能提示。
:::TuffDemoWrapper{demo="GlowTextGlowTextCasesDemo" code-lang="vue"}
---
code: |
  <template>
    <TxGlowText tag="div" :radius="999" :angle="-20" :band-size="28" :duration-ms="1200" :repeat="false">
      <div class="badge">New Feature</div>
    </TxGlowText>
    <TxGlowText tag="div" :radius="12" :angle="16" :band-size="36" :opacity="0.6">
      <div class="status-card">Realtime Sync</div>
    </TxGlowText>
  </template>
---
:::

### 最佳实践

- 标签、标题与渐变文字用 `text-clip`；图片、卡片与状态胶囊用 `adaptive`。
- 文字场景的 `bandSize` 保持在 `24`–`40`，更宽的光带留给图片或卡片。
- 浅色卡片降低 `opacity`，或用 `blendMode="soft-light"` 配更深的 `color`。
- 不要包裹可聚焦控件，以免高光遮住焦点环。
- 不要当作加载骨架；加载反馈用 `TxSkeleton`、`TxProgressBar` 或 `TxLoadingState`。

## API 参考

### 属性

| 属性名 | 类型 | 默认值 | 说明 |
|------|------|---------|------|
| `tag` | `string` | `span` | 根元素标签；文字用 `span`，卡片或图片用 `div`。 |
| `active` | `boolean` | `true` | 显示扫光；`false` 时插槽照常渲染。 |
| `repeat` | `boolean` | `true` | 循环播放；`false` 时只扫一次。 |
| `durationMs` | `number` | `2000` | 一个周期的时长（ms）。 |
| `delayMs` | `number` | `0` | 开始前的延迟（ms）。 |
| `angle` | `number` | `20` | 光带偏离竖直的角度；`0` 为竖直，正值向右倾（形如 `/`）。 |
| `bandSize` | `number` | `38` | 光带宽度占元素宽度的百分比。 |
| `color` | `string` | `rgba(255, 255, 255, 0.9)` | 高光颜色。 |
| `opacity` | `number` | `0.75` | 高光不透明度。 |
| `blendMode` | `string` | - | 自定义 `mix-blend-mode`；`adaptive` 默认用 `plus-lighter`，不支持时用 `screen`。 |
| `mode` | `'classic' \| 'adaptive' \| 'text-clip'` | `adaptive` | `classic` 普通覆盖；`adaptive` 加混合与背景滤镜；`text-clip` 裁切到字形。 |
| `backdrop` | `string` | - | 自定义 `backdrop-filter`，如 `brightness(1.2) saturate(1.1)`。 |
| `radius` | `number` | `10` | 根节点圆角（px）。 |

### 插槽

| 名称 | 参数 | 说明 |
|------|------|------|
| `default` | - | 接收扫光的内容；`text-clip` 下纯文本会镜像到 `aria-hidden` 的高光层。 |

## 概述

- `adaptive` 只提亮：浅色表面上的浅色高光看不见，也不会报错。
- `text-clip` 在挂载和文本变化时读取插槽文本，只适合简单文本。
- 光带从元素左侧半个宽度之外匀速扫到右侧半个宽度之外，占周期的 65%，其余时间停在画外；`--tx-glow-ease` 可覆盖缓动。
- `adaptive` 的背景滤镜只作用于光带经过的部分。
- 扫光层均为 `aria-hidden`，可读文本必须留在默认插槽里。
- 减少动态效果时停止扫动，只保留居中的静态高光。

## 技术实现

- 光带是三倍元素宽的图层上的一条 `linear-gradient`，方向为 `90deg + angle`，靠 `transform`（`text-clip` 为 `background-position`）平移。
- 源码：`packages/tuffex/packages/components/src/glow-text/`。

<TuffDocSourceLink />