Babylon.GUI是一个基于Babylon.js的WebGL库，可以用来在WebGL3D场景中生成交互性UI与动态纹理。相比于html ui，Babylon.GUI的功能较为简化，但使用起来也更加简单，并且具备一些适用于3D编程的独有特性。如果你正寻找一款适用于h53d场景的ui库，这也许正是你所需要的。
为了减少误解，翻译正文使用中英文对照方式呈现，官方教程原地址：http://doc.babylonjs.com/overviews/gui
overviews
概述
Babylon.GUI: How to create 2D and 3D UI
如何建立2D和3D的UI
Table of contents
内容列表
- Introduction 简介
- AdvancedDynamicTexture 高级动态纹理
- General properties 一般属性
- Events 事件
- Bubbling Phase 冒泡阶段
- Parameters 参数
- Alignments 分组对齐
- Position and size 位置和尺寸
- Tracking positions 追踪位置
- Adaptive scaling 适应性缩放
- Rotation and Scaling 姿态和缩放
- Controls 被控对象
- TextBlock 文本框
- Resize to Fit 重新调整大小以适应内容
- InputText 文本输入框
- Button 按钮
- Visual animations 可视的动画
- Custom button 自定义的按钮
- Checkbox 复选框
- RadioButton 单选框
- Slider 滑块
- Line 线
- Image 图片
- VirtualKeyboard 虚拟键盘
- Containers 容器
- Rectangle 矩形
- Ellipse 椭圆
- StackPanel 堆栈面板
- ColorPicker 拾色器
- Helpers 帮助
- Focus management 焦点管理
Babylon.GUI
The Babylon.js GUI library is an extension you can use to generate interactive user interface. It is build on top of the DynamicTexture.
Babylonjs的GUI库是一个可以用来建立交互性用户接口的扩展。它建立在动态材质的基础上
The latest version can be found here: https://github.com/BabylonJS/Babylon.js/tree/master/dist/preview%20release/gui.
最新的版本可以在这里找到
And the source code is available on the main Babylon.js repo: https://github.com/BabylonJS/Babylon.js/tree/master/gui.
同时代码可以在Babylonjs的主报告找到。
You can find a complete demo here: http://www.babylonjs.com/demos/gui/
你可以在这里找到一个完整的示例
Introduction
简介
Babylon.GUI uses a DynamicTexture to generate a fully functionnal user interface.
Babylon.GUI使用一个动态纹理来建立一个具有完全功能的用户接口。
The user interface can be full screen or projected onto any 3d object.
这个用户接口可以是全屏的也可以在一个3D对象上编制。
AdvancedDynamicTexture
高级动态纹理
To begin with Babylon.GUI, you first need an AdvancedDynamicTexture object.
要开始使用Babylon.GUI,你首先需要一个高级动态纹理对象。
Babylon.GUI has two modes:
Babylon.GUI具有两种模式
- Fullscreen mode: In this mode, Babylon.GUI will cover the entire screen and will rescale to always adapt to your rendering resolution. It will also intercept clicks (including touches). To create an AdvancedDynamicTexture in fullscreen mode, just run this code:
- 全屏模式：在这种模式下，Babylon.GUI将覆盖整个屏幕，并且将一直根据渲染的分辨率自动缩放。它将捕获点击（包括触摸）。要建立一个全屏模式的高级动态材质，只需运行以下代码：
varadvancedTexture = BABYLON.GUI.AdvancedDynamicTexture.CreateFullscreenUI("myUI");
Here is an example of a simple fullscreen mode GUI: https://www.babylonjs-playground.com/#XCPP9Y#1 -
这里是一个全屏模式GUI的例子
- Texture mode: In this mode, BABYLON.GUI will be used as a texture for a given mesh. You will have to define the resolution of your texture. To create an AdvancedDynamicTexture in texture mode, just run this code:
- 纹理模式：在这种模式下，BABYLON.GUI将作为某一个网格的纹理被使用。你必须定义你的纹理的分辨率。要建立一个纹理模式的高级动态纹理，只需运行以下代码：
varadvancedTexture2 = BABYLON.GUI.AdvancedDynamicTexture.CreateForMesh(myPlane,1024,1024);
Here is an example of a simple texture mode GUI: https://www.babylonjs-playground.com/#ZI9AK7#1 -
这里是一个纹理模式GUI的例子
Please note that handling pointer move events could be costly on complex meshes, so you can turn off supporting pointer move events with a fourth parameter:
请注意在复杂的网格上处理指针移动事件对性能的消耗很大，所以你可以通过第四个参数来关闭对指针移动事件的支持：
varadvancedTexture2 = BABYLON.GUI.AdvancedDynamicTexture.CreateForMesh(myPlane,1024,1024,false);
Once you have an AdvancedDynamicTexture object, you can start adding controls.
在你拥有一个高级动态纹理对象之后，你可以开始添加被管对象
General properties
通用的属性
Events
事件
All controls have the following observables:
所有的被管对象都具有以下的可监听项：
|
Observables 可监听项 |
Comments 注释 |
|
onPointerMoveObservable |
Raised when the cursor moves over the control. Only available on fullscreen mode 当光标从被管对象上经过时触发。只在全屏模式下有用 |
|
onPointerEnterObservable |
Raised when the cursor enters the control. Only available on fullscreen mode 当光标进入被管对象时触发。只在全屏模式下有用。 |
|
onPointerOutObservable |
Raised when the cursor leaves the control. Only available on fullscreen mode 当光标离开被管对象时触发。只在全屏模式下有用 |
|
onPointerDownObservable |
Raised when pointer is down on the control. 在指针在被管对象上按下时触发。 |
|
onPointerUpObservable |
Raised when pointer is up on the control. 当指针在被管对象上抬起时触发。 |
|
onDirtyObservable |
Raised when the control is marked as dirty. 当被管对象被标记为垃圾时触发 |
|
onAfterDrawObservable |
Raised after control is drawn. 当被管对象绘制完成时触发 |
You can also define that a control is invisble to events (so you can click through it for instance). To do so, just call control.isHitTestVisible.
你也可以将一个被管对象定义为对事件不可见（比如你可以让点击穿过它）。要做到这一点，只需使用control.isHitTestVisible属性
Please note that onPointerMoveObservable, onPointerDownObservable and onPointerUpObservable will receive a Vector2WithInfo parameter containing the pointer coordinates (x, y) and the index of the button pressed (buttonIndex). If you want to get the pointer coordinates in local control space, you have to call control.getLocalCoordinates(coordinates).
请注意onPointerMoveObservable、onPointerDownObservable和onPointerUpObservable将获取一个带有信息的二元向量参数，这个参数包含光标的坐标（x，y）以及被按下的按钮的索引（buttonIndex）。如果你想要在本地控制空间（指这个被控对象的局部坐标系，以左上角为零点）获得光标坐标，你必须使用control.getLocalCoordinates(coordinates).
Here is an example of how to use observables: https://www.babylonjs-playground.com/#XCPP9Y#281 -
这是一个如何使用监听器的例子：
Bubbling Phase
冒泡阶段
onPointerMoveObservable, onPointerEnterObservable, onPointerDownObservable, onPointerUpObservable have a bubbling phase. When an event is notified in one of these observables inside a control, it'll subsequently be notified from the same observable in its parent, recursively, until there are no more parents.
onPointerMoveObservable, onPointerEnterObservable, onPointerDownObservable, onPointerUpObservable具有一个冒泡阶段。当一个事件被一个被控对象内的监听器发现时，它也将随后被这个被控对象的父元素的监听器发现，递归的向上传播，直到没有更多的父元素。
The EventState passed as the second argument to the callback contains the properties target and currentTarget that allow you to track the bubbling phase.
事件状态被作为回调函数的第二个参数传递，它包含这个事件的所属目标和当前目标，这允许你追踪冒泡阶段。
Parameters
参数
|
Property 属性 |
Type 类型 |
Default 默认 |
Comments 注释 |
|
target |
any |
null |
The object that originally notified the event 最初发现这个事件的对象 |
|
currentTarget |
any |
null |
The current object in the bubbling phase 冒泡阶段中的当前对象 |
Here is an example of bubbling: http://www.babylonjs-playground.com/#7EPK2H -
这是一个冒泡的例子
Alignments
分组对齐
You can define the alignments used by your control with the following properties:
你可以使用下列的属性定义你的被控对象使用的分组
|
Property 属性 |
Default 默认 |
Comments 注释 |
|
horizontalAlignment |
BABYLON.GUI.Control.HORIZONTAL_ALIGNMENT_CENTER |
Can be set to left, right or center. 可以被设为左右或中间 |
|
verticalAlignment |
BABYLON.GUI.Control.VERTICAL_ALIGNMENT_CENTER |
Can be set to top, bottom and center. 可以被设为顶部底部或中间 |
Here is an example of how to use alignments: https://www.babylonjs-playground.com/#XCPP9Y#13 -
这是一个如何使用分组对齐的例子
Position and size
位置和尺寸
You can set controls' position with the following properties:
你可以使用如下的属性设置被控对象的位置：（这里的位置设定是在分组对齐基础上的修正位置，类似于dom中的相对定位）
|
Property |
Type |
Default |
Default unit |
|
left |
ValueAndUnit |
0 |
Pixel |
|
top |
ValueAndUnit |
0 |
Pixel |
Size can be set with:
可以这样设置尺寸
|
Property |
Type |
Default |
Default unit |
|
width |
ValueAndUnit |
100%，1，“1024px” |
Percentage |
|
height |
ValueAndUnit |
100% |
Percentage |
Paddings can be set with:
可以这样设置内边距
|
Property |
Type |
Default |
Default unit |
|
paddingTop |
ValueAndUnit |
0px |
Pixel |
|
paddingBottom |
ValueAndUnit |
0px |
Pixel |
|
paddingLeft |
ValueAndUnit |
0px |
Pixel |
|
paddingRight |
ValueAndUnit |
0px |
Pixel |
Please note that paddings are inside the control. This means that the usableWidth = width - paddingLeft - paddingRight. Same for usableHeight = height - paddingTop - paddingBottom.
请注意内边框是在被控对象内部的。这意味着可用的宽度=被控对象宽度-左侧内边距-右侧内边距。同样的，可用高度=被控对象高度-顶部内边距-底部内边距
All these properties can be defined using pixel or percentage as unit. To set value as pixel, use this construct: control.left = "50px" To set value as percentage, use this construct: control.left = "50%"
所有的这些属性可以以像素或百分比为单位进行定义。要把值设为像素数时，使用这个表达式：control.left = "50px" ，要把值设为百分比时，使用这个表达式：control.left = "50%"
You can also not define the unit (In this case the default unit will be used): control.width = 0.5 (which is equivalent to control.width = "50%").
你也可以不定义这个单位（这时使用默认的单位）：control.width = 0.5（等效于control.width = "50%"）
For all properties of type ValueAndUnit, you can find an associated readonly property named xxxInPixels. For instance, left works with leftInPixels which is a the left property in pixels. So if left = "50%" and the control's parent width is 150px then leftInPixels will be 75.
对于所有“值和单位”类型的属性，你可以找到一个相关的只读属性叫做xxxInPixels。举例来说，left属性具有leftInPixels属性，这个子属性使用像素表示的left属性的值。所以如果设置left = "50%"而被控对象的父元素的宽度是150像素则leftInPixels的值是75
Here is an example of how to use positions and sizes: https://www.babylonjs-playground.com/#XCPP9Y#14 -
这是一个如何使用位置和尺寸的例子
Tracking positions
位置追踪
All controls can be moved to track position of a mesh. To do this, just call control.linkWithMesh(mesh). You can then offset the position with control.linkOffsetX and control.linkOffsetY.
所有的被管对象都可以移动来追踪一个网格的位置。要做到这一点，只需要调用control.linkWithMesh(mesh).然后你可以通过control.linkOffsetX 和 control.linkOffsetY来设置被管对象与网格之间的相对位置。
Here is an example of a trackable label: https://www.babylonjs-playground.com/#XCPP9Y#16 -
这里是一个具有追踪能力的标签的例子
Please note that controls that want to track position of a mesh must be at root level (at AdvancedDynamicTexture level).
请注意，追踪网格位置的被管对象必须是在根层（直接被高级动态纹理这一层管理）的
You can also move a control to a specific coordinates in your scene with control.moveToVector3(position). Please note that the control will not stick with the vector if you change it afterwards.
你也可以将一个被管对象移动到场景中一个特定的坐标，通过control.moveToVector3(position).请注意这个被管对象将不会保持在这个三元向量的位置（而是保持在全屏ui的位置？）如果你稍后修改它的话
For Line control, you can also attach the second point to a control with line.connectedControl = control. In this case the x2 and y2 properties are used to offset the second point from the connected control.
对于线段被管对象，你还可以通过line.connectedControl = control将线段的第二个点绑定到另一个被管对象上。在这时x2和y2属性被用来设定第二个点相对于被连接的被管对象的位置。
With these 2 options, you can create a complete trackable label: https://www.babylonjs-playground.com/#XCPP9Y#20 -
使用这两个选项，你可以建立一个具有完全追踪能力的标签：
（这些标签的一个不足是不能使用超文本标记语言来更方便的定义，而只能使用js对象方式定义）
Adaptive scaling
适应性缩放
When in fullscreen UI, you can decide to define your UI with a fixed resolution. To define this resolution, just set myAdvancedDynamicTexture.idealWidth = 600 or myAdvancedDynamicTexture.idealHeight = 400.
在全屏UI中，你可以选择给UI定义一个固定的分辨率。要定义这个分辨率，只需设置myAdvancedDynamicTexture.idealWidth = 600 或 myAdvancedDynamicTexture.idealHeight = 400.
If both are set, the idealWidth will be used.
如果都设置了，将以idealWidth为主（看来改变分辨率后全屏ui仍然是铺满整个视口的，顶层UI的宽高比是视口的宽高比）
When ideal resolution is set, all values expressed in pixels are considered relatively to this resolution and scaled accordingly to match the current resolution.
在设置了理想分辨率之后，所有用像素表示的值都被认为是相对于这个分辨率的，并且会依此调整来适应当前的分辨率。（也就是比例不变？）
Even when ideal size is set, the fullscreen UI will be rendered at the same resolution of your canvas, but you can decide (mostly for performance reason) to force the texture to use the ideal size for resolution as well. To do so, just call myAdvancedDynamicTexture.renderAtIdealSize = true.
即使设定了理想尺寸，全屏UI仍会按照你的canvas的大小来绘制，但是你也可以决定强制纹理使用这个理想的尺寸作为分辨率（主要是为了性能）。要做到这一点，只需设置myAdvancedDynamicTexture.renderAtIdealSize = true.
Here is an example of how to use horizontal adaptive scaling: https://www.babylonjs-playground.com/#XCPP9Y#39 -
这里是一个如何使用水平适应性缩放的例子
Rotation and Scaling
旋转和缩放
Controls can be transformed with the following properties:
被管对象可以通过下列属性进行变形
|
Property |
Type |
Default |
Comments |
|
rotation |
number |
0 |
Value is in radians 弧度值 |
|
scaleX |
number |
1 |
|
|
scaleY |
number |
1 |
|
|
transformCenterX |
number |
0.5 |
Define the center of transformation on X axis. Value is between 0 and 1 定义X方向变形中心的位置，取值在0到1之间。（以这个点为轴旋转） |
|
transformCenterY |
number |
0.5 |
Define the center of transformation on Y axis. Value is between 0 and 1 |
Please be aware that transformations are done at rendering level so after all computations. This means that alignment or positioning will be done first without taking transform in account.
请明确这一点，这些变形是在渲染层（APU）进行的，它们发生在这一帧所有的计算（CPU）之后。这意味着分组和定位会在不考虑变形的情况下先发生
Here is an example of how to use rotation and scaling: https://www.babylonjs-playground.com/#XCPP9Y#22 -
这里是一个如何使用旋转和缩放的例子
Controls
被控制对象
A control is an abstraction of a piece of UI. There are two kinds of controls:
被控制对象是UI的一片区域的抽象。有两种被控制对象：
- Pure controls: A pure control defines an action or an information useful for the user. It could be a TextBlock or a Button.
- 纯粹的被控制对象：纯粹的被控制对象定义一个对用户有用的行为或者信息。它可能是一个文本框或者一个按钮。
- Containers: Containers are used to organize your UI. They can contain other controls or containers.
- 容器：容器被用来组织你的UI，它们可以包含其他的被控制对象或者容器。
All controls share the following properties:
所有的被控制对象具有以下的属性
|
Property |
Type |
Default |
Comments |
|
alpha |
number |
1 |
Between 0 and 1. 0 means completely transparent. 1 means fully opaque 在0和1之间，0意为着完全的透明，1意味着完全的不透明 |
|
color |
string |
Black |
Foreground color 前景颜色 |
|
fontFamily |
string |
Arial |
Font family can be inherited. This means that if you set it on a container, it will be transmitted to all children of the container 字体可以是继承的。这意味着如果你在一个容器上设置了它，它将被传递到这个容器的所有子元素上。 |
|
fontStyle |
string |
Empty string |
Can be inherited. Value can be "italic", "bold" or "oblique" 字形可以被继承。取值可以是“细斜体”、“粗体”或者“斜体” |
|
fontSize |
number |
18 |
Can be inherited 字号可以被继承 |
|
zIndex |
number |
0 |
the zIndex can be used to reorder controls on the z axis 可以被用来在z轴上对被管对象进行排序 |
Controls can be added directly to the AdvancedDynamicTexture or to a container with:
被管对象可以被直接添加给高级动态纹理或者容器，通过：
container.addControl(control);
They can be removed with:
它们可以被移除
container.removeControl(control);
You can also control the control visibility with control.isVisible = false.
你也可以控制被管对象的可见性通过control.isVisible = false.
TextBlock
文本框
The TextBlock is a simple control used to display text: https://www.babylonjs-playground.com/#XCPP9Y#2 -
文本框是一个用来显示文字的简单被管对象：
Here are the properties you can define:
这里是你可以定义的属性
|
Property |
Type |
Default |
Comments |
|
text |
string |
null |
Text to display 要显示的文字 |
|
textWrapping |
boolean |
false |
Can be set to true to enable text wrapping 可以设置为true来允许换行 |
|
resizeToFit |
boolean |
false |
Can be set to true to enable resize to fit 可以设置为true来允许根据内容改变尺寸 |
|
textHorizontalAlignment |
number |
BABYLON.GUI.Control.HORIZONTAL_ALIGNMENT_CENTER |
Can be set to left, right or center可以设为左右或中间 |
|
textVerticalAlignment |
number |
BABYLON.GUI.Control.VERTICAL_ALIGNMENT_CENTER |
Can be set to top, bottom or center 可以设为上下或中间 |
The control currently provides 1 observable:
暂时这种被管对象只提供一个专有的监听器
|
Observables |
Comments |
|
onTextChangedObservable |
Raised when the text has changed 在文字内容改变时触发 |
Resize to Fit
适应性尺寸调整
When resizeToFit is set to true, the width and height of the rendered text will be automatically measured and applied to the TextBlock.
当适应性尺寸调整被设为true时，被渲染的文字的宽度和高度将被自动的计算，然后应用到文本框上（也就是字的大小不变，改变文本框的大小）
This property allows you to change the text and font of a TextBlock without having to worry about manually setting the estimated rendered width and height.
这个属性允许你改变文本框的文字和字体，而不必担心人工的设置文本框预计渲染的宽度和高度
Notice that textWrapping is ignored when resizeToFit is set to true. It doesn't make sense logically for both properties to be used at the same time as they contradict each other.
注意当适应性尺寸调整被设为真时，文字换行将被忽略。同时使用这两个属性在逻辑上没有意义，因为它们相互矛盾。
InputText
文本输入框
The InputText is a control used to let users insert text in a single line: https://www.babylonjs-playground.com/#UWS0TS -
文本输入框是一个被管对象，用来支持用户在一个单行中插入文字：
（实际测试发现这个输入和删除是有延迟的，并不完全可信）
Here are the properties you can define:
这里是你可以定义的属性
|
Property |
Type |
Default |
Comments |
|
text |
string |
null |
Text to display 要显示的文字 |
|
color |
string |
white |
Foreground color 前景颜色 |
|
background |
string |
#222222 |
Background color 背景颜色 |
|
focusedBackground |
string |
black |
Background color to use when the control is focused 在这个被管对象获得焦点时使用的背景颜色 |
|
placeholderText |
string |
null |
Text to display as placeholder (when there is no text defined and the control is not focused) 作为占位显示的文本（当输入框中没有定义文本并且没有获得焦点时） |
|
placeholderColor |
string |
gray |
Foreground color to use when the placeholder text is displayed 在显示占位文本时使用的前景色 |
|
autoStretchWidth |
boolean |
true |
The control will resize horizontally to adapt to text size 被管对象将水平调整大小来适应文本尺寸 |
|
maxWidth |
ValueAndUnit |
100% |
The maximum width allowed if autoStretchWidth is set to true 在自动调整宽度被启用时所允许的最大宽度 |
|
margin |
ValueAndUnit |
10px |
Margin to use on left and right inside the control itself. This margin is used to determine where the text will be drawn 在被管对象内部文字左右两侧的外边距。这个外边距用来决定文字绘制在哪里。 |
|
thickness |
number |
1 |
Thickness of the border 边框的厚度 |
The InputText is a focusable control. This means you can click / touch it in order to give it the focus and control over the keyboard events. You can remove the focus from the control by hitting enter or clicking outside of the control.
文本输入框是一个可以获取焦点的被管对象。这意味着你可以通过点击或者触摸把焦点赋予这个被管对象，然后可以通过键盘事件进行控制。你可以从被管对象移除这个焦点，通过敲击回车或者点击被管对象的外部。
The control provides several observables to track its state:
这种被管对象提供了一些监听器来追踪它的状态：
|
Observables |
Comments |
|
onTextChangedObservable |
Raised when the text has changed 当文字改变时触发 |
|
onFocusObservable |
Raised when the control loses the focus 失去焦点时触发 |
|
onBlurObservable |
Raised when the control gets the focus 获得焦点时触发 |
Please note that the InputText has pretty limited edition support. Here are the supported keys:
请注意这个文本输入框只具有有限的编辑支持。这里是它支持的按键：
- Delete
- Backspace
- Home
- End
- Enter
- Left / Right (used to move the cursor)
Furthermore, please note that due to JavaScript platform limitation, the InputText cannot invoke the onscreen keyboard. On mobile, the InputText will use the prompt() command to get user input. You can define the title of the prompt by setting control.promptMessage.
更进一步的，请注意因为JavaScript的平台限制性，这个文本输入框不能借助显示在屏幕上的键盘（操作系统提供的虚拟键盘）。在移动端，这个文本输入框将使用prompt()命令来获取用户的输入。你可以定义prompt命令的标题，通过设置control.promptMessage.
Button
按钮
A button can be used to interact with your user. Please see the events chapter to see how to connect your events with your buttons.
按钮可以用来与你的用户交互。请浏览事件的章节去了解如何将事件与你的按钮连接
There are four kinds of buttons available out of the box:
有四种可用的按钮
- ImageButton: An image button is a button made with an image and a text. You can create one with:
- 图片按钮:图片按钮是用一张图片（图片与按钮的左边对齐，然后接着是文本）和一段文本组成的按钮。你可以用以下代码建立它：
varbutton = BABYLON.GUI.Button.CreateImageButton("but","Click Me","textures/grass.png");
You can try it here: https://www.babylonjs-playground.com/#XCPP9Y#3 -
你可以在这里试用它
- ImageWithCenterTextButton: An image button made with a image background and a centered text.
- 图片以及居中文本按钮：一个用图片作为背景并且具有一段居中文本的图片按钮
varbutton = BABYLON.GUI.Button.CreateImageWithCenterTextButton("but","Click Me","textures/grass.png");
You can try it here: https://www.babylonjs-playground.com/#PLTRBV -
在这里试用
- SimpleButton: A simple button with text only
- 简单按钮：简单按钮只有文本
varbutton = BABYLON.GUI.Button.CreateSimpleButton("but","Click Me");
You can try it here: https://www.babylonjs-playground.com/#XCPP9Y#4 -
在这里试用
- ImageOnlyButton:
- 只有图片的按钮
varbutton = BABYLON.GUI.Button.CreateImageOnlyButton("but","textures/grass.png");
You can try it here: https://www.babylonjs-playground.com/#XCPP9Y#28 -
在这里试用
Visual animations
可视动画
By default a button will change its opacity on pointerover and will change it scale when clicked. You can define your own animations with the following callbacks:
默认情况下一个按钮将在指针经过时改变不透明度，并且将在被点击时改变缩放。你可以使用以下的回调函数来定义你自己的动画效果
- pointerEnterAnimation
- pointerOutAnimation
- pointerDownAnimation
- pointerUpAnimation
Custom button
用户自定义按钮
You can also create a complete custom button by manually adding children to the button. Here is how the ImageButton is built:
你也可以通过手动的为按钮添加子元素来建立一个完全自定义的按钮。以下是如何构建图片按钮：
varresult =newButton(name);
// Adding text
vartextBlock =newBABYLON.GUI.TextBlock(name +"_button", text);
textBlock.textWrapping =true;
textBlock.textHorizontalAlignment = BABYLON.GUI.Control.HORIZONTAL_ALIGNMENT_CENTER;textBlock.paddingLeft ="20%";
result.addControl(textBlock); // Adding image
variconImage =newBABYLON.GUI.Image(name +"_icon", imageUrl);
iconImage.width ="20%";
iconImage.stretch = BABYLON.GUI.Image.STRETCH_UNIFORM;iconImage.horizontalAlignment = BABYLON.GUI.Control.HORIZONTAL_ALIGNMENT_LEFT;result.addControl(iconImage); return result;
Checkbox
复选框
The checkbox is used to control a boolean value. You can specify the value with checkbox.isChecked.
复选框用来控制一个布尔值。你可以通过checkbox.isChecked来设定这个值。
Changing the isChecked property will raise an observable called checkbox.onIsCheckedChangedObservable.
改变是否被选中属性将触发一个叫做checkbox.onIsCheckedChangedObservable的监听。
The control is rendered using the following properties:
这个被管对象使用如下的属性渲染：
|
Property |
Type |
Default |
Comments |
|
color |
string |
white |
Foreground color 前景颜色 |
|
background |
string |
black |
Background color 背景颜色 |
|
checkSizeRatio |
number |
0.8 |
Define the ratio used to compute the size of the inner checkbox (0.8 by default, which means the inner check size is equal to 80% of the control itself) 定义用来计算复选框内部尺寸的比率（默认是0.8，这意味着内部的区域占被管对象尺寸的80%） |
Here is an example of a checkbox: https://www.babylonjs-playground.com/#U9AC0N#2 -
这里是一个复选框的例子
RadioButton
单选按钮
The radio button is used to define a value among a list by using a group of radio buttons where only one can be true. You can specify the selected value with radiobutton.isChecked.
单选按钮通过一组只能有一个为真的单选按钮来在一个列表中选取一个值。你可以通过radiobutton.isChecked来指定选中的值。
Changing the isChecked property will raise an observable called checkbox.onIsCheckedChangedObservable. Furthermore, if you select a radio button, all other radio buttons within the same group will turn to false.
修改是否选定属性将触发一个叫做checkbox.onIsCheckedChangedObservable的事件。更进一步的，如果你选中了一个单选按钮，所有在同一个组里的单选按钮将转变为假
The control is rendered using the following properties:
这个被管对象使用下列的属性渲染：
|
Property |
Type |
Default |
Comments |
|
color |
string |
white |
Foreground color |
|
background |
string |
black |
Background color |
|
checkSizeRatio |
number |
0.8 |
Define the ratio used to compute the size of the inner checkbox (0.8 by default, which means the inner check size is equal to 80% of the control itself) |
|
group |
string |
empty string |
Use the group property to gather radio buttons working on the same value set 使用分组属性来收集为同一个值工作的单选按钮 |
Here is an example of a radiobutton: https://www.babylonjs-playground.com/#U9AC0N#13 -
这里是一个单选按钮的例子：
Slider
滑块
The slider is used to control a value within a range. You can specify the range with slider.minimum and slider.maximum.
滑块用来在一个范围内控制一个值。你可以使用slider.minimum 和 slider.maximum来指定这个范围
The value itself is specified with slider.value and will raise an observable everytime it is changed (slider.onValueChangedObservable).
这个值本身使用slider.value指定，并且将在它每次改变时触发一个事件（slider.onValueChangedObservable）
The control is rendered using the following properties:
这个被控对象使用下列属性渲染：
|
Property |
Type |
Default |
Comments |
|
borderColor |
string |
white |
Color used to render the border of the thumb 用来渲染小滑块的边缘的颜色 |
|
color |
string |
white |
Foreground color 前景色 |
|
background |
string |
black |
Background color 背景色 |
|
barOffset |
ValueAndUnit |
5px |
Offset used vertically to draw the background bar 绘制背景条的垂直偏移 |
|
thumbWidth |
ValueAndUnit |
30px |
Width of the thumb 小滑块的宽度 |
Here is an example of a slider: https://www.babylonjs-playground.com/#U9AC0N#1 -
这里是一个滑块的例子：
Line
线段
The line will draw a line (!!) between two points.
线段被管对象将在两个点之间画一条线。
Here are the properties you can define:
这里是你可以定义的属性：
|
Property |
Type |
Default |
Comments |
|
x1 |
number |
0 |
X coordinate of the first point 第一个点的X坐标 |
|
y1 |
number |
0 |
Y coordinate of the first point |
|
x2 |
number |
0 |
X coordinate of the second point |
|
y2 |
number |
0 |
Y coordinate of the second point |
|
dash |
array of numbers |
Empty array |
Defines the size of the dashes 定义虚线的尺寸 |
|
lineWidth |
number |
1 |
Width in pixel 以像素表示的宽度 |
Here is an example of a line: https://www.babylonjs-playground.com/#XCPP9Y#6 -
这是一个线段的例子
Image
图片
Use the image control to display an image in your UI. You can control the stretch used by the image with image.stretch property. You can set it to one of these values:
使用图像被控对象在你的UI里显示一张图片。你可以使用image.stretch属性控制这个图片使用的拉伸方式。你可以把它设置为这些值中的一个
- BABYLON.GUI.Image.STRETCH_NONE: Use original size
- 使用原始尺寸
- BABYLON.GUI.Image.STRETCH_FILL: Scale the image to fill the container (This is the default value)
- 缩放图片来填满容器（默认值）
- BABYLON.GUI.Image.STRETCH_UNIFORM: Scale the image to fill the container but maintain aspect ratio
- 缩放图片填满容器，但是保持宽高比
- BABYLON.GUI.Image.STRETCH_EXTEND: Scale the container to adapt to the image size.
- 缩放容器来适应图片的尺寸。
You may want to have the Image control adapt its size to the source image. To do so just call image.autoScale = true.
你可能希望让图片被管对象按照源图片调整尺寸。要做到这一点只需调用image.autoScale = true.
You can change image source at any time with image.source="myimage.jpg".
你可以随时修改图片源通过image.source="myimage.jpg".
You can also define which part of the source image you want to use with the following properties:
你也可以使用以下属性定义你要使用源图片的哪个部分：
- sourceLeft: x coordinate in the source image (in pixel)
- 在源图片中的x坐标（以像素表示）
- sourceTop: y coordinate in the source image (in pixel)
- sourceWidth: width of the source image you want to use (in pixel)
- 你希望使用的部分的宽度
- sourceHeight: height of the source image you want to use (in pixel)
Here is an example of an image: https://www.babylonjs-playground.com/#XCPP9Y#7 -
这是一个使用图片的例子
VirtualKeyboard
虚拟键盘
The VirtualKeyboard is a control used to display simple onscreen keyboard. This is mostly useful with WebVR scenarios where the user cannot easily use his keyboard.
虚拟键盘是一个用来在屏幕上显示简单键盘的被管对象。它通常被使用在WebVR场景中，因为那时用户往往不能方便的使用他的键盘
Keys
按键
You can define the keys provided by the keyboard with the following code:
你可以通过如下的代码定义从键盘提供的按键
varkeyboard =newBABYLON.GUI.VirtualKeyboard();
keyboard.addKeysRow(["1","2","3","4","5","6","7","8","9","0","\u2190"]);
Every key will be created using default values specified by the following properties:
所有的按键将使用默认值建立，可以通过以下属性设定默认值：
|
Property |
Default |
|
defaultButtonWidth 默认按钮宽度 |
40px |
|
defaultButtonHeight 默认按钮高度 |
40px |
|
defaultButtonPaddingLeft 默认按钮左内边距 |
2px |
|
defaultButtonPaddingRight 默认按钮右内边距 |
2px |
|
defaultButtonPaddingTop 上内边距 |
2px |
|
defaultButtonPaddingBottom 下内边距 |
2px |
|
defaultButtonColor 颜色(前景？) |
#DDD |
|
defaultButtonBackground 背景 |
#070707 |
You can also override each property by providing an array containing properties for keys (or null):
你也可以通过提供一个包含按键属性的数组来覆盖每一个属性
addKeysRow(["a","b"], [null, {width:"200px"}]);
You can define each default properties based on the following class:
你可以基于以下的类来定义每个默认属性：
classKeyPropertySet{
width?:string;
height?:string;
paddingLeft?:string;
paddingRight?:string;
paddingTop?:string;
paddingBottom?:string;
color?:string;
background?:string;
}Layouts
布局
The VirtualKeyboard provides a static method to create a default layout:
虚拟键盘提供一个静态方法来建立默认的布局
var keyboard = BABYLON.GUI.VirtualKeyboard.CreateDefaultLayout();
The default layout is equivalent to:
默认的布局是这样的：
addKeysRow(["1","2","3","4","5","6","7","8","9","0","\u2190"]);
addKeysRow(["q","w","e","r","t","y","u","i","o","p"]);
addKeysRow(["a","s","d","f","g","h","j","k","l",";","'","\u21B5"]);
addKeysRow(["z","x","c","v","b","n","m",",",".","/"]);
addKeysRow([" "], [{ width:"200px"}]);
Events
事件
Every time a key is pressed the onKeyPressObservable observable is triggered. But you can also rely on keyboard.connect(inputText) to automatically connect a VirtualKeyboard to an InputText. In this case, the keyboard will only appear when the InputText will be focused and all key pressed events will be sent to the InputText.
每次有按键被按下时onKeyPressObservable事件被触发。但是你也可以依靠keyboard.connect(inputText)来自动的把一个虚拟键盘和一个输入文本框连接起来，这个键盘将只在这个文本输入框获得焦点时出现，并且所有的按键按下事件将被发送到这个文本输入框。
You can find a complete demo here: https://www.babylonjs-playground.com/#S7L7FE -
你可以在这里找到一个完整的示例：
Containers
容器
The containers are controls used to host other controls. Use them to organize your UI. Containers has one specific property: container.background. Use it to define the background color of your container.
容器是用来主持其他被管对象的被管对象。使用他们来组织你的UI。容器有一个独有的属性：container.background.使用它来定义你的容器的背景颜色
Rectangle
矩形
The Rectangle is a rectangular container with the following properties:
矩形是一个具有以下属性的长方形的容器
|
Property |
Type |
Default |
Comments |
|
thickness |
number |
1 |
Thickness of the border 边框的厚度 |
|
cornerRadius |
number |
0 |
Size in pixel of each corner. Used to create rounded rectangles 用像素表示的每个边角的尺寸。用来建立圆角矩形 |
Here is an example of a rectangle control: https://www.babylonjs-playground.com/#XCPP9Y#8 -
这里是一个矩形被管对象的例子
Ellipse
椭圆
The Ellipse is a ellipsoidal container with the following properties:
椭圆是一种椭圆的具有以下属性的容器
|
Property |
Type |
Default |
Comments |
|
thickness |
number |
1 |
Thickness of the border 边框的厚度 |
Here is an example of an ellipse control: https://www.babylonjs-playground.com/#XCPP9Y#10 -
这里是一个椭圆被管对象的例子
StackPanel
堆栈面板
The StackPanel is a control which stacks its children based on its orientation (can be horizontal or vertical). All children must have a defined width or height (depending on the orientation).
堆栈面板是一种基于排列方向（水平或竖直）来堆积子元素的被管对象。所有的子元素都必须具有一个定义好的宽度或高度（基于排列方向）
The height (or width) of the StackPanel is defined automatically based on children.
堆栈面板的高度（或宽度）基于子元素自动定义
Here is an example of a StackPanel: https://www.babylonjs-playground.com/#XCPP9Y#11 -
这里是一个堆栈面板的例子
ColorPicker
拾色器
The color picker control allows users to set colors in your scene.
拾色器被管对象允许用户在你的场景内设置颜色。
Whenever a user interacts with the color picker an observable is triggered (colorPicker.onValueChangedObservable) which returns the current value (Color3) of the color picker.
当用户和拾色器交互时一个事件被触发(colorPicker.onValueChangedObservable)，它将返回拾色器当前的值（Color3）
The control is rendered using the following properties:
这个被管对象基于以下属性渲染：
|
Property |
Type |
Default |
Comments |
|
size |
string or number |
"200px" |
The size, width, and height property will always be the same value since the color picker can only be a square. 尺寸，宽度和高度属性必须是相同的值因为拾色器必须是一个方块 |
Here is an example of a color picker: https://www.babylonjs-playground.com/#91I2RE#1 -
这里是一个拾色器的例子：
Helpers（Header？）
帮助
To reduce the amount of code required to achieve frequent tasks you can use the following helpers:
为了降低频繁的任务所需的代码数量，你可以使用如下的帮助
-
BABYLON.GUI.Control.AddHeader(control, text, size, options { isHorizontal, controlFirst }): This function will create a StackPanel (horizontal or vertical based on options) and will add your control plus a TextBlock in it. Options can also be used to specify if the control is inserted first of after the header. Depending on the orientation, size will either specify the widht or the height used for the TextBlock.
BABYLON.GUI.Control.AddHeader(control, text, size, options { isHorizontal, controlFirst }):这个方法将建立一个堆栈面板（基于选项确定水平还是竖直），然后将把你的被管对象和一个文本框一起放在这个堆栈面板里面。同样可以通过选项设置这个被管对象插入到标题的前面还是后面。根据方向，文本框的宽度或者高度尺寸也将被自动设定。
Focus management
焦点管理
The current focused control can be found using advancedDynamicTexture.focusedControl. You can also manually move the focus to a focusable control by calling advancedDynamicTexture.moveFocusToControl(control).
可以使用advancedDynamicTexture.focusedControl找到当前保有焦点的被管对象。你也可以人工的将焦点移动到一个可以获得焦点的被管对象上，通过调用advancedDynamicTexture.moveFocusToControl(control)。