react-native-awesome-slider

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

项目介绍

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

本库为 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/[email protected]

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 br_rnoh0.72

2. 安装仓库开发依赖

npm install --legacy-peer-deps

Example 已改为从 npm 公仓安装 @hxa-rn/[email protected]，不再使用本地 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