UI 文本

在 UI 实体中写入文本。

通过创建一个 Label 实体，从玩家摄像机位置向前追踪一条射线。

一个 Label 实体具有以下可配置字段：

• 值：要显示的字符串

• 字体大小：文本大小，以数字表示。

  注意：该 字体大小 不受其实体或父实体大小的影响。

• 颜色：文本颜色，作为一个 Color4.

• 字体：要使用的字体。支持的值有：

  • 'serif'

  • 'sans-serif' （默认）

  • 'monospace'

• 文本对齐：文本如何与其父级对齐。它取自以下类型的值： TextAlignType 类型。TextAlignType = 'top-left' | 'top-center' | 'top-right' | 'middle-left' | 'middle-center' | 'middle-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';

• textWrap：设置文本是否使用换行来防止超过最大宽度。默认开启（'wrap'），如需关闭，请传入值 'nowrap'.

📔 注意： 字体大小 不受其实体或父实体大小的影响。

一个 Label 实体也可以拥有其他类型 UI 实体中常见的组件，例如 uiTransform 和 uiBackground.

ui.tsx 文件：

import { UiEntity, Label, ReactEcs } from '@dcl/sdk/react-ecs'
import { Color4 } from '@dcl/sdk/math'

export const uiMenu = () => (
	<UiEntity uiTransform={{ width: 'auto', height: 'auto' }}>
		<Label
			value="这是一个标签"
			color={Color4.Red()}
			fontSize={29}
			font="sans-serif"
			textAlign="top-left"
		/>
	</UiEntity>
)

index.ts 文件：

import { ReactEcsRenderer } from '@dcl/sdk/react-ecs'
import { uiMenu } from './ui'

export function main() {
    ReactEcsRenderer.setUiRenderer(uiMenu, { virtualWidth: 1920, virtualHeight: 1080 })
}

📔 注意：本页中的以下所有代码片段均假定你有一个 .ts 与上文类似，并运行 ReactEcsRenderer.setUiRenderer() 函数。

如果一行文本太长，无法适应分配的宽度，或者其容器的最大宽度，文本将继续显示在下一行。你可以通过更改以下项的值来禁用此功能： textWrap 属性设为 'nowrap'.

你也可以通过显式添加 \n 到字符串中来强制换行。

import { UiEntity, Label, ReactEcs } from '@dcl/sdk/react-ecs'

export const uiMenu = () => (
	<UiEntity uiTransform={{ width: 700, height: 400 }}>
		<Label 
			value="你好，世界！\n另一部分相当长。它大概无法在单行中显示，所以会在某处换行。\n第四行"
			textWrap= {`nowrap`} 
		/>
	</UiEntity>
)

如果没有显式 height 或 width 设置在 uiTransform 容器上，容器将使用值 auto，它会自动调整以适应所有文本。你可以设置一个 maxWidth 和一个 maxHeight 以确保它不会超过某些限制。你还可以使用 minWidth 和 minHeight 以确保容器不会变得过小，即使文本更短也是如此。

📔 注意：不要依赖文本的自动适配。一个 Label 在你不设置大小时所占用的空间在不同浏览器中有所不同。基于 Bevy 的浏览器会测量渲染后的文本并据此布局。Unity 浏览器几乎不给它任何高度，但仍会绘制字母，因此堆叠的标签会彼此重叠，而父级如果根据其文本来设置大小则会塌缩为零。

给每个 Label 一个显式的 width 和 height 在其 uiTransform，并为任何堆叠标签的容器显式设置高度。对于换行文本，请按行数设置高度：两行在 fontSize: 20 大约需要 height: 60.

由于这在不同浏览器中有所不同，在一个客户端中看起来正确的预览，并不能证明在另一个客户端中的布局也正确。

不要在 UI 文本中使用表情符号

在任何 Label 或 按钮 值, uiText.value, 输入框 占位符，以及 下拉框 选项。

SDK 不包含表情符号字形。表情符号是否显示取决于每个浏览器捆绑的字体，而 Unity 浏览器没有这些字体，因此字符会显示为空框或完全消失。同样的注意事项也适用于其他装饰性 Unicode 字符，例如箭头和框线字符。

