SeekBar组件是一个交互式进度控件,提供媒体导航功能。通过提供电视媒体播放器中常用的高级播放控制功能,它的运用不仅限于基本进度条。
使用场景
SeekBar组件非常适合需要媒体导航的应用,例如:
- 视频/音频播放器
- 时间轴拖动
- 内容预览系统
- 进度跟踪接口
- 交互式媒体导航
用户体验
核心属性
currentValue
必需 内容进度的当前位置值。
类型 number
必须介于0和totalValue(含)之间。
totalValue
必需 搜索栏的最大值,表示总持续时间或范围。
类型 number
step
使用方向键导航时要递增或递减的值。值可以是正数或负数。交互控制属性
disabled
启用或禁用具有遥控器事件的所有用户交互。boolean\
默认值 false
disabledWhenNotFocused
如果为true,则在未聚焦搜索栏时禁用用户交互。此属性对于焦点管理至关重要的电视界面非常重要,如果您希望组件自动处理焦点管理而不是在应用代码中手动处理它,则此属性是理想的选择。
boolean\
默认值 false
disableThumbnail
启用或禁用预览缩略图功能。要显示缩略图,请使用thumbnailImageSource属性。
boolean\
默认值 false
trapFocus
控制SeekBar组件的焦点导航行为。
boolean\
默认值 false
启用后,限制用于SeekBar中的向左或向右方向键导航的焦点。向上或向下导航到SeekBar上方或下方的控件仍然可用。
partialDisablingConfiguration
用于控制要禁用哪些特定的用户交互。PartialDisablingConfiguration
如果提供,此属性将覆盖全局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
displayBelowThumb
要在搜索栏滑块拇指下方呈现的自定义内容。您可以使用渲染函数或React Node。(() => React.ReactNode) | React.ReactNode
thumbIcon
自定义的滑块拇指图标组件。您可以使用渲染函数或React Node。渲染函数接收{ focused }属性。
((props: ThumbIconProps) => React.ReactNode) | React.ReactNode
注意 当使用带有focused回调参数的动态图标时,请设置disabledWhenNotFocused={true}以实现正确的焦点行为。
currentValueIndicatorColor
进度指示器已填充部分的颜色。您可以使用静态颜色或根据焦点状态返回颜色的函数。
类型 ColorValue | ((isFocused: boolean) => ColorValue)
barTrackColor
滑块未填充部分的颜色。
类型 ColorValue
segmentColors
分段的颜色配置。SegmentColorsConfig
segmentColors seekColor。如果没有分隔标记,则分段颜色将不适用于搜索栏。
用法示例
黄色分段颜色
红色分段颜色
样式属性
barStyle
滑块的样式覆盖项。
类型 StyleProp<ViewStyle>
currentValueIndicatorStyle
进度指示器的样式覆盖项。StyleProp<ViewStyle>
timeShiftIndicatorStyle
timeshift指示器的样式覆盖项。
类型 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
启用长按交互期间的渐进加速。启用后,根据stepMultiplierFactor和stepMultiplierFactorInterval设置,步长乘数随时间推移而增大(例如,1x、2x、3x、4x)。step值乘以当前乘数。影响按住向左或向右按键或按钮时的搜索速度。
boolean\
默认值 false
enableSkipForwardBackwardAcceleration
在向前或向后跳过交互时启用渐进加速。启用后,连续向前跳转 (>>) 或向后跳转 (<<) 按钮会根据stepMultiplierFactor设置增加步长乘数(例如,1x、2x、3x、4x、5x)。step值乘以当前乘数。
boolean\
默认值 false
enableAnimations
启用或禁用搜索栏滑块拇指和进度动作的动画。 当为true时,拖动条会顺畅地以动画显示位置变化,并且不应用timeShiftIndicatorStyle属性。如果为false,则位置会立即发生变化,所有视觉元素都会被渲染。
boolean\
默认值 false

