CocosCreator3.8研究笔记（十九）CocosCreator UI组件（三）

前面的文章已经介绍了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 不允许自动播放视频，需要在触摸事件中手动播放视频。