# 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]);