---
title: "KeyframeStrokeText 关键帧描边"
description: "先描边、后填充的 SVG 文字动效"
category: Effects
status: beta
since: 0.3.4
tags: [text, svg, animation]
syncStatus: reviewed
verified: true
---

## 用法

### 基础
::::TuffDemoWrapper{demo="KeyframeStrokeTextKeyframeStrokeTextDemo" code-lang="vue"}
---
code: |
  <template>
    <TxKeyframeStrokeText text="TuffEx" :font-size="56" />
    <TxKeyframeStrokeText
      text="Stroke + Fill"
      stroke-color="#0ea5e9"
      fill-color="#0f172a"
      :duration-ms="2400"
      :stroke-width="1.8"
      :font-size="42"
      :font-weight="600"
    />
  </template>
---
::::

### 多语言文本
宽度按实际渲染的文字测量，中文与混排文本无需额外设置。
::::TuffDemoWrapper{demo="KeyframeStrokeTextChineseDemo" code-lang="vue"}
---
code: |
  <template>
    <TxKeyframeStrokeText
      text="关键帧描边动画"
      stroke-color="#16a34a"
      fill-color="#14532d"
      :duration-ms="2600"
      :stroke-width="1.6"
      :font-size="40"
    />
  </template>
---
::::

### 最佳实践

- 只用于短文案；长句难读，测量与动画也更重。
- 文字只是装饰时，把语义标题放在组件外。
- 大型列表中不要随输入逐字更新 `text`，每次变化都会重新测量。
- 在目标页面测试自定义 Web Font，字体加载后宽度会再变一次。
- 深色背景上给 `strokeColor` 选高对比色，否则描边阶段几乎不可见。

## API 参考

### 属性

| 属性名 | 类型 | 默认值 | 说明 |
|------|------|---------|------|
| `text` | `string` | `''` | 要渲染的文字。 |
| `strokeColor` | `string` | `'#4C4CFF'` | 先出现的描边轮廓颜色。 |
| `fillColor` | `string` | `'#111827'` | 描边后显现的最终文字颜色。 |
| `durationMs` | `number` | `1800` | 动画时长（ms），描边与填充共用。 |
| `strokeWidth` | `number` | `2` | 描边宽度，同时决定 viewBox 内边距。 |
| `fontSize` | `string \| number` | `64` | 字号；数字转为 px，字符串原样透传。 |
| `fontWeight` | `string \| number` | `700` | 字重；越粗，描边轮廓越厚。 |
| `fontFamily` | `string` | `'inherit'` | 字体族。 |

## 概述

- 根节点是 `role="img"` 的 SVG；非空 `text` 同步为 `aria-label`，空文本不输出 `aria-label`，以不换行空格占位。
- 挂载后，以及 `text`、字体属性或 `strokeWidth` 变化后，用 `getBBox()` 与 `getComputedTextLength()` 重新测量；`document.fonts.ready` 后再测一次。
- SVG 尺寸取测得的文字框加描边内边距。
- 减少动态效果时不播放动画，直接显示最终状态。

## 技术实现

- 隐藏的测量层固定在原点，两个绘制层带上计算出的偏移；描边按测得长度做 dash 动画，参数经 `--tx-kf-*` CSS 变量传入。
- 源码：`packages/tuffex/packages/components/src/keyframe-stroke-text/`。

<TuffDocSourceLink />