react-native-awesome-slider

本项目基于 react-native-awesome-slider开发。如果在使用过程中有任何问题，欢迎在AtomGit提交Issue，会及时跟进。

项目介绍

@hxa-rn/react-native-awesome-slider 是 react-native-awesome-slider 的鸿蒙适配包，当前版本 2.9.3。

本库为 js-only 纯 TypeScript 滑块组件，基于 react-native-reanimated 与 react-native-gesture-handler 实现连续/离散滑动、步进吸附、缓存条、气泡数值提示、触觉回调、主题与自定义渲染。无自有原生 HAR / TurboModule / Fabric，运行时依赖已适配的鸿蒙 reanimated 与 gesture-handler。

核心能力：

• Slider：进度条、缓存条、步进刻度、气泡、RTL、心跳动画
• Bubble：滑动时数值气泡（非 web 经 TextInput.setNativeProps 更新文本）
• HapticModeEnum / PanDirectionEnum：触觉模式与滑动方向枚举

集成指南

npm install @hxa-rn/react-native-awesome-slider

在 harmony.alias 映射下，业务代码仍从原包名导入：

import { Slider } from 'react-native-awesome-slider';

宿主还需安装与 RNOH 版本配套的：

• @react-native-ohos/react-native-reanimated@~3.6.5
• @react-native-ohos/react-native-gesture-handler@2.14.18

App 根节点需包裹 GestureHandlerRootView，babel.config.js 的 plugins 末尾需加入 react-native-reanimated/plugin。js-only 库无需 Manual Link / HAR / C++ Package 注册。

使用说明

import React from 'react';
import { GestureHandlerRootView } from 'react-native-gesture-handler';
import { Slider } from 'react-native-awesome-slider';
import { useSharedValue } from 'react-native-reanimated';

export default function App() {
  const progress = useSharedValue(30);
  const minimumValue = useSharedValue(0);
  const maximumValue = useSharedValue(100);

  return (
    <GestureHandlerRootView style={{ flex: 1, justifyContent: 'center', padding: 16 }}>
      <Slider
        progress={progress}
        minimumValue={minimumValue}
        maximumValue={maximumValue}
        onValueChange={(value) => {
          console.log('value:', value);
        }}
        onSlidingComplete={(value) => {
          console.log('complete:', value);
        }}
      />
    </GestureHandlerRootView>
  );
}

步进 + 强制吸附示例：

<Slider
  progress={progress}
  minimumValue={minimumValue}
  maximumValue={maximumValue}
  steps={10}
  forceSnapToStep
  hapticMode="step"
  onHapticFeedback={() => {
    // 宿主实现震动；库本身只触发回调
  }}
/>

接口文档

导出

导出	类型	说明
Slider	React.FC<AwesomeSliderProps>	主滑块组件
Bubble	ForwardRefExoticComponent	数值气泡，ref.setText(text)
HapticModeEnum	enum	NONE / STEP / BOTH
PanDirectionEnum	enum	START / LEFT / RIGHT / END
AwesomeSliderProps	type	Slider 全部 Props
SliderThemeType	type	主题颜色

Slider 主要 Props

Prop	类型	默认值	说明
progress	SharedValue<number>	必填	当前进度
minimumValue	SharedValue<number>	必填	最小值
maximumValue	SharedValue<number>	必填	最大值
cache	SharedValue<number>	—	缓存进度条
steps	number	—	分段数量，渲染 N+1 个刻度
forceSnapToStep	boolean	false	强制吸附最近刻度
snapThreshold / snapThresholdMode	number / 'percentage' | 'absolute'	0 / 'absolute'	阈值磁吸（absolute 为像素）
stepTimingOptions	false | WithTimingConfig	false	步进切换动画
disable	boolean	false	禁用拖拽与点击
disableTapEvent	boolean	false	点击不改值（onTap 仍触发）
disableTrackFollow	boolean	false	拖拽过程轨道不跟随
disableTrackPress	boolean	false	仅拇指附近可拖
bubble / renderBubble / setBubbleText	function	—	气泡文本与自定义渲染
bubbleWidth / bubbleMaxWidth / bubbleOffsetX / bubbleTranslateY	number	0 / 100 / 0 / -25	气泡尺寸与位置
renderThumb / renderMark / renderTrack / renderContainer	function	—	自定义渲染插槽
hapticMode / onHapticFeedback	enum / () => void	'none'	触觉模式与回调，库不实现设备震动
theme	SliderThemeType	默认主题	轨道 / 进度 / 缓存 / 气泡 / 心跳色
isRTL	boolean	I18nManager.isRTL	RTL 布局
heartbeat	boolean	false	进度条心跳动画
isScrubbing / panDirectionValue / thumbScaleValue	SharedValue	—	滑动状态、方向、拇指缩放
onSlidingStart / onValueChange / onSlidingComplete / onTap	function	—	滑动与点击回调
panHitSlop	Insets	—	手势命中扩展
activeOffsetX / activeOffsetY / failOffsetX / failOffsetY	number / [number, number]	—	手势激活 / 失败偏移
testID	string	—	测试标识

Bubble

Prop / 方法	说明
color / textColor / textStyle / containerStyle / bubbleMaxWidth	外观
setText(text)	更新气泡文本（非 web：setNativeProps）

废弃：step 请改用 steps；snapToStep 请改用 forceSnapToStep。同时提供时优先 steps；snapToStep 或 forceSnapToStep 任一为 true 即启用吸附。

快速验证（运行 Example）

前置条件

依赖	版本要求
Node.js	>= 18
DevEco Studio	5.0+ / 6.0+
HarmonyOS SDK	API 12+

运行步骤

1. 克隆仓库

git clone https://gitcode.com/hxa-rn/react-native-awesome-slider.git
cd react-native-awesome-slider
git checkout main

2. 安装仓库开发依赖

npm install --legacy-peer-deps

Example 已改为从 npm 公仓安装 @hxa-rn/react-native-awesome-slider@2.9.3，不再使用本地 file:../xxx.tgz，运行 Example 不必再执行 npm pack。

3. 进入 example 目录，安装依赖

cd example
npm install --legacy-peer-deps

4. 生成 JS Bundle

npm run dev

产物：harmony/entry/src/main/resources/rawfile/bundle.harmony.js

5. 用 DevEco Studio 打开鸿蒙工程

• 打开 DevEco Studio
• 选择 example/harmony 目录
• 等待 Sync 完成

6. 编译并运行 HAP

在 DevEco Studio 中点击运行按钮，将 HAP 安装到设备/模拟器。

注意：Example 中已预置插件依赖和 Package 注册，无需手动配置 Link。

约束与限制

• 兼容性：HarmonyOS compatibleSdkVersion 为 5.0.1(13)（example / example_auto 一致）。上游 RN / RNOH 按 peerDependencies 为 React Native >=0.72，本适配包按 RNOH 0.72.5 验证。
• 权限：无额外系统权限。
• 架构：js-only，无自有 HAR，无需 Manual Link / C++ Package 注册。
• 触觉反馈：hapticMode 仅触发 onHapticFeedback，设备震动由宿主实现。
• 气泡文本：非 web 分支使用 TextInput.setNativeProps，鸿蒙端需真机确认实时刷新。
• Web 分支：Platform.OS === 'web' 不适用鸿蒙，鸿蒙走 native 分支。

开源license

本项目基于 MIT 协议，详见 LICENSE 文件。

问题反馈渠道

欢迎在 AtomGit 提交 Issue。也可通过 GitCode 仓库反馈：

https://gitcode.com/hxa-rn/react-native-awesome-slider

https://gitcode.com/hxa-rn/react-native-awesome-slider/issues