From 7e529eb6d615fb4e6edbb789ac7b8dfce910e7b6 Mon Sep 17 00:00:00 2001 From: sky603629 Date: Thu, 16 Oct 2025 15:22:34 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0react-native-color-pi?= =?UTF-8?q?cker=E6=8C=87=E5=AF=BC=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: sky603629 --- en/react-native-color-picker.md | 139 ++++++++++++++++++++++++++++ zh-cn/react-native-color-picker.md | 141 +++++++++++++++++++++++++++++ 2 files changed, 280 insertions(+) create mode 100644 en/react-native-color-picker.md create mode 100644 zh-cn/react-native-color-picker.md diff --git a/en/react-native-color-picker.md b/en/react-native-color-picker.md new file mode 100644 index 00000000..8caa192d --- /dev/null +++ b/en/react-native-color-picker.md @@ -0,0 +1,139 @@ +> Template Version: v0.2.2 + +

+

react-native-color-picker

+

+

+ + Supported platforms + + + License + +

+ +> [!Tip] [Github Address](https://github.com/instea/react-native-color-picker) + +## Installation and Usage + +Navigate to your project directory and enter the following command: + + + +#### **npm** + +```bash +npm install react-native-color-picker@0.6.0 +``` + +#### **yarn** + +```bash +yarn add react-native-color-picker@0.6.0 +``` + + + +### Example + +The following code demonstrates how to use this color picker component in a page: + +> [!WARNING] The library name in the import statement remains unchanged. + +```javascript +import React from 'react' +import { View, Text, Alert } from 'react-native' +import { TriangleColorPicker, toHsv } from 'react-native-color-picker' + +export default class App extends React.Component { + + constructor(...args) { + super(...args) + this.state = { color: toHsv('green') } + this.onColorChange = this.onColorChange.bind(this) + } + + onColorChange(color) { + this.setState({ color }) + } + + render() { + return ( + + React Native Color Picker - Controlled + Alert.alert(`Color selected: ${color}`)} + onOldColorSelected={color => Alert.alert(`Old color selected: ${color}`)} + style={{flex: 1}} + /> + + ) + } + +} +``` + +## Constraints + +### Compatibility + +To use this library, you need to use the correct versions of React-Native and RNOH. Additionally, you need to use the corresponding versions of DevEco Studio and the phone's ROM. + +The content of this document has been verified with the following versions: + +react-native-harmony: 0.72.86; SDK: HarmonyOS 5.1.0.125; IDE: DevEco Studio 5.1.0.849; ROM: 5.0.0.150; + +react-native-harmony: 0.77.18; SDK: HarmonyOS 5.1.0.125; IDE: DevEco Studio 5.1.0.849; ROM: 5.0.0.150; + +## Properties + +> [!TIP] The "Platform" column indicates the platforms supported by the original third-party library. + +> [!TIP] In the "HarmonyOS Support" column, "yes" means the property is supported on the HarmonyOS platform; "no" means it is not supported; "partially" means it is partially supported. The usage is consistent across platforms, and the effect is aligned with that on iOS or Android. + +### Core Properties + +| Name | Description | Type | Required | Platform | HarmonyOS Support | +| :--- | :--- | :--- | :--- | :--- | :--- | +| `color` | A controlled property used to set the current color of the picker. | `String` \| `HSV` | No | All | yes | +| `defaultColor` | An uncontrolled property used to set the initial color of the picker. | `String` \| `HSV` | No | All | yes | +| `oldColor` | An old color for visual comparison. If provided, the center of the picker will be split to show both the new and old colors. | `String` | No | All | yes | +| `style` | Styles applied to the root container of the picker. | `Style` | No | All | yes | +| `hideSliders` | **(HoloPicker only)** Whether to hide the saturation and value sliders. Default: false | `boolean` | No | All | yes | +| `hideControls` | **(TrianglePicker only)** Whether to hide the color preview and confirmation button at the bottom. Default: false | `boolean` | No | All | yes | +| `sliderComponent`| **(HoloPicker only)** Pass in a custom slider component. | `React.Component` | No | All | yes | + +### Callback Functions + +| Name | Description | Type | Required | Platform | HarmonyOS Support | +| :--- | :--- | :--- | :--- | :--- | :--- | +| `onColorChange` | A callback triggered whenever the color changes. Returns the color as an HSV object. | `(color: HSV) => void` | No | All | yes | +| `onColorSelected`| A callback triggered when the user confirms a color selection (e.g., by tapping the center of the picker). Returns the color as a hex string. | `(color: string) => void` | No | All | yes | +| `onOldColorSelected` | A callback triggered when the user taps the old color preview area. Returns the old color as a hex string. | `(color: string) => void` | No | All | yes | + +### Utility Functions + +| Name | Description | Type | Required | Platform | HarmonyOS Support | +| :--- | :--- | :--- | :--- | :--- | :--- | +| `toHsv` | Converts a color string (e.g., `'blue'`, `'#ff0000'`) to an HSV object. | `(color: string) => HSV` | No | All | yes | +| `fromHsv`| Converts an HSV object to a hex color string. | `(hsv: HSV) => string` | No | All | yes | + +## Known Issues + +## Others + +**HSV Object Format**: +```javascript +{ + h: number, // Hue: 0-360 + s: number, // Saturation: 0-1 + v: number, // Value: 0-1 +} +``` + +## License + +This project is licensed under [The MIT License (MIT)](https://github.com/instea/react-native-color-picker/blob/master/LICENSE). \ No newline at end of file diff --git a/zh-cn/react-native-color-picker.md b/zh-cn/react-native-color-picker.md new file mode 100644 index 00000000..c305193f --- /dev/null +++ b/zh-cn/react-native-color-picker.md @@ -0,0 +1,141 @@ +> 模板版本：v0.2.2 + +

+

react-native-color-picker

+

+

+ + Supported platforms + + + License + +

+ +> [!Tip] [Github 地址](https://github.com/instea/react-native-color-picker) + +## 安装与使用 + +进入到工程目录并输入以下命令： + + + +#### **npm** + +```bash +npm install react-native-color-picker@0.6.0 +``` + +#### **yarn** + +```bash +yarn add react-native-color-picker@0.6.0 +``` + + + +### 示例 + +下面的代码展示了如何在一个页面中使用此颜色选择器组件： + +> [!WARNING] 使用时 import 的库名不变。 + +```javascript +import React from 'react' +import { View, Text, Alert } from 'react-native' +import { TriangleColorPicker, toHsv } from 'react-native-color-picker' + +export default class App extends React.Component { + + constructor(...args) { + super(...args) + this.state = { color: toHsv('green') } + this.onColorChange = this.onColorChange.bind(this) + } + + onColorChange(color) { + this.setState({ color }) + } + + render() { + return ( + + React Native Color Picker - Controlled + Alert.alert(`Color selected: ${color}`)} + onOldColorSelected={color => Alert.alert(`Old color selected: ${color}`)} + style={{flex: 1}} + /> + + ) + } + +} +``` + +## 约束与限制 + +### 兼容性 + +要使用此库，需要使用正确的 React-Native 和 RNOH 版本。另外，还需要使用配套的 DevEco Studio 和 手机 ROM。 + +本文档内容基于以下版本验证通过： + +react-native-harmony：0.72.86; SDK：HarmonyOS 5.1.0.125; IDE：DevEco Studio 5.1.0.849; ROM：5.0.0.150; + +react-native-harmony：0.77.18; SDK：HarmonyOS 5.1.0.125; IDE：DevEco Studio 5.1.0.849; ROM：5.0.0.150; + +## 属性 + +> [!TIP] "Platform"列表示该属性在原三方库上支持的平台。 + +> [!TIP] "HarmonyOS Support"列为 yes 表示 HarmonyOS 平台支持该属性；no 则表示不支持；partially 表示部分支持。使用方法跨平台一致，效果对标 iOS 或 Android 的效果。 + +### 核心属性 + +| Name | Description | Type | Required | Platform | HarmonyOS Support | +| :--- | :--- | :--- | :--- | :--- | :--- | +| `color` | 受控属性，用于设置选择器的当前颜色。 | `String` \| `HSV` | No | All | yes | +| `defaultColor` | 非受控属性，用于设置选择器的初始颜色。 | `String` \| `HSV` | No | All | yes | +| `oldColor` | 用于视觉比较的旧颜色。如果提供，选择器中心会分块显示新旧颜色。 | `String` | No | All | yes | +| `style` | 应用于选择器根容器的样式。 | `Style` | No | All | yes | +| `hideSliders` | **(仅限 HoloPicker)** 是否隐藏饱和度和明度滑块。默认值：false | `boolean` | No | All | yes | +| `hideControls` | **(仅限 TrianglePicker)** 是否隐藏底部的颜色预览和确认按钮。默认值：false | `boolean` | No | All | yes | +| `sliderComponent`| **(仅限 HoloPicker)** 传入一个自定义的滑块组件。 | `React.Component` | No | All | yes | + +### 回调函数 + +| Name | Description | Type | Required | Platform | HarmonyOS Support | +| :--- | :--- | :--- | :--- | :--- | :--- | +| `onColorChange` | 当颜色发生任何变化时触发的回调。返回 HSV 格式的颜色对象。 | `(color: HSV) => void` | No | All | yes | +| `onColorSelected`| 当用户确认选择颜色时触发（例如点击选择器中心）。返回十六进制颜色字符串。 | `(color: string) => void` | No | All | yes | +| `onOldColorSelected` | 当用户点击旧颜色预览区域时触发。返回旧颜色的十六进制字符串。 | `(color: string) => void` | No | All | yes | + +### 工具函数 + +| Name | Description | Type | Required | Platform | HarmonyOS Support | +| :--- | :--- | :--- | :--- | :--- | :--- | +| `toHsv` | 将颜色字符串（如 `'blue'`, `'#ff0000'`）转换为 HSV 对象。 | `(color: string) => HSV` | No | All | yes | +| `fromHsv`| 将 HSV 对象转换为十六进制颜色字符串。 | `(hsv: HSV) => string` | No | All | yes | + +## 遗留问题 + +## 其他 + +**HSV 对象格式**: +```javascript +{ + h: number, // 色相: 0-360 + s: number, // 饱和度: 0-1 + v: number, // 透明度: 0-1 +} +``` + +## 开源协议 + +本项目基于 [The MIT License (MIT)](https://github.com/instea/react-native-color-picker/blob/master/LICENSE) ，请自由地享受和参与开源。 + + -- Gitee