rntpc_react-native-slider:基于 react-native-slider 的 OpenHarmony 适配版,滑块选择器组件

基于 react-native-slider 的 OpenHarmony 适配版,滑块选择器组件

分支5Tags4
文件最后提交记录最后更新时间
10 天前
9 天前
24 天前
10 天前
24 天前
1 个月前
1 个月前
24 天前
1 个月前
1 个月前
9 天前
1 年前
1 年前
1 个月前
24 天前
10 天前
10 天前
1 年前
1 个月前
10 天前
1 年前
1 年前

文档模板:v0.4.2

@react-native-community/slider

本项目基于 @react-native-community/slider 开发。

该第三方库的仓库已迁移至 Gitcode,且支持直接从 npm 下载,新的包名为:@react-native-ohos/slider 版本所属关系如下:

三方库名称 三方库版本(npm地址) 发布信息 支持RN版本 Autolink 编译API版本 社区基线版本 源码地址
@react-native-ohos/slider ~ 5.2.0(开发中) Gitcode Releases 0.84.* 是 API12+ 5.2.0 master
@react-native-ohos/slider ~ 5.1.2 Gitcode Releases 0.82.* 是 API12+ 5.1.1 br_rnoh0.82
@react-native-ohos/slider ~ 5.0.1 Gitcode Releases 0.77.* 否 API12+ 5.0.0 br_rnoh0.77
@react-native-ohos/slider ~ 4.4.4 Gitcode Releases 0.72.* 是 API12+ 4.4.3 br_rnoh0.72
@react-native-oh-tpl/slider <= 4.4.3-0.3.4@deprecated Github Releases(deprecated) 0.72.* 否 API12+ 4.4.3 sig

简介

Slider 组件用于 React Native。
Slider 是一个可在指定数值范围内选择单一值的交互组件,支持自定义样式、步进、禁用态及滑动回调等能力。
开发者可以快速接入并交付一致、可定制的滑动选择体验。

下载安装

进入到工程目录并输入以下命令:

npm

npm install @react-native-ohos/slider

yarn

yarn add @react-native-ohos/slider
是否支持autolink RN框架版本
~5.2.0 是 0.84

使用AutoLink的工程需要根据该文档配置,Autolink框架指导文档:https://gitcode.com/CPF-RN/ohos_react_native/blob/master/docs/zh-cn/Autolinking.md

如您使用的版本支持 Autolink,并且工程已接入 Autolink,可跳过ManualLink配置。

ManualLink: 此步骤为手动配置原生依赖项的指导

首先需要使用 DevEco Studio 打开项目里的 HarmonyOS 工程 harmony

1. Overrides RN SDK

为了让工程依赖同一个版本的 RN SDK,需要在工程根目录的 oh-package.json5 添加 overrides 字段,指向工程需要使用的 RN SDK 版本。替换的版本既可以是一个具体的版本号,也可以是一个模糊版本,还可以是本地存在的 HAR 包或源码目录。

关于该字段的作用请阅读官方说明

{
  ...
  "overrides": {
    "@rnoh/react-native-openharmony" : "./react_native_openharmony"
  }
}

2.引入原生端代码

目前有两种方法:

  • 通过 har 包引入;
  • 直接链接源码。

方法一:通过 har 包引入(推荐)

har 包位于三方库安装路径的 `harmony` 文件夹下。

打开 entry/oh-package.json5,添加以下依赖

"dependencies": {
    "@rnoh/react-native-openharmony": "file:../react_native_openharmony",
    "@react-native-ohos/slider": "file:../../node_modules/@react-native-ohos/slider/harmony/slider.har"
  }

点击右上角的 sync 按钮

或者在终端执行:

cd entry
ohpm install

方法二:直接链接源码

