> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/3d-nei-rong-ji-chu/text.md).

# 文本

如何向场景中添加文本

将文本添加到场景中，使用 `TextShape` 组件。此文本位于一个位置

Decentraland 中的文本支持所有 *utf8* 字符，包括东方字符和特殊字符。

{% hint style="warning" %}
**📔 注意**：此组件适用于场景 3D 空间中的世界内标签和 UI，不适用于玩家的 2D HUD UI。
{% endhint %}

要将文本作为现有实体上的标签添加，一个好的做法是创建第二个实体，并让它具有 `TextShape` 组件，然后将其设为另一个实体的子实体。

## 在 Creator Hub 中使用 Scene Editor

在世界中放置文本最简单的方法是添加一个 **文本** [智能物品](/creator/content-creator-zh/chang-jing-bian-ji-qi/jiao-hu-xing/smart-items.md) ，并在 Scene Editor 中可视化设置。然后你可以在 Scene Editor 的 UI 上设置所有可用字段。

![
](https://2460066822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-e555db49c09743be8685fc9f249cfd2ab00480f0%2Ftext-smart-item.png?alt=media\&token=d9ebef2a-4c56-4439-a5c1-c67792aa6f78)

## 创建文本组件

下面的示例展示了如何创建一个 `TextShape` 组件，并通过代码将其添加到实体中。

```ts
const sign = engine.addEntity()

Transform.create(sign, {
	position: Vector3.create(8, 1, 8),
})

TextShape.create(sign, {
	text: '你好，世界',
})
```

{% hint style="warning" %}
**📔 注意**：如果带有文本组件的实体是另一个实体的子实体，那么它会受到父实体缩放的影响。如果父实体沿其轴进行了不均匀缩放，文本也会因此被拉伸或压缩。
{% endhint %}

{% hint style="warning" %}
**📔 注意**: `TextShape` 组件不可点击。 `PointerEvents` 当用于具有一个 `TextShape` 组件。
{% endhint %}

{% hint style="warning" %}
**📔 注意**: `TextShape` 必须通过

> `import { TextShape } from "@dcl/sdk/ecs"`

参见 [导入](/creator/content-creator-zh/chang-jing-sdk7/ru-men/coding-scenes.md#imports) ，了解如何轻松处理这些内容。
{% endhint %}

## 更改文本值

创建新的文本组件时，你会为其分配一个要显示的字符串。此字符串存储在 `text` 字段中，指向你自己的流媒体基础设施。

字段中。如果你想更改组件显示的字符串，可以随时通过更改一个 `text` 字段来实现，位于组件的 [可变版本](/creator/content-creator-zh/chang-jing-sdk7/bian-cheng-mo-shi/mutable-data.md) 中。

```ts
const mutableText = TextShape.getMutable(myEntity)

mutableText.text = '新字符串'
```

## 基本文本属性

该 `TextShape` 组件具有多个可设置的属性，用于设置文本样式。以下是一些最常见的属性：

* `font`：来自枚举的值 `Font`.
* `字体大小`: *数值*。字体 10 的实体高度为 1 米。
* `textColor`: *Color4* 对象。 *Color4* 对象存储一个 *RGB* 颜色，表示为 0 到 1 之间的三个数字，再加上 *alpha* 用于透明度。参见 [颜色类型](/creator/content-creator-zh/chang-jing-sdk7/3d-nei-rong-ji-chu/color-types.md) 了解更多详情。

```ts
TextShape.create(sign, {
	text: '你好，世界',
	textColor: { r: 1, g: 0, b: 0, a: 1 },
	fontSize: 5,
	font: Font.F_SANS_SERIF,
})
```

## 字体

文本形状可以使用枚举中的字体 `Font`。该枚举目前包含以下字体：

* `Font.F_SANS_SERIF`
* `Font.F_SERIF`
* `Font.F_MONOSPACE`

默认情况下使用 `Font.F_SANS_SERIF`.

```ts
TextShape.create(sign, {
	text: '你好，世界',
	textColor: { r: 1, g: 0, b: 0, a: 1 },
	fontSize: 5,
	font: Font.F_SANS_SERIF,
})
```

{% hint style="warning" %}
**📔 注意**：目前，所有字体都会以 Sans Serif 渲染。这是一个已知问题，未来会修复。
{% endhint %}

{% hint style="info" %}
**💡 提示**：如果使用 VS studio 或其他 IDE，输入 `Font.` ，你应该会看到包含所有可用字体的建议列表。
{% endhint %}

## 文本对齐和内边距属性

该 `TextShape` 组件会创建一个具有尺寸、内边距等属性的文本框。

* `textAlign`：从 `TextAlignMode` 枚举中选择一个值。可能的值包括垂直（*顶部*, *中间*, *底部*）和水平（*左侧*, *center*, *右侧*）对齐的所有组合。
* `width`: *数值*。文本框的宽度。
* `height`: *数值*。文本框的高度。
* `paddingTop`: *数值*。文本与文本框轮廓之间的空间。
* `paddingRight`: *数值*。文本与文本框轮廓之间的空间。
* `paddingBottom`: *数值*。文本与文本框轮廓之间的空间。
* `paddingLeft`: *数值*。文本与文本框轮廓之间的空间。

{% hint style="info" %}
**💡 提示**：如果文本要悬浮在空间中，最好添加一个 [`广告牌` 组件](/creator/content-creator-zh/chang-jing-sdk7/3d-nei-rong-ji-chu/entity-positioning.md#face-the-user) ，使文本旋转并始终面向玩家且保持可读。
{% endhint %}

## 文本阴影和轮廓属性

文本默认没有阴影，但你可以设置以下值来赋予它类似阴影的效果。

* `shadowBlur`: *数值*
* `shadowOffsetX`: *数值*
* `shadowOffsetY`: *数值*
* `shadowColor`: *Color3* 对象。 *Color3* 对象存储一个 *RGB* 颜色，表示为 0 到 1 之间的三个数字。

```ts
TextShape.create(sign, {
	text: '带阴影的文本',
	shadowColor: { r: 1, g: 0, b: 0 },
	shadowOffsetY: 1,
	shadowOffsetX: -1,
})
```

文本中的字母也可以在其边缘周围具有不同颜色的轮廓。

* `outlineWidth`: *数值*。文本轮廓在各个方向上的宽度，数值范围为 0 到 1。默认情况下 *0*，这会使其不可见。
* `outlineColor`: *Color3* 对象。 *Color3* 对象存储一个 *RGB* 颜色，表示为 0 到 1 之间的三个数字。

## 多行

如果你希望文本占据多行，请使用 `\n` 作为字符串的一部分。下面的示例包含两行独立的文本：

```ts
TextShape.create(sign, {
	text: '这是第一行。\n这是另一行',
})
```

你还可以为多行文本设置以下相关属性：

* `lineCount`: *数值*。文本框中最多可容纳多少行文本。如果未设置，则行数没有限制。 `textWrapping` 属性必须为 *true* 才能使用多于一行。
* `lineSpacing`: *数值*。每一行之间的间距。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/3d-nei-rong-ji-chu/text.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.