# 文字入场

- 页面: https://jiguang132.com/zh/resources/motion-primitives/docs/text-effect
- 资源: Motion Primitives (https://jiguang132.com/zh/resources/motion-primitives.md)
- 全部指南: https://jiguang132.com/zh/resources/motion-primitives/docs.md

按字符、单词或行实现文字入场。

## 使用要点

使用实际语言测试分段方式；中文与英文的单词划分不同，长段落避免过长延迟。

## 版本与安装前检查

此版本以 React 18.3.1、Motion 11.12.0 和 Tailwind CSS 4 验证。先检查目标项目的 React、样式入口和现有依赖；不要直接降级 React，也不要把其他版本的 Motion API 混入本实现。React 19 项目需要单独兼容验证。

预览可在隔离环境中运行，不代表可以把所有上游全局 CSS 覆盖到已有网站。只合并所需主题变量和工具类，保留现有样式。

## 安装组件

下面的 JGUANG_ORIGIN 是占位符；替换为提供此资源的已验证站点地址。请使用当前提供此资源的 JGuang 站点地址，安装前检查资源状态与版本。运行前预览文件变更，不使用 --overwrite。

```sh
npx shadcn@latest add https://jiguang132.com/r/motion-primitives/text-effect.json
```

此组件直接依赖：`clsx@2.1.1`, `motion@11.12.0`, `tailwind-merge@2.6.0`。React 与 ReactDOM 由目标项目提供。

## 可运行示例

以下标识与预览及示例安装包一一对应。每个示例包含自己的状态和必要辅助组件；安装一个完整示例即可开始，再按需求调整公开参数。

### 逐字符入场

```sh
npx shadcn@latest add https://jiguang132.com/r/motion-primitives/text-effect--text-effect-per-char.json
```

```tsx
import { TextEffectPerChar } from "@/components/motion-primitives/app/docs/text-effect/text-effect-per-char";

export function Example() { return <TextEffectPerChar />; }
```

### 逐词入场

```sh
npx shadcn@latest add https://jiguang132.com/r/motion-primitives/text-effect--text-effect-per-word.json
```

```tsx
import { TextEffectPerWord } from "@/components/motion-primitives/app/docs/text-effect/text-effect-per-word";

export function Example() { return <TextEffectPerWord />; }
```

### 预设文字动画

```sh
npx shadcn@latest add https://jiguang132.com/r/motion-primitives/text-effect--text-effect-preset.json
```

```tsx
import { TextEffectWithPreset } from "@/components/motion-primitives/app/docs/text-effect/text-effect-preset";

export function Example() { return <TextEffectWithPreset />; }
```

### 自定义文字状态

```sh
npx shadcn@latest add https://jiguang132.com/r/motion-primitives/text-effect--text-effect-variants.json
```

```tsx
import { TextEffectWithCustomVariants } from "@/components/motion-primitives/app/docs/text-effect/text-effect-variants";

export function Example() { return <TextEffectWithCustomVariants />; }
```

### 自定义延迟

```sh
npx shadcn@latest add https://jiguang132.com/r/motion-primitives/text-effect--text-effect-custom-delay.json
```

```tsx
import { TextEffectWithCustomDelay } from "@/components/motion-primitives/app/docs/text-effect/text-effect-custom-delay";

export function Example() { return <TextEffectWithCustomDelay />; }
```

### 逐行入场

```sh
npx shadcn@latest add https://jiguang132.com/r/motion-primitives/text-effect--text-effect-line.json
```

```tsx
import { TextEffectPerLine } from "@/components/motion-primitives/app/docs/text-effect/text-effect-line";

export function Example() { return <TextEffectPerLine />; }
```

### 文字退出动画

```sh
npx shadcn@latest add https://jiguang132.com/r/motion-primitives/text-effect--text-effect-exit.json
```

```tsx
import { TextEffectWithExit } from "@/components/motion-primitives/app/docs/text-effect/text-effect-exit";

export function Example() { return <TextEffectWithExit />; }
```

### 动画速度控制

```sh
npx shadcn@latest add https://jiguang132.com/r/motion-primitives/text-effect--text-effect-speed.json
```

```tsx
import { TextEffectSpeed } from "@/components/motion-primitives/app/docs/text-effect/text-effect-speed";

export function Example() { return <TextEffectSpeed />; }
```

## 交互与无障碍检查

使用键盘验证可聚焦控件、Enter/Space、关闭与焦点返回；在手机和深浅主题下检查溢出与对比度。遵循 prefers-reduced-motion，为持续动画提供暂停或静态替代内容。平台预览的暂停控件属于预览宿主，不会自动随单组件安装到目标项目。

## 来源与本地修改

https://github.com/ibelick/motion-primitives/tree/120f64f6ca60348e251f929e9c81f11ccbe45eda

保留 MIT 许可证；包含滚动锁定辅助代码的包还附 Adobe Apache-2.0 声明。本地修复对话框焦点返回；演示图片替换为自有几何示意图。完整变化见随包附带的 LOCAL_CHANGES.md。此文档是 JGuang 双语实用指南，不是上游 MDX 的逐字译本。

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt