文本（text）

优质

小牛编辑

117浏览

2023-12-01

文本组件呈现带符号距离字段（SDF）字体文本。

Example Image

简介

请注意，在3D中渲染文本是困难的。在2d web开发中，文本是最基本的东西，因为浏览器的渲染器和布局引擎处理一切。而浏览器目前尚未对3d环境中的文本提供这么强大的内在支持。在A-Frame中呈现文本还有其他几种不同的方法，包括：

默认情况下，我们选择了基于SDF的文本作为核心组件，因为相对良好的性能和清晰度。此组件使用 mattdesl的three-bmfont-text库

例子

下面是一个基本的文本示例。

<a-entity text="value: Hello World;"></a-entity>

请参见更多示例以查看对齐、定位、基线、缩放和自动调整大小的配置。

打开这些示例场景中的任何一个，点击<ctrl> + <alt> + i打开检查器（Inspector），试试所有可能的配置取值，查看效果！

Inspecting Text

属性

属性描述缺省值

align 多行文本对齐（左、中、右）。 left

alphaTest 如果alpha小于此值，则放弃文本像素。 0.5

anchor 水平定位（左、中、右、对齐）。 center

baseline 垂直定位（顶部、中心、底部）。 center

color 文本颜色。 white

font

要呈现文本的字体，可以是字体（Fonts）

我们可以指定不同的字体，尽管这个过程不像Web字体那么简单。文本组件默认为roboto使用多通道签名距离（MSDF）字体。MSDF有助于保持锐角和边缘。

Stock字体

从A-Frame的内置字体中进行选择。这些字体将从CDN加载。如果希望应用程序脱机工作得更好，请在本地下载这些字体并通过URL指向它们。

Stock MSDF Fonts	URL
roboto	https://cdn.aframe.io/fonts/Roboto-msdf.json

Stock SDF Fonts	URL
aileronsemibold	https://cdn.aframe.io/fonts/Aileron-Semibold.fnt
dejavu	https://cdn.aframe.io/fonts/DejaVu-sdf.fnt
exo2bold	https://cdn.aframe.io/fonts/Exo2Bold.fnt
exo2semibold	https://cdn.aframe.io/fonts/Exo2SemiBold.fnt
kelsonsans	https://cdn.aframe.io/fonts/KelsonSans.fnt
monoid	https://cdn.aframe.io/fonts/Monoid.fnt
mozillavr	https://cdn.aframe.io/fonts/mozillavr.fnt
sourcecodepro	https://cdn.aframe.io/fonts/SourceCodePro.fnt

自定义字体

不同的字体可以使用font和fontImage属性来指定。

<a-entity text="font: mozillavr; value: Via stock font name."></a-entity>
<a-entity text="font: https://cdn.aframe.io/fonts/mozillavr.fnt; value: Via URL."></a-entity>
<a-entity text="text: Hello World; font: ../fonts/DejaVu-sdf.fnt; fontImage: ../fonts/DejaVu-sdf.png"></a-entity>

如果没有指定， fontImage将会是 font的名称，但是后缀会被替换为 .png。比如，如果 font路径以 mozillavr.fnt结束，那么 fontImage贴图将默认为 mozillavr.png。

生成SDF字体

基于stock字体，我们可以使用Hiero生成SDF字体，这是一个位图字体打包工具。参见指南。

我们也可以使用基于Web的MSDF工具来生成MSDF字体，或者使用命令行工具msdfgen 或 msdf-bmfont。

Non-ASCII字符

要使用非ascii字符，需要创建自己的自定义字体。最简单的方法是使用基于Web的MSDF。选择所需的字符集并生成自己的自定义msdf字体zip文件。

下载自定义msdf字体zip文件后，将其解压缩并重命名*.png为*-msdf.png，然后将png和json文件都放到A-Frame目录中。

最后，应该使用&lt；meta&gt；标记指定HTML中使用的字符集，以避免文本被混淆。如果你的文本是乱码，则无法显示。

<html>
  <head>
    <meta charset="UTF-8">
    <script src="https://aframe.io/releases/0.9.2/aframe.min.js"></script>
  </head>
  <body>
    <a-scene>
      <a-sky color="lightblue"></a-sky>
      <a-text value="ABCあいうえお日本語" font="custom-msdf.json" negate="false" scale="2 2 1" position="-2 2 -4"></a-text>
    </a-scene>
  </body>
</html>

尺寸（Sizing）

要更改文本大小，我们可以：

更改width。
更改wrapCount（在给定宽度内大致容纳多少个字符）。
更改wrapPixels。
更改scale组件。
Position文本远近。

Sizing

文本可以通过指定A-Frame单元的宽度进行换行。

如果我们需要定制布局或者需要知道文本的边界，文本的输出长度可以动态地预先计算，比如：

totalWidth = data.value.length * (data.width / data.wrapCount)

自动缩放（Auto-Scaling）

当文本和几何体一起匹配使用，对于一些二维友好的几何体（如，box，plane），文本组件可以缩放、包围或对齐文本，或者可以自动缩放其所关联的几何体来适应文本。

Geometry Alignments

缩放文本以适应几何体

要使文本组件的width属性自动缩放以匹配几何体组件的width，请不要为文本组件指定宽度：

<a-entity
  geometry="primitive: plane; width: 4; height: auto"
  material="color: blue"
  text="value: This text will be 4 units wide."></a-entity>

缩放几何体以适应文本

要使几何图形与文本自动缩放，请设置几何体组件的width和height属性设置为auto，并设置文本组件的宽度。在本例中，平面的width将被设置为4个单位，其height将被设置为文本同等高度：

<a-entity
  geometry="primitive: plane; height: auto; width: auto"
  material="color: blue"
  text="width: 4; value: This text will be 4 units wide."></a-entity>

注意，如果geometry或text都不指定宽度，则文本width属性将默认为1个单位（米），而几何体的宽度也将变成1个单位。

<a-entity
  geometry="primitive: plane"
  material="color: blue"
  text="value: 1-wide\ndefault."></a-entity>

限制

文本组件没有利用three-bmfont-text库及其姊妹模块。

SDF字体渲染倾向于生成平滑的锐边。

生成的文本不适用于raycaster交叉测试。对于光线投射器或光标检测，可以将几何体组件与文本组件一起使用。