如需使用直接链接源码,请参考[直接链接源码说明](https://gitcode.com/CPF-RN/usage-docs/blob/master/zh-cn/link-source-code.md)

3.配置 CMakeLists 和引入 SliderPackage

打开 entry/src/main/cpp/CMakeLists.txt,添加:

project(rnapp)
cmake_minimum_required(VERSION 3.4.1)
set(RNOH_APP_DIR "${CMAKE_CURRENT_SOURCE_DIR}")
+set(OH_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/../../../oh_modules")
set(RNOH_CPP_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../../../../../react-native-harmony/harmony/cpp")

add_subdirectory("${RNOH_CPP_DIR}" ./rn)

# RNOH_BEGIN: add_package_subdirectories
add_subdirectory("../../../../sample_package/src/main/cpp" ./sample-package)
+ add_subdirectory("${OH_MODULES}/@react-native-ohos/slider/src/main/cpp" ./slider)
# RNOH_END: add_package_subdirectories

add_library(rnoh_app SHARED
    "./PackageProvider.cpp"
    "${RNOH_CPP_DIR}/RNOHAppNapiBridge.cpp"
)

target_link_libraries(rnoh_app PUBLIC rnoh)

# RNOH_BEGIN: link_packages
target_link_libraries(rnoh_app PUBLIC rnoh_sample_package)
+ target_link_libraries(rnoh_app PUBLIC rnoh_slider)
# RNOH_END: link_packages

打开 entry/src/main/cpp/PackageProvider.cpp,添加:

#include "RNOH/PackageProvider.h"
#include "SamplePackage.h"
+ #include "SliderPackage.h"

using namespace rnoh;

std::vector<std::shared_ptr<Package>> PackageProvider::getPackages(Package::Context ctx) {
    return {
      std::make_shared<SamplePackage>(ctx),
+     std::make_shared<SliderPackage>(ctx)
    };
}

4.在 ArkTs 侧引入 slider 组件

找到 function buildCustomRNComponent(),一般位于 entry/src/main/ets/pages/index.ets 或 entry/src/main/ets/rn/LoadBundle.ets,添加:

  ...
+ import { RNCSlider, SLIDER_TYPE } from "@react-native-ohos/slider"

@Builder
export function buildCustomRNComponent(ctx: ComponentBuilderContext) {
  ...
+ if (ctx.componentName === SLIDER_TYPE) {
+   RNCSlider({
+     ctx: ctx.rnComponentContext,
+     tag: ctx.tag,
+   })
+ }
 ...
}
...

本库使用了混合方案,需要添加组件名。

在entry/src/main/ets/pages/index.ets 或 entry/src/main/ets/rn/LoadBundle.ets 找到常量 arkTsComponentNames 在其数组里添加组件名

const arkTsComponentNames: Array<string> = [
  SampleView.NAME,
  GeneratedSampleView.NAME,
  PropsDisplayer.NAME,
+ SLIDER_TYPE
  ];

5. 在 ArkTs 侧引入 SliderPackage

打开 entry/src/main/ets/RNPackagesFactory.ts,添加:

  ...
+ import {SliderPackage} from '@react-native-ohos/slider';

export function createRNPackages(ctx: RNPackageContext): RNPackage[] {
  return [
    new SamplePackage(ctx),
+   new SliderPackage(ctx)
  ];
}

运行

点击右上角的 sync 按钮

或者在终端执行:

cd entry
ohpm install

然后编译、运行即可。

约束与限制

兼容性

本文档内容基于以下版本验证通过:

  1. RNOH: 0.84.2; SDK: HarmonyOS 6.0.1 Release SDK; IDE: DevEco Studio 26.0.0 Beta1; ROM: 6.0.0.120 SP7;

使用示例

下面的代码展示了这个库的基本使用场景:

使用时 import 的库名不变。

使用thumbImage属性时请确保引入的图片路径地址正确,可检查harmony/entry/src/main/resources/rawfile/assets目录下是否被打包至静态资源目录,如若不存在则图片放置文件目录不对

import Slider from "@react-native-community/slider"
import { View } from 'react-native'

export default function SliderExample() {
    return (
        <View style={{ backgroundColor: 'red', width: 200, height: 100 }}>
            <Slider
                style={{ width: 200, height: 40 }}
                minimumValue={0}
                maximumValue={1}
                minimumTrackTintColor="#FFFFFF"
                maximumTrackTintColor="#000000"
            />
        </View>
    );
};

接口说明

"Platform"列表示该属性在原三方库上支持的平台。

"OpenHarmony Support"列为 yes 表示 OpenHarmony平台支持 该属性;no 则表示不支持;partially 表示部分支持。使用方法跨平台一致,效果对标 iOS 或 Android 的效果。

组件

名称 参数类型 必填 平台 OpenHarmony平台支持 描述
Slider SliderProps yes all yes Slider组件

属性

SliderProps

名称 参数类型 默认值 必填 平台 OpenHarmony平台支持 描述
style View.style - 否 所有平台 是 用于设置 Slider 的样式和布局。详见 StyleSheet.js 和 ViewStylePropTypes.js。
disabled boolean false 否 所有平台 是 如果为 true,用户将无法移动滑块。
默认值为 false。
maximumValue number 1 否 所有平台 是 滑块的初始最大值。
默认值为 1。
minimumTrackTintColor color - 否 所有平台 是 滑块按钮左侧轨道的颜色。
在 iOS 上覆盖默认的蓝色渐变图像。
minimumValue number 0 否 所有平台 是 滑块的初始最小值。
默认值为 0。
lowerLimit number Number.MIN_SAFE_INTEGER 否 Android, iOS 是 滑动下限。用户将无法滑到该限制以下。
upperLimit number Number.MAX_SAFE_INTEGER 否 Android, iOS 是 滑动上限。用户将无法滑到该限制以上。
onSlidingStart (value: number) => void - 否 所有平台 是 用户开始拖动滑块时调用的回调函数。
初始值作为参数传递给回调处理函数。
onSlidingComplete (value: number) => void - 否 所有平台 是 用户释放滑块时调用的回调函数,无论值是否已更改。
当前值作为参数传递给回调处理函数。
onValueChange (value: number) => void - 否 所有平台 是 用户拖动滑块时持续调用的回调函数。
step number 0 否 所有平台 是 滑块的步长值。该值应在 0 到 (maximumValue - minimumValue) 之间。默认值为 0。
在 Windows 操作系统上,默认值为滑块范围(从 minimumValue 到 maximumValue)的 1%。
maximumTrackTintColor color - 否 所有平台 是 滑块按钮右侧轨道的颜色。
在 iOS 上覆盖默认的灰色渐变图像。
value number 0 否 所有平台 是 表示滑块值的只写属性。可用于以编程方式控制滑块拇指的位置。在开始时输入一次仍作为初始值。以编程方式更改值不会触发任何事件。
该值应在 minimumValue 和 maximumValue 之间,默认值分别为 0 和 1。默认值为 0。
这不是受控组件,您不需要在拖动过程中更新值。
tapToSeek boolean false 否 iOS 否 允许点击滑块轨道来设置拇指位置。
在 iOS 上默认为 false。在 Android 或 Windows 上无效。
inverted boolean false 否 所有平台 是 反转滑块的方向。
默认值为 false。
vertical boolean false 否 Windows 是 如果设置为 true,则将滑块方向更改为垂直。
默认值为 false。
thumbTintColor color - 否 Android 是 前景滑块手柄的颜色。
注意: 此属性将覆盖设置的 thumbImage 属性,这意味着如果同时设置了 thumbImage 和 thumbTintColor,用于拇指的图像可能无法正确显示!
maximumTrackImage Image
.propTypes
.source
- 否 iOS 是 分配最大轨道图像。仅支持静态图像。图像的最左侧像素将被拉伸以填充轨道。 本实现使用 ImageFit.Fill 整图拉伸,不实现 iOS 的中心/边缘像素 cap-inset 拉伸,圆角及装饰边框可能变形。
minimumTrackImage Image
.propTypes
.source
- 否 iOS 是 分配最小轨道图像。仅支持静态图像。图像的最右侧像素将被拉伸以填充轨道。 本实现使用 ImageFit.Fill 整图拉伸,不实现 iOS 的中心/边缘像素 cap-inset 拉伸,圆角及装饰边框可能变形。
thumbImage Image
.propTypes
.source
- 否 所有平台 是 为拇指设置图像。仅支持静态图像。需要是本地或网络图像的 URI;不支持 base64 编码的 SVG。
thumbSize number 0(默认外观) 否 所有平台 是 设置拇指(Thumb)的尺寸(宽和高)。若同时提供了 thumbImage,图片将按此尺寸缩放;未设置(或为 0)时使用平台默认外观。
trackImage Image
.propTypes
.source
- 否 iOS 是 为轨道分配单个图像。仅支持静态图像。图像的中心像素将被拉伸以填充轨道。 本实现使用 ImageFit.Fill 整图拉伸,不实现 iOS 的中心/边缘像素 cap-inset 拉伸,圆角及装饰边框可能变形。
ref MutableRefObject - 否 web 否 引用对象。
View - - - - - 继承的 View 属性...
StepMarker FC<MarkerProps> - 否 iOS, Android, Windows 是 用于在滑轨上渲染每个刻度的组件,可根据滑块位置动态改变该刻度的样式。
renderStepNumber boolean false 否 iOS, Android, Windows 是 启用步骤编号显示功能。步骤编号将显示在滑轨下方。
accessibilityUnits string - 否 iOS 否 供屏幕阅读器播报的单位词(一个或多个单词)。未设置时按百分比播报当前值。
需同时传入 accessibilityIncrements 才能正确工作。应为复数形式,单数单位会由系统处理。
accessibilityIncrements Array<string> - 否 iOS 否 表示滑块各增量档位的字符串数组,所有元素必须为字符串。
需同时传入 accessibilityUnits 才能正确工作。元素数量须与 maximumValue 相同。
testID string - 否 iOS, Android, Windows 是 用于在UI自动化测试中定位此视图。

StepMarker

您的自定义组件会渲染到滑块的每一步上,包括滑块的拖动块以及沿滑块全长的其余步骤。该StepMarker属性接受您的自定义组件,并为其提供以下参数:

名称 参数类型 默认值 必填 平台 OpenHarmony平台支持 描述
stepMarked boolean - 是 iOS, Android, Windows 是 标识当前刻度是否为滑块所在位置。若用户拖动或点击该刻度,滑块将移至此处且stepMarked参数将变为true。可用于区分渲染自定义滑块组件或自定义刻度标记。
currentValue number - 是 iOS, Android, Windows 是 包含Slider当前滑块位置的数值。可用于在刻度标记上显示Slider数值,或根据滑块位置渲染不同变体的刻度标记。
index number - 是 iOS, Android, Windows 是 当前自定义刻度标记实例的渲染索引号。可用于在刻度标记内显示步骤序号,或根据刻度在滑轨上的位置渲染多种变体。
min number 0 是 iOS, Android, Windows 是 Slider的最小值,与minimumValue属性相同,未设置时采用相同默认值。
max number 1 是 iOS, Android, Windows 是 Slider的最大值,与maximumValue属性相同,未设置时采用相同默认值。

遗留问题

其他

无

目录结构

/rntpc_react-native-slider  # 项目根目录
├── harmony              # 鸿蒙适配代码
│    └─ slider                  # 鸿蒙适配核心代码
│          └─ index.ets    # 鸿蒙适配代码入口
│          └─ src/main/ets
│              └─ Slider.ets  # Slider 组件
│              └─ SliderDescriptorWrapper.ets  # 组件描述封装
│              └─ SliderPackage.ets  # ArkTS 侧包注册
│              └─ Logger.ets  # 日志工具
│          └─ src/main/cpp
│              └─ CMakeLists.txt  # CMake 构建配置
│              └─ SliderPackage.h  # 原生包注册
│              └─ SliderJSIBinder.h  # JSI 绑定
│              └─ SliderNapiBinder.h  # NAPI 绑定
│              └─ SliderEventEmiRequestHandler.h  # 事件发射请求处理
│              └─ ComponentDescriptor.h  # 组件描述符
│              └─ Props.h / Props.cpp  # 属性定义
│              └─ EventEmitters.h / EventEmitters.cpp  # 事件发射
│              └─ ShadowNodes.h / ShadowNodes.cpp  # Shadow Node
├── src                  # RN代码
│    └─ index.ts  # 入口文件
│    └─ Slider.tsx  # Slider 组件
│    └─ RNCSliderNativeComponent.ts  # 原生组件类型文件
│    └─ components  # 刻度相关组件
│    └─ utils  # 样式与常量工具
├── typings
│    └─ index.d.ts  # 类型声明
├── README.md           # 中文安装使用方法
├── README_en.md   # 英文安装使用方法

贡献代码

使用过程中发现任何问题都可以提交 Issue,当然,也非常欢迎提交 PR 。

开源协议

本项目基于 The MIT License (MIT) ,请自由地享受和参与开源。

项目介绍

基于 react-native-slider 的 OpenHarmony 适配版,滑块选择器组件

定制我的领域