前面的文章已经介绍了Layout 组件 、ScrollView 组件 、PageView 组件 。
想了解的朋友,请查看 CocosCreator3.8研究笔记(十八)CocosCreator UI组件(二)。
今天我们主要介绍CocosCreator 常用组件:Button 组件 、EditBox 组件 、ProgressBar 组件、Toggle 组件。
一、Button 组件
Button 组件可以响应用户的点击操作,当用户点击 Button 时,Button 自身会有状态变化,在完成点击操作后响应一个自定义的行为。
(1)、Button 属性
属性 | 功能说明 |
---|---|
Target | Node 类型,当 Button 发生 Transition 的时候,会相应地修改 Target 节点的 SpriteFrame,颜色或者 Scale。 |
Interactable | 布尔类型,设为 false 时,则 Button 组件进入禁用状态。 |
Transition | 枚举类型,包括 NONE、COLOR、SPRITE 和 SCALE。每种类型对应不同的 Transition 设置。 |
Click Event | 列表类型,默认为空,用户添加的每一个事件由节点引用,组件名称和一个响应函数组成。 |
- Button Transition
Button Transition 用来指定当用户点击 Button 时的状态表现,目前主要有 NONE、COLOR、SPRITE 和 SCALE。
- COLOR Transition
- SPRITE Transition
- SCALE Transition
属性 | 功能 |
---|---|
Duration | Button 状态切换需要的时间间隔。 |
ZoomScale | 当用户点击按钮后,按钮会缩放到一个值,这个值等于 Button 原始 scale * zoomScale,zoomScale 可以为负数 |
(2)、Button 事件
属性 | 功能说明 |
---|---|
Target | 带有脚本组件的节点。 |
Component | 脚本组件名称。 |
Handler | 指定一个回调函数,当用户点击 Button 并释放时会触发此函数。 |
CustomEventData | 用户指定任意的字符串作为事件回调的最后一个参数传入。 |
代码添加回调的两种方式:
- 构造一个
EventHandler
对象,然后设置好对应的target
、component
、handler
和customEventData
参数。
import { _decorator, Component, Event, Node, Button, EventHandler } from 'cc';
const { ccclass, property } = _decorator;
@ccclass("test")
export class test extends Component {
onLoad () {
const clickEventHandler = new EventHandler();
clickEventHandler.target = this.node; // 这个 node 节点是你的事件处理代码组件所属的节点
clickEventHandler.component = 'test'; // 这个是脚本类名
clickEventHandler.handler = 'callback';
clickEventHandler.customEventData = 'data';
const button = this.node.getComponent(Button);
button.clickEvents.push(clickEventHandler);
}
callback (event: Event, customEventData: string) {
// 这里 event 是一个 Touch Event 对象,可以通过 event.target 取到事件的发送节点
const node = event.target as Node;
const button = node.getComponent(Button);
console.log(customEventData); // data
}
}
- 通过
button.node.on('click', ...)
的方式来添加
import { _decorator, Component, Button } from 'cc';
const { ccclass, property } = _decorator;
@ccclass("test")
export class test extends Component {
@property(Button)
button: Button | null = null;
onLoad () {
this.button.node.on(Button.EventType.CLICK, this.callback, this);
}
callback (button: Button) {
}
}
注意:
(A)、在事件回调里面无法获得当前点击按钮的屏幕坐标点 。
(B)、这种方式注册的事件,无法传递 customEventData。
二、 EditBox 组件
EditBox 是一种文本输入组件,可以获取用户输入的文本。
(1)、EditBox 属性
属性 | 功能说明 |
---|---|
BackgroundImage | 输入框背景节点上挂载的 Sprite 组件对象 |
FontColor | 输入框文本的颜色 |
FontSize | 输入框文本的字体大小 |
InputFlag | 指定输入标识:可以指定输入方式为密码或者单词首字母大写(仅支持 Android 平台) |
InputMode | 指定输入模式:ANY 表示多行输入,其它都是单行输入,移动平台上还可以指定键盘样式。 |
LineHeight | 输入框文本的行高 |
MaxLength | 输入框最大允许输入的字符个数 |
Placeholder | 输入框占位符的文本内容 |
PlaceholderFontColor | 输入框占位符的文本字体颜色 |
PlaceholderFontSize | 输入框占位符的文本字体大小 |
PlaceholderLabel | 输入框占位符节点上挂载的 Label 组件对象 |
ReturnType | 指定移动设备上面回车按钮的样式 |
String | 输入框的初始输入内容,如果为空则会显示占位符的文本 |
TabIndex | 修改 DOM 输入元素的 tabIndex,这个属性只有在 Web 上面修改有意义。 |
TextLabel | 输入框输入文本节点上挂载的 Label 组件对象 |
(2)、EditBox 事件
- Editing Did Began:在用户点击输入框获取焦点的时候被触发。
- Editing Did Ended:在单行模式下面,一般是在用户按下回车或者点击屏幕输入框以外的地方调用该函数。
如果是多行输入,一般是在用户点击屏幕输入框以外的地方调用该函数。 - Text Changed:在用户每一次输入文字变化的时候被触发。但若是通过
EditBox.string
的setter
设置时不会派发该事件。
(3)、注意事项
-
如果需要输入密码,则需要把 Input Flag 设置为 password,同时 Input Mode 必须是 Any 之外的选择,一般选择 Single Line。
-
如果要输入多行,可以把 Input Mode 设置为 Any。
-
背景图片支持九宫格缩放
(4)、代码添加回调
添加回调的有两种方式:
- 构造一个
EventHandler
对象,然后设置好对应的target
、component
、handler
和customEventData
参数。
import { _decorator, Component, EditBox, EventHandler } from 'cc';
const { ccclass, property } = _decorator;
@ccclass("test")
export class test extends Component {
onLoad() {
const editboxEventHandler = new EventHandler();
editboxEventHandler.target = this.node; // 这个 node 节点是你的事件处理代码组件所属的节点
editboxEventHandler.component = 'test';
editboxEventHandler.handler = 'onEditDidBegan';
editboxEventHandler.customEventData = 'data';
const editbox = this.node.getComponent(EditBox);
editbox.editingDidBegan.push(editboxEventHandler);
// 你也可以通过类似的方式来注册其它回调函数
// editbox.editingDidEnded.push(editboxEventHandler);
// editbox.textChanged.push(editboxEventHandler);
// editbox.editingReturn.push(editboxEventHandler);
}
onEditDidBegan(editbox, customEventData) {
// 这里 editbox 是一个 EditBox 对象
// 这里的 customEventData 参数就等于你之前设置的 "data"
}
// 假设这个回调是给 editingDidEnded 事件的
onEditDidEnded(editbox, customEventData) {
// 这里 editbox 是一个 EditBox 对象
// 这里的 customEventData 参数就等于你之前设置的 "data"
}
// 假设这个回调是给 textChanged 事件的
onTextChanged(text, editbox, customEventData) {
// 这里的 text 表示修改完后的 EditBox 的文本内容
// 这里 editbox 是一个 EditBox 对象
// 这里的 customEventData 参数就等于你之前设置的 "data"
}
// 假设这个回调是给 editingReturn 事件的
onEditingReturn(editbox, customEventData) {
// 这里 editbox 是一个 EditBox 对象
// 这里的 customEventData 参数就等于你之前设置的 "data"
}
}
-
通过
editbox.node.on('editing-did-began', ...)
的方式来添加,也可以注册editing-did-ended
、text-changed
和editing-return
事件,这些事件的回调函数的参数与editing-did-began
的参数一致。
注意:这种方式注册的事件,无法传递 customEventData
// 假设我们在一个组件的 onLoad 方法里面添加事件处理回调,在 callback 函数中进行事件处理:
import { _decorator, Component, EditBox } from 'cc';
const { ccclass, property } = _decorator;
@ccclass("test")
export class example test Component {
@property(EditBox)
editbox: EditBox | null = null;
onLoad(){
this.editbox.node.on('editing-did-began', this.callback, this);
}
callback(editbox: EditBox){
// 回调的参数是 editbox 组件
}
}
三、ProgressBar 组件
ProgressBar(进度条)经常被用于在游戏中显示某个操作的进度,比如:游戏更新下载进度。
ProgressBar 属性
属性 | 功能说明 |
---|---|
Bar Sprite | 进度条渲染所需要的 Sprite 组件,可以通过拖拽一个带有 Sprite 组件的节点到该属性上来建立关联。 |
Mode | 支持 HORIZONTAL(水平)、VERTICAL(垂直)和 FILLED(填充)三种模式,可以通过配合 reverse 属性来改变起始方向。 |
Total Length | 当进度条为 100% 时 Bar Sprite 的总长度/总宽度。在 FILLED 模式下 Total Length 表示取 Bar Sprite 总显示范围的百分比,取值范围从 0 ~ 1。 |
Progress | 浮点,取值范围是 0~1,不允许输入之外的数值。 |
Reverse | 布尔值,默认的填充方向是从左至右/从下到上,开启后变成从右到左/从上到下。 |
在节点上添加 ProgressBar 组件,然后给该组件关联一个 Bar Sprite 就可以在场景中控制 Bar Sprite 来显示进度了。
Bar Sprite 可以是自身节点,子节点,或者任何一个带有 Sprite 组件的节点。
Bar Sprite 可以自由选择 Simple、Sliced 和 Filled 渲染模式。
进度条的模式选择 FILLED 的情况下,Bar Sprite 的 Type 也需要设置为 FILLED,否则会报警告。
四、Toggle 组件
Toggle 是一个 CheckBox, Toggle 继承自 Button,当它和 ToggleContainer 一起使用的时候,可以变成 RadioButton。
Toggle 属性
属性 | 功能说明 |
---|---|
isChecked | 布尔类型,如果这个设置为 true,则 check mark 组件会处于 enabled 状态,否则处于 disabled 状态。 |
checkMark | Sprite 类型,Toggle 处于选中状态时显示的图片 |
Check Events | 列表类型,默认为空,用户添加的每一个事件由节点引用,组件名称和一个响应函数组成。详情见下方的 Toggle 事件 部分 |
Toggle 的事件回调有二个参数,第一个参数是 Toggle 本身,第二个参数是 customEventData。
添加事件回调的方法(一):
import { _decorator, Component, Event, Node, ToggleComponent, EventHandler } from 'cc';
const { ccclass, property } = _decorator;
@ccclass("test")
export class example extends Component {
onLoad(){
const checkEventHandler = new EventHandler();
checkEventHandler.target = this.node; //这个 node 节点是你的事件处理代码组件所属的节点
checkEventHandler.component = 'test'; //这个是脚本类名
checkEventHandler.handler = 'callback';
checkEventHandler.customEventData = 'data';
const toggle = this.node.getComponent(ToggleComponent);
toggle.checkEvents.push(checkEventHandler);
}
callback(event: Event, customEventData: string){
//这里 event 是一个 Touch Event 对象,你可以通过 event.target 取到事件的发送节点
// 这里的 customEventData 参数就等于之前设置的 'data'
}
}
方法(二): 通过 toggle.node.on('toggle', ...)
的方式来添加。
注意这种方式注册的事件,无法传递 customEventData
import { _decorator, Component, ToggleComponent } from 'cc';
const { ccclass, property } = _decorator;
@ccclass("test")
export class test extends Component {
@property(ToggleComponent)
toggle: ToggleComponent | null = null;
onLoad(){
this.toggle.node.on('toggle', this.callback, this);
}
callback(toggle: ToggleComponent){
// 回调的参数是 toggle 组件,
}
}
五、ToggleContainer 组件
ToggleContainer 不是一个可见的 UI 组件,它可以用来修改一组 Toggle 组件的行为。
当一组 Toggle 属于同一个 ToggleContainer 的时候,任何时候只能有一个 Toggle 处于选中状态。
1、ToggleContainer 属性
属性 | 功能说明 |
---|---|
AllowSwitchOff | 如果这个设置为 true,那么 toggle 按钮在被点击的时候可以反复地被选中和未选中。 |
CheckEvents | 选中事件。列表类型,默认为空,用户添加的每一个事件由节点引用,组件名称和一个响应函数组成。 |
2、ToggleContainer 事件回调
import { _decorator, Component, Event, Node, ToggleContainer, EventHandler } from 'cc';
const { ccclass, property } = _decorator;
@ccclass("test")
export class test extends Component {
onLoad(){
const containerEventHandler = new EventHandler();
containerEventHandler.target = this.node; // 这个 node 节点是你的事件处理代码组件所属的节点
containerEventHandler.component = 'test';// 这个是脚本类名
containerEventHandler.handler = 'callback';
containerEventHandler.customEventData = 'data';
const container = this.node.getComponent(ToggleContainer);
container.checkEvents.push(containerEventHandler);
}
callback(event: Event, customEventData: string) {
// 这里 event 是一个 Touch Event 对象,你可以通过 event.target 取到事件的发送节点
// 这里的 customEventData 参数就等于之前设置的 'data'
}
}
3、ToggleContainer的使用案例:
(1)、在属性检查器中,为Toggle 的父节点添加 ToggleContainer 组件
(2)、在层级管理器中添加多个同级的Toggle 组件
=
此时,所有包含 Toggle 组件的节点都会自动被添加到ToggleContainer 容器中。
(3)、运行效果
六、Slider 组件
Slider 是一个滑动器组件,通常用于调节 UI 的数值(例如音量调节),它主要的部件是一个滑块按钮,该部件用于用户交互,通过该部件可进行调节 Slider 的数值大小。
Slider 属性
属性 | 功能说明 |
---|---|
handle | 滑块按钮部件,可以通过该按钮进行滑动调节 Slider 数值大小 |
direction | 滑动器的方向,分为横向和竖向 |
progress | 当前进度值,该数值的区间是 0-1 之间 |
slideEvents | 滑动器组件事件回调函数 |
代码添加回调方法一:
构造一个EventHandler
对象,然后设置对应的 target
、component
、handler
和 customEventData
参数。
mport { _decorator, Component, Event, Node, Slider, EventHandler } from 'cc';
const { ccclass, property } = _decorator;
@ccclass("SliderCtrl")
export class SliderCtrl extends Component {
onLoad () {
const sliderEventHandler = new EventHandler();
// 这个 node 节点是事件处理脚本组件所属的节点
sliderEventHandler.target = this.node;
// 这个是脚本类名
sliderEventHandler.component = 'SliderCtrl';
sliderEventHandler.handler = 'callback';
sliderEventHandler.customEventData = 'data';
const slider = this.node.getComponent(Slider);
slider!.slideEvents.push(sliderEventHandler);
}
callback(slider: Slider, customEventData: string) {
//这里 event 是一个 Touch Event 对象,你可以通过 event.target 取到事件的发送节点
// 这里的 customEventData 参数就等于之前设置的 'data'
}
}
代码添加回调方法二:
通过 slider.node.on('slide', ...)
的方式来添加,这种方式注册的事件,无法传递 customEventData。
import { _decorator, Component, Slider } from 'cc';
const { ccclass, property } = _decorator;
@ccclass("SliderCtrl")
export class SliderCtrl extends Component {
@property(Slider)
slider: Slider | null = null;
onLoad () {
this.slider!.node.on('slide', this.callback, this);
}
callback(slider: Slider) {
}
}
七、WebView 组件
WebView 是一种显示网页的组件,该组件让你可以在游戏里面集成一个小的浏览器,目前只支持 Web、iOS 和 Android 平台。
WebView 属性
属性 | 功能说明 |
---|---|
Url | 指定一个 URL 地址,这个地址以 http 或者 https 开头,请填写一个有效的 URL 地址。 |
WebView Events | WebView 的回调事件,当 webview 在加载网页过程中,加载网页结束后或者加载网页出错时会调用此函数。 |
WebViewEvents 事件
属性 | 功能说明 |
---|---|
Target | 带有脚本组件的节点。 |
Component | 脚本组件名称。 |
Handler | 指定一个回调函数,当网页加载过程中、加载完成后或者加载出错时会被调用,该函数会传一个事件类型参数进来。 |
CustomEventData | 用户指定任意的字符串作为事件回调的最后一个参数传入。 |
WebView 事件回调参数
名称 | 功能说明 |
---|---|
LOADING | 表示网页正在加载过程中。 |
LOADED | 表示网页加载已经完毕。 |
ERROR | 表示网页加载出错了。 |
代码添加回调方法一:
构造一个 Component.EventHandler
对象,然后设置好对应的 target
、component
、handler
和 customEventData
参数。
import { _decorator, Component, WebView } from 'cc';
const { ccclass, type } = _decorator;
@ccclass('WebViewComponent')
export class WebViewComponent extends Component {
@type(WebView)
webview = null;
start () {
const eventHandler = new Component.EventHandler();
eventHandler.target = newTarget; // 这个对象是你的事件处理代码组件所属的节点
eventHandler.component = "WebViewComponent";
eventHandler.handler = "callback";
eventHandler.customEventData = "data";
this.webview.webviewEvents.push(eventHandler);
}
// 注意参数的顺序和类型是固定的
callback: function(webview, eventType, customEventData) {
// webview:是一个 webview 组件对象实例
// eventType:等于 WebView.EventType enum 里面的值
// customEventData:参数就等于你之前设置的 "data"
}
}
代码添加回调方法二:
通过 slider.node.on('slide', ...)
的方式来添加,这种方式注册的事件,无法传递 customEventData。
import { _decorator, Component, WebView } from 'cc';
const { ccclass, type } = _decorator;
@ccclass('WebViewCtrl')
export class WebViewComponent extends Component {
@type(WebView)
webview = null;
start () {
this.webview.node.on(WebView.EventType.LOADED, this.callback, this);
}
callback (webview) {
// 这里的 webview 是一个 WebView 组件对象
// 对 webview 进行你想要的操作
}
}
八、VideoPlayer 组件
VideoPlayer 是一种视频播放组件,可通过该组件播放本地和远程视频,支持的视频格式为 mp4。
点击 属性检查器 下面的 添加组件 按钮,然后从 UI 组件 中选择 VideoPlayer,即可添加 VideoPlayer 组件到节点上。
1、VideoPlayer 属性
属性 | 功能说明 |
---|---|
Resource Type | 视频来源的类型,目前支持本地(LOCAL)视频和远程(REMOTE)视频 URL |
Remote URL | 当 Resource Type 为 REMOTE 时显示的字段,填入远程视频的 URL |
Clip | 当 Resource Type 为 LOCAL 时显示的字段,拖拽本地视频的资源到此处来使用 |
Play On Awake | 视频加载后是否自动开始播放? |
Current Time | 指定从哪个时间点开始播放视频 |
Volume | 视频的音量(0.0 ~ 1.0) |
Mute | 是否静音视频。静音时设置音量为 0,取消静音时恢复原来的音量 |
Keep Aspect Ratio | 是否保持视频原来的宽高比 |
Full Screen On Awake | 是否全屏播放视频 |
Stay On Bottom | 永远在游戏视图最底层(该属性仅在 Web 平台生效) |
Video Player Event | 视频播放回调函数,该回调函数会在特定情况被触发,比如播放中,暂时,停止和完成播放。 |
2、VideoPlayerEvent 事件
属性 | 功能说明 |
---|---|
target | 带有脚本组件的节点。 |
component | 脚本组件名称。 |
handler | 指定一个回调函数,当视频开始播放后,暂停时或者结束时都会调用该函数,该函数会传一个事件类型参数进来。 |
customEventData | 用户指定任意的字符串作为事件回调的最后一个参数传入。 |
3、VideoPlayerEvent 事件回调参数
名称 | 功能说明 |
---|---|
PLAYING | 表示视频正在播放中。 |
PAUSED | 表示视频暂停播放。 |
STOPPED | 表示视频已经停止播放。 |
COMPLETED | 表示视频播放完成。 |
META_LOADED | 表示视频的元信息已加载完成,可以调用 getDuration 来获取视频总时长。 |
READY_TO_PLAY | 表示视频准备好了,可以开始播放了。 |
ERROR | 处理视频时触发的错误 |
CLICKED | 表示视频被用户点击了。(只支持 Web 平台) |
4、代码添加回调方法一:
构造一个 Component.EventHandler
对象,然后设置好对应的 target
、component
、handler
和 customEventData
参数。
import { _decorator, Component, VideoPlayer } from 'cc';
const { ccclass, type } = _decorator;
@ccclass('VideoPlayerComponent')
export class VideoPlayerComponent extends Component {
@type(VideoPlayer)
videoPlayer = null;
start () {
const eventHandler = new Component.EventHandler();
eventHandler.target = newTarget; // 这个对象是你的事件处理代码组件所属的节点
eventHandler.component = "VideoPlayerComponent";
eventHandler.handler = "callback";
eventHandler.customEventData = "data";
this.videoplayer.videoPlayerEvent.push(eventHandler);
}
// 注意参数的顺序和类型是固定的
callback: function(videoplayer, eventType, customEventData) {
// 这里的 videoplayer 是一个 VideoPlayer 组件对象实例
// 这里的 eventType === VideoPlayer.EventType enum 里面的值
// 这里的 customEventData 参数就等于你之前设置的 "data"
}
}
5、代码添加回调方法二:
通过 videoplayer.node.on(VideoPlayer.EventType.READY_TO_PLAY, ...)
的方式来添加,也可以注册 meta-loaded
、clicked
、playing
等事件,这些事件的回调函数的参数与 ready-to-play
的参数一致。
注意:这种方式注册的事件,也无法传递 customEventData.
/假设我们在一个组件的 onLoad 方法里面添加事件处理回调,在 callback 函数中进行事件处理:
import { _decorator, Component, VideoPlayer } from 'cc';
const { ccclass, type } = _decorator;
@ccclass('VideoPlayerComponent')
export class VideoPlayerComponent extends Component {
@type(VideoPlayer)
videoPlayer = null;
start () {
this.videoplayer.node.on(VideoPlayer.EventType.READY_TO_PLAY, this.callback, this);
}
callback (videoplayer) {
// 这里的 videoplayer 表示的是 VideoPlayer 组件
// 对 videoplayer 进行你想要的操作
}
}
6、实现 UI 在 VideoPlayer 上渲染
可通过以下两个步骤实现 UI 在 VideoPlayer 上显示:
(1)、 项目设置 -> 宏配置 中的 ENABLE_TRANSPARENT_CANVAS 设置为勾选状态( Canvas 背景支持 alpha 通道)
(2)、 属性检查器 中勾选 VideoPlayer 组件上的 stayOnBottom 属性。
注意:
-
该功能仅支持 Web 平台。
-
各个浏览器具体效果无法保证一致,跟浏览器是否支持与限制有关。
-
开启 stayOnBottom 后,将无法正常监听
VideoPlayerEvent
中的clicked
事件。
7、VideoPlayer播放视频演示
import { _decorator, Node, Component, find, VideoPlayer } from 'cc';
const { ccclass, type } = _decorator;
@ccclass('VideoPlayerComponent')
export class VideoPlayerComponent extends Component {
@type(VideoPlayer)
videoPlayer = null;
start () {
let canvas = find('Canvas');
canvas.on(Node.EventType.TOUCH_START, this.playVideo, this);
}
playVideo () {
this.videoplayer.play();
}
}
注意:一些移动端的浏览器或 WebView 不允许自动播放视频,需要在触摸事件中手动播放视频。