SeekBar组件是一个交互式进度控件,提供媒体导航功能。通过提供电视媒体播放器中常用的高级播放控制功能,它的运用不仅限于基本进度条。
使用场景
SeekBar组件非常适合需要媒体导航的应用,例如:
- 视频/音频播放器
- 时间轴拖动
- 内容预览系统
- 进度跟踪接口
- 交互式媒体导航
用户体验
核心属性
currentValue
必需 内容进度的当前位置值。
Type number
必须介于0和totalValue(含)之间。
totalValue
必需 搜索栏的最大值,表示总持续时间或范围。
Type number
step
使用方向键导航时要递增或递减的值。值可以是正数或负数。number默认 10
交互控制属性
disabled
启用或禁用具有遥控器事件的所有用户交互。boolean默认
false
disabledWhenNotFocused
如果为true,则在未聚焦搜索栏时禁用用户交互。此属性对于焦点管理至关重要的电视界面非常重要,如果您希望组件自动处理焦点管理而不是在应用代码中手动处理它,则此属性是理想的选择。
boolean默认
false
disableThumbnail
启用或禁用预览缩略图功能。如需显示缩略图,请使用thumbnailImageSource属性。
boolean默认
false
trapFocus
控制SeekBar组件的焦点导航行为。
boolean默认
false
启用后,会将向左或向右方向键导航的焦点限制在SeekBar中。向上或向下导航到SeekBar上方或下方的控件仍然可用。
partialDisablingConfiguration
用于控制要禁用哪些特定的用户交互。PartialDisablingConfiguration(参见Types部分)
提供后,此属性会覆盖全局的disabled和disabledWhenNotFocused设置。
该属性仅用于禁用特定按钮。例如,您可以禁用skipForward >>或skipBackward <<,同时保留播放定位行为(right和left方向键),或移除默认行为以便自行处理。
可用操作:
playPauseskipBackwardskipForwardleftrightselectback
PartialDisablingConfiguration对象时,所有操作的默认值都会设为false。
注意 禁用back按钮仅会影响SeekBar的内部使用,不会影响外部导航或组件外部的其他交互。
回调属性
onValueChange
当滑动时如滑块拇指值发生变化则触发回调。(value: number) => void
onSlidingStart
滑动交互开始时触发回调。对于方向键,回调会在初始按下向左或向右(按下按键)时触发。() => void
onSlidingEnd
滑动交互结束时触发回调。对于方向键导航,在松开向左或向右方向键时(按键弹起)触发。() => void | undefined
onRewindPress
当用户触发快退操作时触发回调。默认情况下,按下此按钮会模拟向后搜索内容的长按交互。 对于遥控器中的快退按钮<<,在松开按键时(按键弹起)触发。
() => void
相关属性:longPressIntervalDuration、stepMultiplierFactor、enableSkipForwardBackwardAcceleration。
onFastForwardPress
当用户触发快进操作时触发回调。默认情况下,按下此按钮会模拟向前搜索内容的长按交互。 对于遥控器>>中的快进按钮,在松开按键时(按键弹起)触发。
() => void
相关属性:longPressIntervalDuration、stepMultiplierFactor、enableSkipForwardBackwardAcceleration。
onPress
当用户按下遥控器上的选择按钮时触发回调。(seekBarThumbValue: number) => void
onPlayPause
当用户按下遥控器上的播放或暂停按钮时触发回调。(seekBarThumbValue: number) => void
onFocus
当搜索栏获得焦点时触发回调。() => void
onBlur
当搜索栏失去焦点时触发回调。() => void
onSeekInteractionChange
在使用方向键进行搜索交互期间触发回调。 该事件对象包含指示搜索方向的方向属性:'forward': 向右方向键导航搜索(初始按下)'rewind': 向左方向键导航搜索(初始按下)'fast_forward': 长按向右方向键导航'fast_rewind': 长按向左方向键导航null: 在搜索交互结束时发送(当用户在搜索后松开方向键时)
(event: InteractionEventPayload) => void
事件序列
在方向键交互过程中,onSeekInteractionChange回调会按特定顺序触发。
向右方向键示例
- 初次按下(按键按下):
event.direction = 'forward' - 如果按住时间足够长(经过
longPressDelay之后):event.direction = 'fast_forward' - 释放时(按键抬起):
event.direction = null
- 初次按下(按键按下):
event.direction = 'rewind' - 如果按住时间足够长(经过
longPressDelay之后):event.direction = 'fast_rewind' - 释放时(按键抬起):
event.direction = null
完整事件流程
长按交互的完整顺序是:视觉自定义属性
markers
在搜索栏上显示的标记数组。支持三种类型的标记:ReactNodeMarker[] | BreakMarker[]
标记类型
- ReactNode标记: 用于复杂视觉元素的自定义React组件
- 点标记: 将搜索栏分隔成段的彩色点,通常用于广告标记
- 分段标记: 将条形分隔为不同段的分隔标记
- ReactNode标记不能与点或分段标记组合
- 点和分段标记可以一起使用
- 点标记之间应至少有3%的间距
- 点标记最多只能在搜索栏总宽度的97%内放置
示例2
分段标记
displayAboveThumb
要在搜索栏滑块拇指上方呈现的自定义内容。您可以使用渲染函数或React Node。渲染函数接收的属性:{ mode, stepValue, multiplier, focused }。
DisplayAboveThumbType | React.ReactNode(参见Types部分)
displayBelowThumb
要在搜索栏滑块拇指下方呈现的自定义内容。您可以使用渲染函数或React Node。(() => React.ReactNode) | React.ReactNode
thumbIcon
自定义的滑块拇指图标组件。您可以使用渲染函数或React Node。渲染函数接收{ focused }属性。
((props: ThumbIconProps) => React.ReactNode) | React.ReactNode
注意:将动态图标与focused回调参数一起使用时,请设置disabledWhenNotFocused={true}以获得正确的焦点行为。
currentValueIndicatorColor
进度指示器已填充部分的颜色。您可以使用静态颜色或根据焦点状态返回颜色的函数。
Type ColorValue | ((isFocused: boolean) => ColorValue)
barTrackColor
滑块未填充部分的颜色。
Type ColorValue
segmentColors
分段的颜色配置。SegmentColorsConfig
segmentColors seekColor。如果没有分隔标记,则分段颜色将不适用于搜索栏。
用法示例
黄色分段颜色
红色分段颜色
样式属性
barStyle
滑块的样式覆盖项。
Type StyleProp<ViewStyle>
currentValueIndicatorStyle
进度指示器的样式覆盖项。StyleProp<ViewStyle>
timeShiftIndicatorStyle
timeshift指示器的样式覆盖项。
Type StyleProp<ViewStyle>
缩略图属性
thumbnailStyle
缩略图容器的样式覆盖项。StyleProp<ViewStyle>
thumbnailImageSource
缩略图预览的图像来源。接受动态来源的渲染属性。((thumbValue: number) => ImageSourcePropType) | ImageSourcePropType
thumbnailImageStyle
缩略图的样式覆盖项。StyleProp<ImageStyle>
thumbnailImageResizeMode
缩略图的大小调整模式。ImageResizeMode默认
"cover"
thumbnailLabel
要在缩略图中显示的标签。接受动态内容的渲染属性。((thumbValue: number) => string) | string
thumbnailLabelTextStyle
缩略图标签文本的样式覆盖项。StyleProp<TextStyle>
thumbnailLabelContainerStyle
缩略图标签容器的样式覆盖项。StyleProp<ViewStyle>
交互计时属性
longPressIntervalDuration
方向键长按操作的间隔持续时间(以毫秒为单位)。控制按住方向键时搜索操作更新的频率。建议保留默认值,因为它与遥控器发送的事件频率相匹配。number默认
200
示例1
长按间隔持续时间:200
示例2
长按间隔持续时间:400
longPressDelay
用户触发长按操作需经过的时间(以毫秒为单位)。对于方向键输入,用户按住左键或右键可触发长按。number默认
250
示例1
长按延迟:200
示例2
长按延迟:3000
keyDownThrottleDelay
限制按键按下事件的延迟。有助于防止在快速按键时进行过度的事件处理。number默认
0
animationDuration
当enableAnimations为true时,动画时长的毫秒值。控制滑块拇指和进度过渡所需的时间。为在长按以及快进或快退交互中获得更好的动画感知效果,建议在longPressIntervalDuration和animationDuration中使用相同的值。如果enableAnimations为false,则不起作用。
number默认
200
搜索行为属性
maxStepValue
长按期间渐进搜索的最大步长值。限制加速期间搜索步长的变大程度。number默认
160
stepMultiplierFactor
渐进式搜索步长的乘法系数,决定加速期间搜索速度的增加速度。step值将乘以该系数。仅在启用了enableLongPressAcceleration或enableSkipForwardBackwardAcceleration时才应用。
number默认
1
示例
stepMultiplierFactor={1}: 恒定加速 -1x → 2x → 3x → 4x, ..stepMultiplierFactor={2}: 快速加速 - 速度随时间加倍1x → 2x → 4x → 8x, ..stepMultiplierFactor={3}: 快速加速 - 速度随时间增至三倍1x → 3x → 6x → 12x, ..
stepMultiplierFactorInterval
步长乘数之间的时间间隔增加。控制方向键向左或向右长按加速期间搜索速度的增大频率(以毫秒为单位)。stepMultiplierFactor处理速度的提高。
number默认
1000
lowerSeekLimit
搜索栏范围内的最小可搜索值。防止搜索到该值之前的位置。number默认
0
upperSeekLimit
搜索栏范围内的最大可搜索值。防止搜索到该值之后的位置。number默认
totalValue
enableLongPressAcceleration
启用长按交互期间的渐进加速。启用后,步进倍数会随时间增大(例如1x、2x、3x、4x),具体取决于stepMultiplierFactor和stepMultiplierFactorInterval设置。step值乘以当前乘数。这会影响按住左或右按键或按钮时的搜索速度。
boolean默认
false
enableSkipForwardBackwardAcceleration
在向前或向后跳过交互时启用渐进加速。启用后,连续向前跳转 (>>) 或向后跳转 (<<) 按钮会根据stepMultiplierFactor设置增加步长乘数(例如,1x、2x、3x、4x、5x)。step值乘以当前乘数。
boolean默认
false
enableAnimations
启用或禁用搜索栏滑块拇指和进度动作的动画。 当为true时,进度条会平滑地以动画方式改变位置,且不应用timeShiftIndicatorStyle属性。如果为false,则位置会立即发生变化,所有视觉元素都将被渲染。
boolean默认
false
类型定义
PartialDisablingConfiguration
InteractionEventPayload
DisplayAboveThumbProps
SegmentColorsConfig
ThumbIconProps
SeekMode
术语表
以下列表包含本文档中使用的重要术语。 滑块拇指 -SeekBar上的一个交互式元素,让用户可以设置当前值 (currentValue)。默认情况下,thumb会放置在SeekBar的currentValue上。如果用户与之互动,则滑块拇指的位置会相应改变。
时移 - 用滑块拇指向前或向后推移的操作。
时移指示器 - 该指示器表示用户移动滑块拇指时currentValue和当前滑块拇指位置之间的间隔。
当前值指示器 - 这是SeekBar中表示当前值的填充部分(进度指示器)。
搜寻缩略图 - 基于图像的缩略图组件,通常显示在SeekBar滑块拇指上方,该组件显示图像预览和缩略图标签等内容。
标记 - 在整个SeekBar中水平布置的自定义React节点或视图。有三种类型: ReactNode标记(自定义组件)、点标记(彩色点)和分段标记(分隔标记)。
点标记 - 将搜索栏分成多个分段的彩色标记,通常用于广告标记。不能与ReactNode标记组合。
分段标记(分隔标记)- 将条形划分为不同分段的标记。可以与点标记组合。
ReactNode标记 - 用于复杂视觉元素的自定义React组件。不能与点或分段标记组合。
长按 - 当用户按住方向键按钮(向左或向右)时,触发加速搜索行为。
向前跳转/向后跳转 - 遥控器按钮(>>和<<),可模拟用于搜索内容的长按交互。
方向键导航 - 用于搜索和滑块拇指定位的向左或向右方向键控件。
焦点限制 - 启用后,在允许向上或向下导航的同时,防止焦点向左或向右移动到超出SeekBar的位置。
加速 - 长按或连续跳转操作时速度逐渐增加,由stepMultiplierFactor控制。
播放定位范围——限制总范围内可定位位置的边界(lowerSeekLimit或upperSeekLimit)。
分段 - 通过分隔符标记创建的搜索栏的各个部分,每个部分都有可自定义的颜色和视觉属性。
