UIToggle、UIToggleGroup 组件

概述

UIToggle 是一个单选按钮,用于进行简单的状态切换,需配合TouchInputComponent使用。

UIToggleGroup 是一个UIToggle管理器,用于在组内任意子UIToggle发生状态变化时,调整其他UIToggle状态。

组件概要

UIToggle -> Touchable -> Component -> Object

UIToggleGroup -> Component -> Object

注意

  1. UIToggle若无指定Target,会默认取Toggle所在节点的第一个存在渲染组件的子节点,作为状态切换的目标,默认状态为显示。
  2. onTouchEnter时会将当前组件的isChecked设为true。
  3. UIToggle状态变化,会触发当前节点所有组件的onStateChange(isChecked: Booleen, state: ToggleState)

UIToggle 静态属性描述

属性 功能
ToggleState UIToggle的状态枚举值
enum ToggleState {
  UnChecked,
  Checked,
}

UIToggle 属性描述

属性名 类型 默认值 说明
allowSwitchOff boolean true 是否允许取消激活态。
isChecked boolean false 是否处于激活态。
target Renderable2D undefined UIToggle激活态影响的渲染组件
toggleGroup UIToggleGroup undefined UIToggle关联的UIToggleGroup
index number -1 位于ToggleGroup的index,若无对应ToggleGroup则为-1

UIToggle 方法描述

方法 参数 返回值 功能
getState <ToggleState> 返回当前UIToggle状态
setState <ToggleState> Void 设置UIToggle状态,会影响isChecked

UIToggleGroup 属性描述

属性名 类型 默认值 说明
allowSwitchOff boolean false UIToggleGroup下属的UIToggle是否允许取消激活态。
toggleList Array<UIToggle> [] 只读属性,UIToggleGroup控制的UIToggle数组。
deafaultActiveToggle UIToggle undefined UIToggleGroup中默认处于激活态的UIToggle。

UIToggleGroup 方法描述

方法 参数 返回值 功能
getActiveToggle <UIToggle / null> 返回当前ToggleGroup激活状态的Toggle
setIndex <index: number> <boolean> 根据index,激活ToggleGroup里面Toggle,返回是否成功激活
checkedChange <toggle: UIToggle> Void 取消激活ToggleGroup中除toggle外的其他Toggle
addToggle <toggle: UIToggle> Void 往当前UIToggleGroup添加UIToggle
removeToggle <toggle: UIToggle> Void 往当前UIToggleGroup删除UIToggle

使用流程

UIToggle.gif

/* UIToggle1 */
// 默认允许取消激活态的UIToggle组件
const uiToggle1Entity = game.createEntity2D('UIToggle1');
uiToggle1Entity.transform2D.position.x = -300;
uiToggle1Entity.transform2D.size.x = 200;
uiToggle1Entity.transform2D.size.y = 200;
const uiToggle1 = uiToggle1Entity.addComponent(engine.UIToggle);
// UIToggle组件需搭配触摸组件使用
const uiToggle1Touch = uiToggle1Entity.addComponent(engine.TouchInputComponent);
// 默认情况下,触摸组件仅处理带渲染组件的节点
const uiToggle1Graphic = uiToggle1Entity.addComponent(engine.UIGraphic);
uiRoot.addChild(uiToggle1Entity.transform2D);

// UIToggle1的子渲染节点
const UIToggle1ChildGraphicEntity = game.createEntity2D('UIToggle1ChildGraphic');
UIToggle1ChildGraphicEntity.transform2D.size.x = 100;
UIToggle1ChildGraphicEntity.transform2D.size.y = 100;
const UIToggle1ChildGraphic = UIToggle1ChildGraphicEntity.addComponent(engine.UIGraphic);
UIToggle1ChildGraphic.color = new engine.Color(180, 40, 100);
uiToggle1Entity.transform2D.addChild(UIToggle1ChildGraphicEntity.transform2D);

