widget.newSwitch()

类型 函数
库 widget.*
返回值 SwitchWidget
修订版 版本 2024.3703
关键字 窗口小部件，开关，单选按钮，开/关，复选框，控件
另请参阅 SwitchWidget

概述

创建一个 SwitchWidget 对象。

陷阱

语法

widget.newSwitch( options )

此函数接收单个参数 options，这是一张接受以下参数的表

id (可选)

字符串. 可选，一个要分配给开关的标识。默认值为 "widget_switch"。

x, y (可选)

数字. 窗口小部件的 x 和 y 中心的坐标。如果定义了 left 和 top，则这些值将被它们覆盖。

left, top (可选)

数字. 窗口小部件创建时的左上角位置。如果指定了此参数，则这些值会覆盖 x 和 y 参数。

initialSwitchState (可选)

布尔值. 开关的初始状态 — 为开/选中时的 true，或关/取消选中时的 false。默认值为 false。

style (可选)

字符串. 开关样式。有效选项是 "radio"、"checkbox" 和 "onOff"。默认值为 "onOff"。

onPress (可选)

监听器。在按下开关时要调用的一个可选项。回调函数不要求测试 event.phase，因为它仅支持 "began"。如果要通过该监听器类型读取 object.isOn 属性，则将报告开关的当前状态，表示在实际开关状态更改发生之前的 .isOn 状态。

onRelease (可选)

监听器。当用户释放开关时调用的一个可选项（假设触摸仍然停留在开关上）。回调函数不要求测试 event.phase，因为它仅支持 "ended"。如果要通过该监听器类型读取 object.isOn 属性，则将报告变动后的开关状态，表示在开关状态更改发生之后的 .isOn 状态。

onEvent (可选)

监听器。应仅在未设置 onPress 和 onRelease 时指定的一个可选项。这个回调函数允许你测试 event.phase 的 "began"、"moved" 或 "ended"。

方法

object:setState()

属性

object.isOn

可视化定制

sheet (必需)

图片表。该图片表的 对象 用于开关。

单选按钮或复选框开关

收音机和复选框开关可用 图片表 中两个大小相等的帧在视觉上进行自定义。只需声明图片表，然后在 widget 构造器中将两个帧指定为 frameOn 和 frameOff。

frameOn (必需)

数字。收音机/复选框开关的 “打开” 帧的索引号。

frameOff (必需)

数字。收音机/复选框开关的 “关闭” 帧的索引号。

width, height (必需)

数字。每个帧的宽度/高度。

开/关开关

开/关开关可用 图片表 中的 4 个帧（左侧）以及一个 蒙版 图像（中间）在视觉上进行自定义，从而组成一个组合开关（右侧）。

+  → 

onOffBackgroundFrame 帧（左上）滑到小工具蒙版区域的后面。此帧通常是开关的 “打开” 端和 “关闭” 端的组合。手柄将放置在此帧的水平中心，因此根据你的设计，你可以为开关创建两个不同的端，由手柄分隔。

实际手柄既可以有 “默认” 帧，也可以有 “悬停” 帧 — 后者在视觉上与前者存在某些差异，以表明用户正在操作手柄。如果你不想指示任何视觉差异，你可以为 onOffHandleDefaultFrame 和 onOffHandleOverFrame 指定相同的帧号。

叠层边框（onOffOverlayFrame）位于手柄的后面，但位于蒙版背景滑块的前面。请记住，在设计 蒙版 图像时，蒙版的可见（白色）区域通常与叠层边框的内部开放区域大小相同。此外，蒙版必须遵循 此处 概述的所有蒙版的要求。

onOffBackgroundFrame (必需)

数字。用于滑动背景帧的帧索引。它将被为 onOffMask 定义的图像遮盖。

onOffBackgroundWidth, onOffBackgroundHeight (必需)

数字。背景帧的宽度/高度。

onOffMask (必需)

字符串。蒙版图像的文件名（包括扩展名和任何子文件夹路径），例如 "myWidgetAssets/switchMask.png"。此图像必须遵守 此处 概述的蒙版要求。

onOffHandleDefaultFrame (必需)

数字。用于手柄 “默认”（未按下）外观的帧索引。

onOffHandleOverFrame (必需)

数字。用于手柄 “悬停”（按下）外观的帧索引。

onOffOverlayFrame (必需)

数字。用于叠层边框的帧索引。

onOffOverlayWidth, onOffOverlayHeight (必需)

数字。叠加边框的宽度/高度。

offDirection (可选)

字符串。onOffBackgroundFrame 框架从视觉角度看被认为是“关”的一侧。默认值为 "right"，但是此值可以设置为 "left"。仅当您希望反转开关的“开”和“关”侧时，才更改此值。

分组单选按钮

通过将多个按钮放在同一显示组中，可以对单选按钮进行编组（关联）。同一组中的按钮将表现为基于 HTML 的单选按钮，其中一次只能选择一个按钮。当选择了该组中的另一个按钮时，其他按钮将自动关闭。请参阅以下使用示例。

示例

单选按钮
local widget = require( "widget" )

-- Handle press events for the buttons
local function onSwitchPress( event )
    local switch = event.target
    print( "Switch with ID '"..switch.id.."' is on: "..tostring(switch.isOn) )
