> 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 中使用场景编辑器

在世界中放置文本最简单的方法是添加一个 **文本** [智能物品](/creator/content-creator-zh/chang-jing-bian-ji-qi/jiao-hu-xing/smart-items.md) 在场景编辑器中可视化地创建。然后你可以在场景编辑器的 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`.
* `fontSrc`: *字符串*。指向 `.ttf` 字体文件在你的场景中的路径，用于以自定义字体渲染文本。参见 [自定义字体](#custom-fonts).
* `fontSize`: *数字*。字体大小为 10 的实体高度为 1 米。
* `textColor`: *Color4* 对象。 *Color4* 对象存储一个 *RBG* 颜色，表示为三个 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" %}
**📔 注意**：目前，所有字体都以无衬线体渲染。这是一个已知问题，未来会修复。
{% endhint %}

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

### 自定义字体

要用你自己的字体渲染文本，请将 TrueType（`.ttf`) 字体文件添加到你的场景文件夹，并将 `fontSrc` 属性设置为其路径，相对于场景根文件夹（就像 `src` 在 `GltfContainer`中的 `font` 一样设置：它是每当自定义字体无法加载时使用的回退字体。

```ts
TextShape.create(sign, {
	text: '你好，世界',
	fontSize: 5,
	fontSrc: 'assets/fonts/Lobster-Regular.ttf',
	font: Font.F_SANS_SERIF,
})
```

同样的 `fontSrc` 属性也存在于 UI `Label`, `Button`, `Input` 和 `Dropdown` 实体上，以及 `uiText` 在 `UiEntity`上。参见 [UI 中的自定义字体](/creator/content-creator-zh/chang-jing-sdk7/2d-ui/ui_text.md#custom-fonts).

使用自定义字体时请记住以下几点：

* **仅支持 `.ttf` 文件**。该文件必须是真正的 TrueType 字体。带有 CFF 轮廓的 OpenType 字体（通常是 `.otf`）、字体集合（`.ttc`）以及网页字体（`.woff`, `.woff2`）都会被拒绝，文本会使用回退字体进行渲染。 `font`.
* **字体必须是你场景中的一个文件**. `fontSrc` ，不能指向外部 URL，字体族名称（例如来自 Google Fonts 的）也不受支持。下载该 `.ttf` 文件，将其包含到你的场景文件夹中，并引用其路径。请确保该字体的许可证允许重新分发；Google Fonts 上的大多数字体使用 SIL Open Font License，允许这样做。
* **在桌面客户端上，自定义字体只有在场景资源优化后才会显示**。当你发布场景时，其字体会与 3D 模型一起转换为优化后的资源包，转换完成后自定义字体才会出现。在此之前，文本会使用回退字体 `font`。在自定义字体支持之前发布的场景，只有在再次发布时才会转换其字体。这同样适用于本地预览：自定义字体只有在使用优化后的资源进行预览时才会显示（Creator Hub 中的 **压缩资源** 选项，或 `npm run start -- --asset-bundles` （来自 CLI）。参见 [使用优化后的资源进行预览](/creator/content-creator-zh/chang-jing-sdk7/ru-men/preview-scene.md#preview-with-optimized-assets)。Bevy 网页客户端会直接加载 `.ttf` 文件，因此自定义字体会立即显示，在本地预览中也是如此。
* **不支持移动端**。Decentraland 移动应用会忽略 `fontSrc` 并渲染回退字体 `font`。请选择一个看起来仍然合适的回退字体，不要依赖自定义字体来让文本适配固定空间。参见 [移动端缺失的功能](/creator/content-creator-zh/mian-xiang-yi-dong-duan-gou-jian/yi-dong-ke-hu-duan/missing-features.md).
* **字体文件最大不能超过 16 MB**。更大的文件会被拒绝，并使用回退字体 `font` 。字形轮廓极其复杂的字体也可能会被拒绝。
* **字符**：拉丁字符（ASCII 和 Latin-1）会预渲染。字体包含的其他字符，如西里尔文或中文，会在它们第一次出现在场景中时渲染，这可能会造成短暂卡顿。字体不包含的字符会使用内置无衬线字体绘制。
* **字体是共享的**：所有使用相同 `fontSrc` 的文本实体都会共享同一份字体副本，因此在场景中重复使用一种字体的成本不高于只使用一次。尽量少用几种字体，而不是很多不同的字体，因为每种字体都有自己的纹理。每个字体文件都会增加大约 700 KB 的优化下载。

当桌面客户端无法使用自定义字体时，它会在控制台记录一条消息，说明正在使用回退字体，但不会给出原因。如果你看到这条信息，请检查该文件是否为 TrueType `.ttf` ，且大小小于 16 MB，然后重新发布。

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

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

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

{% hint style="info" %}
**💡 提示**：如果文本需要悬浮在空间中，最好添加一个 [`Billboard` 组件](/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* 对象存储一个 *RBG* 颜色，表示为三个 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* 对象存储一个 *RBG* 颜色，表示为三个 0 到 1 之间的数字。

## 多行

如果你希望文本跨越多行，请使用 `\n` 作为字符串的一部分。以下示例有两行独立的文本：

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

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

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

## 将文本按列布局

空格和制表符在 `TextShape`中不能对齐成列，甚至使用 `Font.F_MONOSPACE`也不行。用空格填充记分板会得到参差不齐的列，只要姓名或数字长度变化，列就会立刻移位。

要构建表格，请每列使用一个 `TextShape` 。为每一列分配自己的实体，设置其位置，并把行放入它的 `text` 字段中，并用 `\n`分隔。这样每一行在所有列中都处于同一高度。

```ts
// 一个两列表板：一个 TextShape 用于姓名，一个用于分数
const board = engine.addEntity()
Transform.create(board, { position: Vector3.create(8, 2, 8) })

const names = engine.addEntity()
Transform.create(names, { parent: board, position: Vector3.create(-1, 0, 0) })
TextShape.create(names, {
	text: 'Ana\nBruno\nChiara',
	textAlign: TextAlignMode.TAM_MIDDLE_LEFT,
	fontSize: 2,
})

const scores = engine.addEntity()
Transform.create(scores, { parent: board, position: Vector3.create(1, 0, 0) })
TextShape.create(scores, {
	text: '120\n85\n9',
	textAlign: TextAlignMode.TAM_MIDDLE_RIGHT,
	fontSize: 2,
})
```

将每一列朝列与列之间的空隙对齐： `TAM_MIDDLE_LEFT` 用于左列， `TAM_MIDDLE_RIGHT` 用于右列。数字最好右对齐，这样数字位会对齐。

要更新一行，请重写每一列的整个 `text` 字符串。让每一列中的行数保持一致，否则各行就不再对应了。


---

# 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.