widget.newSlider()

类型 函数
库 widget.*
返回值 SliderWidget
修订版 Release 2024.3703
关键字 widget、slider、sliding control
另请参阅 SliderWidget

概述

创建 SliderWidget 对象。

疑难解答

语法

widget.newSlider( options )

此函数采用一个参数 options，它是一个接受以下参数的表

id (可选)

字符串. 为滑块指定的可选标识。默认值为 "widget_slider"。

x, y (可选)

数字. 滑块 x 和 y 中心点的坐标。如果定义了 left 和 top，这些值将被它们覆盖。

left, top (可选)

数字. 创建滑块的 left 和 top 位置。如果指定，这些值将覆盖 x 和 y 参数。

orientation (可选)

字符串. 滑块的方向，可以是 "horizontal" 或 "vertical"。默认值为 "horizontal"。

width, height (必需)

数字. 滑块的宽度 或 高度，具体取决于 orientation 设置（水平方向的 width 或垂直方向的 height）。

value (可选)

数字. 以百分比表示滑块的起始值。默认值为 50，表示滑块手柄将从 50% 开始。

listener (可选)

侦听器. 用于处理滑块交互事件的函数。在此侦听器函数中，event.phase 返回预期的触控交互阶段，即 "began"、"moved" 或 "ended"。此外，您可以用 event.value 读取滑块的新值。

属性

object.value

方法

object:setValue()

视觉定制

使用 image sheet 可以对滑块小工具进行视觉定制。如下例所示，可以利用 5 个框架组装外部边框和内部填充条。外部边框由左端盖（红色）、中间跨度（绿色）和右端盖（黄色）组成。内部填充区域（橙色）将延伸来跨度当前滑块填充百分比。所有的外部边框框架和内部填充框架都应具有相同的宽度和高度。

控制柄框架的大小可以和其他框架不同。请注意，所有滑块控件都有一个限制，限制控制柄在任一方向上的拖动范围。关于视觉自定义，当控制柄的中心轴到达中间跨部分的任一边缘时，控制柄将停止。因此，对于水平滑块，当控制柄中心轴到达跨中末端盖之间的部分的左边缘或右边缘时，控制柄将停止。对于垂直滑块，同样的原理适用于此，但是限制将是跨中部分的顶部边缘和底部边缘。

 → 
sheet (必需)

ImageSheet. 滑块的图像图集对象。

水平滑块

leftFrame (必需)

Number. 边框左端盖的框架索引。

middleFrame (必需)

Number. 边框中间跨度的框架索引。

rightFrame (必需)

Number. 边框右端盖的框架索引。

fillFrame (必需)

Number. 中间填充跨度的框架索引。

frameWidth, frameHeight (必需)

Numbers. 边框框架和中间填充跨度的宽度/高度。所有这些框架应该共享相同的宽度和高度。

handleFrame (必需)

Number. 控制柄元素的框架索引。

handleWidth, handleHeight (必需)

Numbers. 控制柄元素框架的宽度/高度。

垂直滑块

topFrame (必需)

Number. 边框顶部端盖的框架索引。

middleVerticalFrame (必需)

Number. 边框中间跨度的框架索引。

bottomFrame (必需)

Number. 边框底部端盖的框架索引。

fillVerticalFrame (必需)

Number. 中间填充跨度的框架索引。

frameWidth, frameHeight (必需)

Numbers. 边框框架和中间填充跨度的宽度/高度。所有这些框架应该共享相同的宽度和高度。

handleFrame (必需)

Number. 控制柄元素的框架索引。

handleWidth, handleHeight (必需)

Numbers. 控制柄元素框架的宽度/高度。

示例

水平
local widget = require( "widget" )
    
-- Slider listener
local function sliderListener( event )
    print( "Slider at " .. event.value .. "%" )
end

-- Create the widget
local slider = widget.newSlider(
    {
        x = display.contentCenterX,
        y = display.contentCenterY,
        width = 400,
        value = 10,  -- Start slider at 10% (optional)
        listener = sliderListener
    }
)
垂直
local widget = require( "widget" )
    
-- Slider listener
local function sliderListener( event )
    print( "Slider at " .. event.value .. "%" )
end

-- Create the widget
local slider = widget.newSlider(
    {
        x = display.contentCenterX,
        y = display.contentCenterY,
        orientation = "vertical",
        height = 200,
        value = 10,  -- Start slider at 10% (optional)
        listener = sliderListener
    }
)
图层
local widget = require( "widget" )

-- Slider listener
local function sliderListener( event )
    print( "Slider at " .. event.value .. "%" )
end

-- Image sheet options and declaration
-- For testing, you may copy/save the image under "Visual Customization" above
local options = {
    frames = {
        { x=0, y=0, width=36, height=64 },
        { x=40, y=0, width=36, height=64 },
        { x=80, y=0, width=36, height=64 },
        { x=124, y=0, width=36, height=64 },
        { x=168, y=0, width=64, height=64 }
    },
    sheetContentWidth = 232,
    sheetContentHeight = 64
}
local sliderSheet = graphics.newImageSheet( "widget-slider.png", options )

-- Create the widget
local slider = widget.newSlider(
    {
        sheet = sliderSheet,
        leftFrame = 1,
        middleFrame = 2,
        rightFrame = 3,
        fillFrame = 4,
        frameWidth = 36,
        frameHeight = 64,
        handleFrame = 5,
        handleWidth = 64,
        handleHeight = 64,
        x = display.contentCenterX,
        y = display.contentCenterY,
        orientation = "horizontal",
        width = 300,
        listener = sliderListener
    }
)