Button Component Reference

The Button component responds to a click from the user. When the user clicks a Button, its status will change. In addition, users can assign a custom behavior to buttons’ click event.

Click the Add Component button at the bottom of the Inspector panel and select UI/Button to add the Button component to the node.

To use Button, please refer to the Button API documentation and the Button scene of the test-cases-3d project.

Button Properties

Button Transition

Button Transition is used to choose the action of the button when clicked by the user. Currently the types available are NONE, COLOR, SPRITE and SCALE.

Color Transition

Sprite Transition

Scale Transition

Button Click Events

The Button can additionally add a click event to respond to the player’s click action. There are two ways to achieve this.

Add a callback using the Properties

Add a callback using the script

There are two ways to add a callback through the script.

1. The event callback added by this method is the same as the event callback added by the editor, all added by the script. First you need to construct a EventHandler object, and then set the corresponding target, component, handler and customEventData parameters.

    import { _decorator, Component, Event, Node, Button, EventHandler } from 'cc';
    const { ccclass, property } = _decorator;
    @ccclass("example")
    export class example extends Component {
        onLoad () {
            const clickEventHandler = new EventHandler();
            // This node is the node to which your event handler code component belongs
            clickEventHandler.target = this.node;
            // This is the script class name
            clickEventHandler.component = 'example';
            clickEventHandler.handler = 'callback';
            clickEventHandler.customEventData = 'foobar';
            const button = this.node.getComponent(Button);
            button.clickEvents.push(clickEventHandler);
        }
        callback (event: Event, customEventData: string) {
            // The event here is a Touch object, and you can get the send node of the event by event.target
            const node = event.target as Node;
            const button = node.getComponent(Button);
            console.log(customEventData); // foobar
        }
    }

2. By button.node.on ('click', ...) to add event callback. This is a very simple way, but the way has some limitations, in the event callback the screen coordinate point of the current click button cannot be obtained.

    // Suppose we add an event handler callback to the onLoad method of a component and handle the event in the callback function:
    import { _decorator, Component, Button } from 'cc';
    const { ccclass, property } = _decorator;
    @ccclass("example")
    export class example ex tends Component {
        @property(Button)
        button: Button | null = null;
        onLoad () {
            this.button.node.on(Button.EventType.CLICK, this.callback, this);
        }
        callback (button: Button) {
            // Note that events registered this way cannot pass customEventData
        }
    }