end

-- Create a group for the radio button set
local radioGroup = display.newGroup()

-- Create two associated radio buttons (inserted into the same display group)
local radioButton1 = widget.newSwitch(
    {
        left = 150,
        top = 200,
        style = "radio",
        id = "RadioButton1",
        initialSwitchState = true,
        onPress = onSwitchPress
    }
)
radioGroup:insert( radioButton1 )

local radioButton2 = widget.newSwitch(
    {
        left = 250,
        top = 200,
        style = "radio",
        id = "RadioButton2",
        onPress = onSwitchPress
    }
)
radioGroup:insert( radioButton2 )
复选框
local widget = require( "widget" )

-- Handle press events for the checkbox
local function onSwitchPress( event )
    local switch = event.target
    print( "Switch with ID '"..switch.id.."' is on: "..tostring(switch.isOn) )
end

-- Create the widget
local checkboxButton = widget.newSwitch(
    {
        left = 250,
        top = 200,
        style = "checkbox",
        id = "Checkbox",
        onPress = onSwitchPress
    }
)
开/关开关
local widget = require( "widget" )

-- Handle press events for the checkbox
local function onSwitchPress( event )
    local switch = event.target
    print( "Switch with ID '"..switch.id.."' is on: "..tostring(switch.isOn) )
end

-- Create the widget
local onOffSwitch = widget.newSwitch(
    {
        left = 250,
        top = 200,
        style = "onOff",
        id = "onOffSwitch",
        onPress = onSwitchPress
    }
)
图像图纸 — 单选按钮
local widget = require( "widget" )

-- Handle press events for the buttons
local function onSwitchPress( event )
    local switch = event.target
    print( "Switch with ID '"..switch.id.."' is on: "..tostring(switch.isOn) )
end

-- Image sheet options and declaration
local options = {
    width = 100,
    height = 100,
    numFrames = 2,
    sheetContentWidth = 200,
    sheetContentHeight = 100
}
local radioButtonSheet = graphics.newImageSheet( "radioButtonSheet.png", options )

-- Create a group for the radio button set
local radioGroup = display.newGroup()

-- Create two associated radio buttons (inserted into the same display group)
local radioButton1 = widget.newSwitch(
    {
        left = 150,
        top = 200,
        style = "radio",
        id = "RadioButton1",
        width = 100,
        height = 100,
        initialSwitchState = true,
        onPress = onSwitchPress,
        sheet = radioButtonSheet,
        frameOff = 1,
        frameOn = 2
    }
)
radioGroup:insert( radioButton1 )

local radioButton2 = widget.newSwitch(
    {
        left = 250,
        top = 200,
        style = "radio",
        id = "RadioButton2",
        width = 100,
        height = 100,
        onPress = onSwitchPress,
        sheet = radioButtonSheet,
        frameOff = 1,
        frameOn = 2
    }
)
radioGroup:insert( radioButton2 )
图像图纸 — 复选框
local widget = require( "widget" )

-- Handle press events for the checkbox
local function onSwitchPress( event )
    local switch = event.target
    print( "Switch with ID '"..switch.id.."' is on: "..tostring(switch.isOn) )
end

-- Image sheet options and declaration
local options = {
    width = 100,
    height = 100,
    numFrames = 2,
    sheetContentWidth = 200,
    sheetContentHeight = 100
}
local checkboxSheet = graphics.newImageSheet( "checkboxSheet.png", options )

-- Create the widget
local checkbox = widget.newSwitch(
    {
        left = 250,
        top = 200,
        style = "checkbox",
        id = "Checkbox",
        width = 100,
        height = 100,
        onPress = onSwitchPress,
        sheet = checkboxSheet,
        frameOff = 1,
        frameOn = 2
    }
)
图像图纸 — 开/关开关
local widget = require( "widget" )

-- Handle press events for the checkbox
local function onSwitchPress( event )
    local switch = event.target
    print( "Switch with ID '"..switch.id.."' is on: "..tostring(switch.isOn) )
end

-- Image sheet options and declaration
-- For testing, you may copy/save the image under "Visual Customization: On/Off Switch" above
local options = {
    frames = {
        { x=0, y=0, width=160, height=44 },
        { x=0, y=45, width=42, height=42 },
        { x=44, y=45, width=42, height=42 },
        { x=88, y=44, width=96, height=44 }
    },
    sheetContentWidth = 184,
    sheetContentHeight = 88
}
local onOffSwitchSheet = graphics.newImageSheet( "widget-on-off-sheet.png", options )

-- Create the widget
local onOffSwitch = widget.newSwitch(
    {
        left = 250,
        top = 200,
        style = "onOff",
        id = "OnOffSwitch",
        onPress = onSwitchPress,

        sheet = onOffSwitchSheet,
    
        onOffBackgroundFrame = 1,
        onOffBackgroundWidth = 160,
        onOffBackgroundHeight = 44,
        onOffMask = "widget-on-off-mask.png",

        onOffHandleDefaultFrame = 2,
        onOffHandleOverFrame = 3,

        onOffOverlayFrame = 4,
        onOffOverlayWidth = 96,
        onOffOverlayHeight = 44
    }
)