A-Frame中文教程

文本(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

自定义字体

不同的字体可以使用fontfontImage属性来指定。

<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字体,或者使用命令行工具msdfgenmsdf-bmfont

Non-ASCII字符

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

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

最后,应该使用<;meta>;标记指定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)

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

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>

缩放几何体以适应文本

要使几何图形与文本自动缩放,请设置几何体组件的widthheight属性设置为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>

注意,如果geometrytext都不指定宽度,则文本width属性将默认为1个单位(米),而几何体的宽度也将变成1个单位。

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

限制

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

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

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

更多阅读

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