In CocosCreator, the difference between User-interface (UI) components and 2D rendering objects is that 2D rendering objects are generally only responsible for rendering 2D objects, while UI is more responsible for user interaction capabilities.
Commonly used UI controls can be created by adding nodes.
Click the + Create Node button in the upper left corner of the hierarchy manager , then select UI to create the required UI node. The corresponding UI component will be automatically mounted on the node:
Other UI components can be added by manually selecting the node in the Hierarchy Manager and then clicking Add Component -> UI in the Property Inspector :
Next, we will introduce the use and precautions of commonly used UI components one by one. Due to the large content of UI components and space reasons, we will continue to introduce them in the future.
This article mainly introduces the Canvas component, UITransform component, and Widget component.
To learn about commonly used 2D rendering objects, please view CocosCreator3.8 Research Notes (16) CocosCreator 2D Object .
1. Canvas component
(1), The role of Canvas component
The Canvas (canvas) component inherits from the RenderRoot2D component, so the Canvas component is the data collection entrance.
There can be multiple Canvas nodes in the scene, and all 2D rendering elements must be rendered as child nodes of RenderRoot2D .
In addition to inheriting the data entry capability from RenderRoot2D, the Canvas node itself also serves as an important component of screen adaptation and plays a key role in multi-resolution adaptation in game production.
The design resolution and adaptation scheme of Canvas are configured through the project settings .
(2) Properties of the Canvas component
| Attributes | Function Description |
|---|---|
| CameraComponent | The camera associated with the Canvas. This camera may not necessarily render the content under the Canvas. It can be used with the AlignCanvasWithScreen property to automatically change some parameters of the Camera to align it with the Canvas. |
| AlignCanvasWithScreen | Whether the camera associated with the Canvas should be aligned with the Canvas. If you want to control the camera position yourself, do not check this option. |
(3), matters needing attention
If you encounter UI rendering errors, blurry screens, splashing screens, etc., the first thing to check is the ClearFlag of all cameras (Camera and Canvas) in the scene to ensure that there must be a camera in the scene to perform the Solid_Color clear screen operation .
Specifically how to set ClearFlag , please refer to the following situations:
-
If there is only one UI Canvas or 3D Camera in the scene, then the ClearFlag property is set to
Solid_Color. -
If the scene contains a 2D background layer, 3D scene layer, and 2D UI layer, then:
For cameras used for 3D scene rendering, please ensure that the first rendering camera is SOLID_COLOR (if a skybox is configured, set it to SKYBOX ), and the remaining cameras are determined according to project requirements.
For cameras used for UI rendering (under Canvas), use DEPTH ONLY .
If a camera has a targetTexture set, please set it to SOLID_COLOR .
As shown in the figure: the ClearFlag property of the first rendered camera is set toSolid_Color
As shown in the figure: UI rendering (below the Canvas) camera, the ClearFlag property is set toDEPTH ONLY
2. UITransform component
(1), The role of UITransform component
Define the rectangle information on the UI, including the size and anchor point position of the rectangle.
The size and position of the rectangle can be arbitrarily manipulated through this component. It is generally used for rendering, calculation of click events, interface layout, screen adaptation, etc.
(2), UITransform component properties
| Attributes | Function Description |
|---|---|
| ContentSize | UI rectangle content size |
| AnchorPoint | UI rectangle anchor point position |
(3), add UITransform component
Click the Add Component button under the Property Inspector and select UI/UITransform to add the UITransform component to the node.
(4) Dynamically modify size and anchor points
const uiTransform = this.getComponent(UITransform);
// 方法一
uiTransform.setContentSize(100, 220);
uiTransform.setAnchorPoint(0.5, 0);
// 方法二
uiTransform.width = 100;
uiTransform.height = 220;
uiTransform.anchorX = 0.5;
uiTransform.anchorY = 0;
3. Widget component
(1), The role of Widget
Widget (alignment widget) is a very commonly used UI layout component.
It can automatically align the current node to any position of the parent object, or constrain the size, making it easy to adapt to different resolutions.
Click the Add Component button under the Property Inspector and select UI/Widget to add the Widget component to the node.
(2), Widget option
| Options | illustrate | Remark |
|---|---|---|
| Top | Align top border | When selected, an input box will be displayed next to it for setting the distance between the upper boundary of the current node and the upper boundary of the parent object. |
| Bottom | align bottom border | When selected, an input box will be displayed next to it for setting the distance between the lower boundary of the current node and the lower boundary of the parent object. |
| Left | Align left margin | When selected, an input box will be displayed next to it for setting the distance between the left edge of the current node and the left edge of the parent object. |
| Right | Align right margin | When selected, an input box will be displayed next to it for setting the distance between the right edge of the current node and the right edge of the parent object. |
| HorizontalCenter | Centered horizontally | |
| VerticalCenter | vertically centered | |
| Target | Align target | Specifies the node for alignment reference. When no target is specified here, the direct parent node will be used as the alignment target. |
| AlignMode | Specifies the alignment of the Widget, which is used to determine when the Widget should be updated at runtime | Usually set to ALWAYS , realignment occurs every time the node changes. When set to ONCE , alignment occurs only once when the component is initialized. When ON_WINDOW_RESIZE, it will be updated every time the window changes. |
(3) Use of Widget
Here we take the Spite node and add the Widget component as an example for demonstration.
Below: Align left, align top, left and top margins 100px.
Below: Align right, align bottom, right and bottom margins 100px.
The picture below is vertically centered and horizontally centered.
Below: Width stretch, height stretch, top and bottom margins 50px
(4) Restrictions on node location and size
If the Align Mode attribute is set to ALWAYS , each frame will be aligned according to the set alignment policy at runtime. The position (position) and size (width, height) attributes of the node where the component is located may be restricted and cannot be used through API or animation. The system can be modified freely.
If you need to meet the alignment strategy and the need to change the position and size at runtime, you can achieve it in the following two ways:
-
Make sure that the Align Mode property of the Widget component is set to ONCE . This property will only be responsible for alignment once when the component is initialized (onEnable), and will not be aligned again every frame. Alignment can be completed automatically during initialization, and then the UI can be moved and transformed through the API or animation system.
-
By calling the alignment margin API of the Widget component, including top , bottom , left , and right , you can directly modify the position of the node where the Widget is located or the stretch in a certain axis. These properties can also be added with corresponding keyframes in the animation editor to ensure alignment while realizing various rich UI animations.
(5). Code to modify alignment distance
const widget = this.getComponent(Widget);
// 设置默认对齐单位是 px
widget!.bottom = 50;
widget!.top = 50;
// 设置对齐单位是 %
widget!.isAbsoluteTop = false;
widget!.isAbsoluteBottom = false;
widget!.bottom = 0.1; // 10%
widget!.top = 0.1; // 10%