> For the complete documentation index, see [llms.txt](https://docs.febucci.com/text-animator-unity/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.febucci.com/text-animator-unity/3.x-zh/xiao-guo/she-zhi-wen-ben.md).

# 设置文本

你可以从两个不同的 UI 系统将文本设置到 Text Animator：

* [#ui-toolkit](#ui-toolkit "mention")
* [#text-mesh-pro](#text-mesh-pro "mention")

{% hint style="info" %}
此页面包含一些已经存在于 [安装与快速入门](/text-animator-unity/3.x-zh/kuai-su-ru-men/an-zhuang-yu-kuai-su-ru-men.md)中的信息，但也包含针对每个系统以及一般情况的其他细节和建议。请务必阅读 [#best-practices](#best-practices "mention") 这一部分！ 
{% endhint %}

***

## UI Toolkit

*附注：假设你已经知道* [*如何使用 UI Toolkit*](https://docs.unity3d.com/Documentation/Manual/UIElements.html) *以及它的功能。*

#### 从 UI Builder

{% columns %}
{% column width="58.333333333333336%" %}

* 转到 库 -> 项目
* 拖动 "<mark style="color:默认;background-color:yellow;">AnimatedLabel</mark>" 从 “Custom Controls/Febucci/Text Animator for Unity” 到你的层级结构中！

{% hint style="info" %}
我们正在努力确保你可以直接在 UI Toolkit 中为内置的 Label 和 Button 添加动画！ *（适用于 Unity 6.3 及以上。）*  保持关注！
{% endhint %}
{% endcolumn %}

{% column width="41.666666666666664%" %}
你的 .uxml 应该看起来像这样：

<figure><img src="/files/9d9dcee98e6dbdd40207c905e43e4d9936763443" alt="" width="302"><figcaption></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

#### 通过代码

你可以创建一个 "<mark style="color:默认;background-color:yellow;">Febucci.TextAnimatorForUnity.AnimatedLabel</mark>" 类的实例并将其添加到你的 UI 文档中，像这样：

```csharp
using UnityEngine;
using UnityEngine.UIElements;
using Febucci.TextAnimatorForUnity; // <- 导入 Text Animator 的命名空间

public class ExampleScript : MonoBehaviour
{ 
    [SerializeField] UIDocument document;

    void Start()
    {
        var container = document.rootVisualElement.contentContainer;
        var animatedLabel = new AnimatedLabel(); // <- 创建一个 animated label
        container.Add(animatedLabel); // <- 将其添加到内容容器中
        // [..]
        animatedLabel.SetText("<wave>hello"); // <- 设置文本
    }
}
```

{% hint style="success" %}
就这些！！你已经准备好使用 [如何添加效果](/text-animator-unity/3.x-zh/xiao-guo/ru-he-tian-jia-xiao-guo.md)
{% endhint %}

***

## Text Mesh Pro

*附注：假设你已经知道* [*如何使用 Text Mesh Pro*](https://docs.unity3d.com/Packages/com.unity.ugui@2.0/manual/TextMeshPro/index.html) *以及它如何工作。*

添加一个 <mark style="color:默认;background-color:yellow;">文本动画器 - Text Mesh Pro</mark> 组件到同一个具有 <mark style="color:默认;background-color:yellow;">TextMeshPro</mark> 组件（UI 或世界空间！）：

你的检视器应如下所示：

<figure><img src="/files/42af3928a69895539c679a2f55b20e045460d9b3" alt=""><figcaption></figcaption></figure>

{% hint style="success" %}
就这些！！你已经准备好使用 [如何添加效果](/text-animator-unity/3.x-zh/xiao-guo/ru-he-tian-jia-xiao-guo.md)
{% endhint %}

{% hint style="warning" %}
如果你看到的是空文本（但你已经在组件中设置了它们），请确保你至少点击过一次 TextMeshPro 组件，并导入了“Essentials”（在弹出窗口出现并要求你这样做时）。
{% endhint %}

#### 通过代码设置文本的最佳实践

要通过代码将文本设置到你的 TextMeshPro 对象，请参考 Text Animator 的脚本，而不是 TMPro，如下所示：

```csharp
using UnityEngine;
using TMPro; 
using Febucci.TextAnimatorForUnity.TextMeshPro; // <- 导入 Text Animator 的命名空间

public class ExampleScript : MonoBehaviour
{
    [SerializeField] TMP_Text textMeshPro;
    [SerializeField] TextAnimator_TMP textAnimator;

    void Start()
    {
        // 🚫 不要：通过 TMPro 设置文本
        textMeshPro.SetText("<wave>hello");

        // ✅ 应该：直接通过 Text Animator 设置文本
        textAnimator.SetText("<wave>hello");
    }

}
```

{% hint style="info" %}
附注：引用 TMPro 也依然可以工作，但使用 TextAnimator 设置文本的集成效果更好，因为我们对文本有更多控制。
{% endhint %}

***

## 最佳实践

### 整段文本/对话只设置一次

请尽量只设置一次文本，并使用打字机 / 可见性方法来控制它的显示方式。

{% hint style="info" %}
如果你真的需要在稍后追加文本，可以使用 “textAnimator.AppendText” 方法。
{% endhint %}

<details>

<summary>示例</summary>

如果有一个角色说“Hellooooo how are you doing?”，并且你想逐字显示，只需这样做： `typewriter.ShowText("Hellooooo how are you doing?");` 就这样！ [动态显示和隐藏字母](/text-animator-unity/3.x-zh/da-zi-ji/dong-tai-xian-shi-he-yin-cang-zi-mu.md)

***

如果你正在构建一个动态字符串，你仍然可以在将其值设置给打字机/动画器之前先完成它。

```csharp
int apples = 5; // 稍后从游戏状态中获取
string playerName = "Bob";

// 先构建完整的对话行
string dialogue = $"Hello {playerName}, you've got {apples} apples";

// 然后只设置一次文本
typewriter.ShowText(dialogue);
```

（如果你使用的是对话系统，它们会帮你完成这件事——不用担心！ [集成](/text-animator-unity/3.x-zh/ji-cheng/yi-ji-cheng-de-cha-jian-yu-dui-hua-xi-tong.md))

</details>

<details>

<summary>为什么我应该一次设置整段文本，而不是逐个字符设置？</summary>

性能！(即使你没有使用 Text Animator 也是如此。)

每次设置文本时，TextMeshPro 或 UI Toolkit 都需要计算其网格、位置等，而 Text Animator 随后还要重新计算字符持续时间等。这意味着如果你每秒多次更改文本（例如逐步添加更多字母），每次都要进行这些计算。

要逐个显示字符，你只需先设置一次完整文本，然后启动打字机： [动态显示和隐藏字母](/text-animator-unity/3.x-zh/da-zi-ji/dong-tai-xian-shi-he-yin-cang-zi-mu.md)&#x20;

</details>