如果要做图形标签，请改用图像：把图片放在一个小的 UiEntity 中，放在文本旁边，使用一个 uiBackground 并配合一个 纹理。见 UI 背景.

import { UiEntity, ReactEcs } from '@dcl/sdk/react-ecs'
import { Color4 } from '@dcl/sdk/math'

export const uiMenu = () => (
	<UiEntity
		uiTransform={{
			minWidth: 100,
			maxWidth: 300,
			height: 'auto',
			alignSelf: 'center',
			padding: 10,
		}}
		uiBackground={{
			color: Color4.Red(),
		}}
		uiText={{
			value: '你好，世界！',
			fontSize: 18,
		}}
	/>
)

响应式文本大小

使用 scaleFontSize() 用于提供会根据玩家屏幕尺寸自动调整的字体值的函数。在设置 字体大小 文本 UI 实体的属性时，请传入此函数，而不是单个数字。

import { scaleFontSize } from '@dcl/sdk/react-ecs'
import { UiEntity, ReactEcs } from '@dcl/sdk/react-ecs'
import { Color4 } from '@dcl/sdk/math'

export const uiMenu = () => (
  <UiEntity
    uiTransform={{
      width: 'auto',
      height: 'auto',
      alignSelf: 'center',
      padding: 10,
    }}
    uiText={{
      value: '你好，世界！',
      fontSize: scaleFontSize(15)
    }}
  />
)

该 scaleFontSize() 该函数需要两个参数：

• 字体大小：要使用的基础字体大小。

• scaleUnit （可选）：缩放因子。它决定文本应根据屏幕宽度还是高度进行调整，以及调整幅度的乘数。默认值： 0.39 （一个数字，因此会被解释为相对于 width）。可取值可以是：

  • Number：一个简单数字，在这种情况下它会被解释为相对于 width

  • 以……结尾的字符串 vw：这会使该数字相对于视图宽度。例如 "0.8vw"

  • 以……结尾的字符串 vh：这会使该数字相对于视图高度。例如 "0.8vh"

💡 提示：此函数的工作方式类似于 CSS 的 calc() 函数。

的值 scaleUnit 是窗口宽度或高度的百分比。因此 scaleUnit 为 "100vw" 表示屏幕宽度的 100%，而值 "0.5vw" 表示屏幕宽度的 0.5%。

以下公式 scaleFontSize() 将屏幕宽度或高度乘以 scaleUnit，然后再加上 字体大小 作为第一个参数传入的

final font = fontSize + (screen width * scaleUnit / 100)

例如，下面的代码片段使用了一个 scaleUnit 值为 0.8。若屏幕宽度为 1280px，那么文本大小将变为 25.24，按以下公式计算 15 + (1280 * 0.8 / 100).

📔 注意: scaleFontSize() 返回一个 数字，因此其结果是一个以 虚拟 像素为单位的大小——在绘制之前它仍然会乘以 UI 缩放系数 。在上面的示例中，使用默认的 1920x1080 虚拟屏幕以及宽度为 1280px 的画布，缩放因子为 1280 / 1920 = 0.667，因此文本渲染大约为 16.8px。如果你想要一个直接相对于画布测量、忽略虚拟屏幕的字体大小，请传入一个 vw/vh 字符串 直接 字体大小 传给 fontSize: '1.8vh'.

import { scaleFontSize } from '@dcl/sdk/react-ecs'
import { UiEntity, ReactEcs } from '@dcl/sdk/react-ecs'

export const uiMenu = () => (
  <UiEntity
    uiTransform={{
      width: 'auto',
      height: 'auto',
      alignSelf: 'center',
      padding: 10,
    }}
    uiText={{
      value: '你好，世界！',
      fontSize: scaleFontSize(15, 0.8)
    }}
  />
)

💡 提示：如果你没有不同屏幕尺寸可供测试，可以尝试使用 Web Explorer，并调整运行预览的窗口大小。每次你更改窗口时，文本都会立即调整。

作为 scaleFontSize()的替代方案，传入一个 vw/vh 字符串，直接作为 字体大小 ——例如 fontSize: '1.8vh' ——它根据画布调整文本大小，并完全忽略 UI 缩放因子。不要 不是 使用你自己根据 UiCanvasInformation计算出的系数去乘字体大小：SDK 已经应用过一个系数，参见 响应式 UI 大小.