> 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)

## 创建文本组件

以下示例展示了如何创建一个 `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 = 'new string'
```

## 基本文本属性

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

* `字体`：枚举中的值 `字体`.
* `字体大小`: *数字*。字体大小为 10 的实体高 1 米。
* `textColor`: *Color4* 对象。 *Color4* 对象存储一个 *RBG* 颜色，包含 0 到 1 之间的三个数字，以及 *透明度* 用于透明度。参见 [颜色类型](/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.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` 组件会创建一个带有大小、内边距等属性的文本框。

* `文本对齐`：从 `TextAlignMode` 枚举中选择一个值。可能的值包括垂直（*顶部*, *中间*, *底部*）与水平（*left*, *中心*, *right*）对齐方式的所有组合。
* `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* 对象存储一个 *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` 属性必须为 *真* 才能使用多行。
* `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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.