/* UIToggleGroup */
// 多UIToggle的管理组件UIToggleGroup
const uiToggleGroupEntity = game.createEntity2D('UIToggleGroup');
uiToggleGroupEntity.transform2D.position.x = 300;
uiToggleGroupEntity.transform2D.size.x = 500;
uiToggleGroupEntity.transform2D.size.y = 520;
const UIToggleGroupGraphic = uiToggleGroupEntity.addComponent(engine.UIGraphic);
const uiToggleGroup = uiToggleGroupEntity.addComponent(engine.UIToggleGroup);
uiRoot.addChild(uiToggleGroupEntity.transform2D);

/* DefaultToggle */
// 默认情况下,UIToggleGroup仅会管理一级子节点,所以这里添加带有UIToggle的一级子节点DefaultToggle
const DefaultToggleEntity = game.createEntity2D('DefalutToggle');
DefaultToggleEntity.transform2D.position.y = 200;
DefaultToggleEntity.transform2D.size.x = 320;
DefaultToggleEntity.transform2D.size.y = 50;
const DefaultToggle = DefaultToggleEntity.addComponent(engine.UIToggle);
const DefaultToggleTouch = DefaultToggleEntity.addComponent(engine.TouchInputComponent);
const DefaultToggleGraphic = DefaultToggleEntity.addComponent(engine.UIGraphic);
DefaultToggleGraphic.color = new engine.Color(20, 123, 34);
uiToggleGroupEntity.transform2D.addChild(DefaultToggleEntity.transform2D);
// DefaultToggle 对应的渲染组件
const DefaultToggleGraphicEntity = game.createEntity2D('DefalutToggleGraphic');
DefaultToggleGraphicEntity.transform2D.size.x = 320;
DefaultToggleGraphicEntity.transform2D.size.y = 50;
const tmpGraphic = DefaultToggleGraphicEntity.addComponent(engine.UIGraphic);
tmpGraphic.color = new engine.Color(0, 0, 0, 220);
DefaultToggleEntity.transform2D.addChild(DefaultToggleGraphicEntity.transform2D);

/* ToggleChildrenGrid */
// 使用UIGrid管理子UIToggle位置,但默认情况下不会加载到UIToggleGroup,需要手动添加。
const gridEntity = game.createEntity2D('ToggleChildrenGrid');
const grid = gridEntity.addComponent(engine.UIGrid);
grid.autoSize = true;
grid.columns = 3;
grid.paddingX = 5;
grid.paddingY = 5;
const gridLength = 10;
for (let i = 1; i < gridLength; i++) {
    const gridItem = game.createEntity2D('Toggle3.' + i);
    gridItem.transform2D.size.x = 100;
    gridItem.transform2D.size.y = 100;
    const uiToggle = gridItem.addComponent(engine.UIToggle);
    uiToggleGroup.addToggle(uiToggle);
    if (i === 1) {
        // 将第一个UIToggle设置为默认激活态。
        uiToggleGroup.deafaultActiveToggle = uiToggle;
    }
    const uiToggleTouch = gridItem.addComponent(engine.TouchInputComponent);
    const uiToggleGraphic = gridItem.addComponent(engine.UIGraphic);
    uiToggleGraphic.color = new engine.Color(i * 123 % 255, i * 88 % 255, i * 168 % 255);
    gridEntity.transform2D.addChild(gridItem.transform2D);

    const gridItemGraphicEntity = game.createEntity2D('Toggle3.' + i + '');
    gridItemGraphicEntity.transform2D.size.x = 100;
    gridItemGraphicEntity.transform2D.size.y = 100;
    const gridItemGraphic = gridItemGraphicEntity.addComponent(engine.UIGraphic);
    gridItemGraphic.color = new engine.Color(0, 0, 0, 220);
    gridItem.transform2D.addChild(gridItemGraphicEntity.transform2D);
}
uiToggleGroupEntity.transform2D.addChild(gridEntity.transform2D);

// 将最后一个UIToggle从UIToggleGroup中移除
uiToggleGroup.removeToggle(uiToggleGroup.toggleList[uiToggleGroup.toggleList.length - 1]);