基于 react-native-slider 的 OpenHarmony 适配版,滑块选择器组件
| 文件 | 最后提交记录 | 最后更新时间 |
|---|---|---|
| 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
Link
| 是否支持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
然后编译、运行即可。
约束与限制
兼容性
本文档内容基于以下版本验证通过:
- 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) ,请自由地享受和参与开源。