≡

A-Frame中文教程

1.1.0 › 组件

文本（text）

文本组件呈现带符号距离字段（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 要呈现文本的字体，可以是A-Frame的stock字体或者一个字体的URL default
fontImage 字体图像渲染文本的纹理路径。默认为font名称后缀替换为.png。如果使用的是stock字体，则不需要指定该值。 从字体名称派生
height 文本块的高度。 从文本大小派生
letterSpacing 以像素为单位的字母间距。 0
lineHeight 以像素为单位的行高。 从字体文件派生
opacity 不透明度，范围从0到1，其中0表示完全透明，1表示完全不透明。 1.0
shader 用于渲染文本的着色器。 sdf
side 要渲染的边。（front, back, double） front
tabSize 以空格计算的缩进字数 4
transparent 文本是否透明。 true
value 文本的实际内容。换行符和制表符通过 \n和 \t来支持。 ‘’
whitespace 如何处理空白（即normal、pre、nowrap）。 关于whitespace. normal
width 宽度（米）。 如果存在，则从几何体中导出
wrapCount 字符数多少后可以换行。 40
wrapPixels 像素数多少后可以换行。 从wrapCount派生
zOffset 如果将几何体用作背景，则应用z-offset以避免z-fighting。 0.001

该实现基于mattdesl’s three-bmfont-text. 阅读有关文本属性的更多信息.

字体（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中使用的字符集，以避免文本被混淆。如果你的文本是乱码，则无法显示。

在线试试：a-frame text组件使用自定义字体来实现中文文本显示

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

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

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交叉测试。对于光线投射器或光标检测，可以将几何体组件与文本组件一起使用。

更多阅读

下面是一些文本渲染相关的背景阅读链接：