From b5d6d7a761950aa4a043c326d86c2b5a364e4c95 Mon Sep 17 00:00:00 2001 From: zhang_hanyong Date: Tue, 4 Jun 2024 17:55:26 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9Ereact-native-syan-ima?= =?UTF-8?q?ge-picker=E5=BA=93=E7=9A=84usage-docs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: zhang_hanyong --- zh-cn/react-native-syan-image-picker.md | 285 ++++++++++++++++++++++++ 1 file changed, 285 insertions(+) create mode 100644 zh-cn/react-native-syan-image-picker.md diff --git a/zh-cn/react-native-syan-image-picker.md b/zh-cn/react-native-syan-image-picker.md new file mode 100644 index 00000000..13cfc9bc --- /dev/null +++ b/zh-cn/react-native-syan-image-picker.md @@ -0,0 +1,285 @@ +> 模板版本：v0.2.1 + +

+

react-native-syan-image-picker

+

+

+ + Supported platforms + + + License + + +

+ +> [!TIP] [Github 地址](https://github.com/react-native-oh-library/react-native-syan-image-picker) + +## 安装与使用 + +请到三方库的 Releases 发布地址查看配套的版本信息：[@react-native-oh-tpl/react-native-syan-image-picker Releases](https://github.com/react-native-oh-library/react-native-syan-image-picker/releases)，并下载适用版本的 tgz 包。 + +进入到工程目录并输入以下命令： + +> [!TIP] # 处替换为 tgz 包的路径 + + + +#### **npm** + +```bash +npm install @react-native-oh-tpl/react-native-syan-image-picker@file:# +``` + +#### **yarn** + +```bash +yarn add @react-native-oh-tpl/react-native-syan-image-picker@file:# +``` + + + +下面的代码展示了这个库的基本使用场景： + +```js +import React from "react"; +import { + StyleSheet, + Text, + View, + Image, + ScrollView, + TouchableOpacity, + Dimensions +} from 'react-native'; +import SYImagePicker from "react-native-syan-image-picker/src/SYImagePicker"; + +export default class App extends Component<{}> { + constructor(props) { + super(props); + this.state = { + photos: [], + }; + } + /** + * 开启压缩，选择一张照片先裁剪然后再压缩，并支持base64编码 + **/ +SYImagePicker.showImagePicker( + { + /** + * imageCount为1才支持裁剪 + **/ + imageCount: 1, + isCrop: true, + quality: 90, + compress: true, // 开启压缩 + enableBase64: false, + }, + (err, photos) => { + if (!err) { + this.setState({ + photos, + }); + } else { + console.log(err); + } + }, + ); +/** + * 关闭压缩，多选照片并支持base64编码 + **/ + handleAsyncSelectPhoto = async () => { + SYImagePicker.removeAllPhoto() + try { + const photos = await SYImagePicker.asyncShowImagePicker({ + imageCount: 8, //指定选择的照片数量 + enableBase64: true, // 支持base64编码 + }); + // 选择成功 + this.setState({ + photos: [...this.state.photos, ...photos], + }); + } catch (err) { + console.log(err); + // 取消选择，err.message为"取消" + } + }; +/** +* 缓存清除 +**/ +handleDeleteCache = () => { + SYImagePicker.deleteCache(); + }; + +/** +* 移除选中的图片 +**/ +handleDeletePhoto = index => { + const { selectedPhotos: oldPhotos } = this.state; + const selectedPhotos = oldPhotos.filter((photo, photoIndex) => photoIndex !== index); + // 更新原生图片数组 + SYImagePicker.removePhotoAtIndex(index); + } + +/** +* 移除选中的全部图片 +**/ +STImagePicke.removeAllPhoto() + +/** +* 调用相机 +**/ +SyanImagePicker.openCamera(options, (err, photos) => { + if (err) { + // 取消选择 + return; + } + // 选择成功，渲染图片 + // ... +}) + +/** +* 选择视频 +**/ +SyanImagePicker.openVideoPicker(options, (err, videos) => { + if (err) { + // 取消选择 + return; + } + // 选择成功，处理视频 + // ... +}) + +} +``` + +## Link + +目前鸿蒙暂不支持 AutoLink，所以 Link 步骤需要手动配置。 + +首先需要使用 DevEco Studio 打开项目里的鸿蒙工程 `harmony` + +### 在工程根目录的 `oh-package.json` 添加 overrides 字段 + +```json +{ + ... + "overrides": { + "@rnoh/react-native-openharmony" : "./react_native_openharmony" + } +} +``` + +### 引入原生端代码 + +目前有两种方法： + +1. 通过 har 包引入（在 IDE 完善相关功能后该方法会被遗弃，目前首选此方法）； +2. 直接链接源码。 + +方法一：通过 har 包引入（推荐） + +> [!TIP] har 包位于三方库安装路径的 `harmony` 文件夹下。 + +打开 `entry/oh-package.json5`，添加以下依赖 + +```json +"dependencies": { + "@rnoh/react-native-openharmony": "file:../react_native_openharmony", + "@react-native-oh-tpl/react-native-syan-image-picker": "file:../../node_modules/@react-native-oh-tpl/react-native-syan-image-picker/harmony/syan_image_picker.har" + } +``` + +点击右上角的 `sync` 按钮 + +或者在终端执行： + +```bash +cd entry +ohpm install +``` + +方法二：直接链接源码 + +> [!TIP] 如需使用直接链接源码，请参考[直接链接源码说明](/zh-cn/link-source-code.md) + +### 在 ArkTs 侧引入SyanImagePickerPackage + +打开 `entry/src/main/ets/RNPackagesFactory.ts`，添加： + +```diff +... ++ import {SyanImagePickerPackage} from '@react-native-oh-tpl/react-native-syan-image-picker/ts'; + +export function createRNPackages(ctx: RNPackageContext): RNPackage[] { + return [ + new SamplePackage(ctx), ++ new SyanImagePickerPackage(ctx) + ]; +} +``` + +### 运行 + +点击右上角的 `sync` 按钮 + +或者在终端执行： + +```bash +cd entry +ohpm install +``` + +然后编译、运行即可。 + +## 约束与限制 + +### 兼容性 + +要使用此库，需要使用正确的 React-Native 和 RNOH 版本。另外，还需要使用配套的 DevEco Studio 和 手机 ROM。 + +请到三方库相应的 Releases 发布地址查看 Release 配套的版本信息：[@react-native-oh-tpl/react-native-syan-image-picker Releases](https://github.com/react-native-oh-tpl/react-native-syan-image-picker/releases) + +## ImagePickerOption(选择图片或数据的配置项) + +| Name | Description | Type | Required | Platform | HarmonyOS Support | +| ------------------------- | -------------------------------- | ------- | -------- | -------- | ----------------- | +| imageCoun | 最大选择图片数目，默认6 | number | yes | yes | yes | +| isCamera | 是否允许用户在内部拍照，默认true | boolean | yes | yes | yes | +| isCrop | 是否允许裁剪，默认false, imageCount 为1才生效 | boolean | yes | yes | yes | +| compress | 是否压缩照片 | boolean | yes | yes | yes | +| quality | 压缩质量 | number | yes | yes | yes | +| enableBase64 | 是否返回base64编码，默认不返回 | boolean | yes | yes | yes | +| videoCount | 选择的视频个数 | number | yes | yes | yes | +| allowPickingMultipleVideo | 允许选择多个视频 | boolean | yes | yes | yes | + +## SelectedPhoto（选择的图片或视频返回的数据） + +| Name | Description | Type | Required | Platform | HarmonyOS Support | +| ------------ | ---------------------------------------------- | ------ | -------- | -------- | ----------------- | +| width | 图片宽度 | number | yes | yes | yes | +| height | 图片高度 | number | yes | yes | yes | +| original_uri | 图片原始路径 | string | yes | yes | yes | +| uri | 图片路径 | string | yes | yes | yes | +| type | 文件类型 | string | yes | yes | yes | +| size | 图片大小，单位为字节 b | number | yes | yes | yes | +| base64 | 图片的 base64 编码，如果 enableBase64 设置 false，则不返回该属性 | string | yes | yes | yes | + +## API + +| Name | Description | Type | Required | Platform | HarmonyOS Support | +| -------------------- | ----------------- | -------------------------------------------------------- | -------- | -------- | ----------------- | +| showImagePicker | 打开图片选择器，选择图片 | callback: (err: null \| string, photos: SelectedPhoto[]) | yes | yes | yes | +| asyncShowImagePicker | 打开图片选择器，选择图片 | Promise | yes | yes | yes | +| openCamera | 打开相机拍照，并可以选择所拍的照片 | callback: (err: null \| string, photos: SelectedPhoto[]) | yes | yes | yes | +| asyncOpenCamera | 打开相机拍照，并可以选择所拍的照片 | Promise | yes | yes | yes | +| deleteCache | 清除缓存 | void | yes | yes | yes | +| removePhotoAtIndex | 删除已选择照片的索引 | void | yes | yes | yes | +| removeAllPhoto | 删除所有已选择的照片 | void | yes | yes | yes | +| openVideoPicker | 打开视频选择器 | callback: (err: null \| string, photos: SelectedPhoto[]) | yes | yes | yes | + +## 其他 + +## 开源协议 + +本项目基于 [The MIT License (MIT)](https://https://github.com/syanbo/react-native-syan-image-picker/LICENSE.md) ，请自由地享受和参与开源。 -- Gitee