diff --git a/_sidebar.md b/_sidebar.md index c9e42e32c71f908eea7c83f2debe0d2411b23fca..6e381886b174b76c64313c9d622b0579e2506188 100644 --- a/_sidebar.md +++ b/_sidebar.md @@ -50,6 +50,8 @@ - [lottie-react-native](/zh-cn/lottie-react-native.md) - [react-native-image-sequence-2](/zh-cn/react-native-image-sequence-2.md) - [react-native-clippath](/zh-cn/react-native-clippath.md) + - [react-native-image-crop-picker](/zh-cn/react-native-image-crop-picker.md) + - RN JS库 - [react-i18next](/zh-cn/react-i18next.md) - [react-native-action-button](/zh-cn/react-native-action-button.md) diff --git a/zh-cn/README.md b/zh-cn/README.md index 1bc6fbead31faf2bcbbf7c79bb957a1f2f3f49cb..7805650064c97302e90e7bd360a8f375ff208d1a 100644 --- a/zh-cn/README.md +++ b/zh-cn/README.md @@ -148,6 +148,7 @@ | 126 | [react-native-feather](https://github.com/yigithanyucedag/react-native-feather "https://github.com/yigithanyucedag/react-native-feather") | 1.1.2 | \- | \- | [链接](https://react-native-oh-library.gitee.io/usage-docs/#/zh-cn/react-native-feather) | | 127 | [@react-navigation/native-stack](https://github.com/react-navigation/react-navigation/tree/main/packages/native-stack) | 6.9.26 | \- | [@react-native-oh-tpl/native-stack](https://github.com/react-native-oh-library/react-navigation/tree/sig/packages/native-stack) | [链接](/zh-cn/react-navigation-native-stack)| | 128 | [react-native-clippath](https://github.com/Only-IceSoul/react-native-clippath) | 1.1.8 | 是 | [@react-native-oh-tpl/react-native-clippath](https://github.com/react-native-oh-library/react-native-clippath/releases) | [链接](https://react-native-oh-library.gitee.io/usage-docs/#/zh-cn/react-native-clippath) | +| 128 | [react-native-image-crop-picker](https://github.com/ivpusic/react-native-image-crop-picker) | 0.40.3 | 是 | [@react-native-image-crop-picker](https://github.com/react-native-oh-library/react-native-clippath/releases) | [链接](https://react-native-oh-library.gitee.io/usage-docs/#/zh-cn/react-native-image-crop-picker) | ## 社区 diff --git a/zh-cn/react-native-image-crop-picker.md b/zh-cn/react-native-image-crop-picker.md new file mode 100644 index 0000000000000000000000000000000000000000..2fc68306f9be44b9feffd6972e1061be9f98095d --- /dev/null +++ b/zh-cn/react-native-image-crop-picker.md @@ -0,0 +1,435 @@ +> > 模板版本：v0.2.0 +> +>

+>

@react-native-oh-tpl/react-native-image-crop-picker

+>

+>

+> +> Supported platforms +> +> +> License +> +>

+> +> +> +> +> > [Github 地址](https://github.com/react-native-oh-library/react-native-image-crop-picker) +> +> ## 安装与使用 +> +> 请到三方库的 Releases 发布地址查看配套的版本信息：[@react-native-oh-tpl/react-native-image-crop-picker Releases ](https://github.com/react-native-oh-library/react-native-image-crop-picker/releases)，并下载适用版本的 tgz 包。 +> +> 进入到工程目录并输入以下命令： +> +> **** +> +> [!tip] #处替换为tgz包的路径 +> +> #### **npm** +> +> ```bash +> npm install @react-native-oh-tpl/react-native-image-crop-picker@file:# +> ``` +> +> #### **yarn** +> +> ```bash +> yarn add @react-native-oh-tpl/react-native-image-crop-picker@file:# +> ``` +> +> 下面的代码展示了这个库的基本使用场景： +> +> > [!TIP] 使用时 import 的库名不变。 +> +> ```js +> import { ImagePicker } from 'react-native-image-crop-picker'; +> +> // Image +> ImagePicker.openPicker({ +> width: 300, +> height: 400, +> cropping: true +> }).then(image => { +> console.log(image); +> }); +> +> // Video +> ImagePicker.openCamera({ +> mediaType: 'video', +> }).then(image => { +> console.log(image); +> }); +> +> // Crop picture +> ImagePicker.openCropper({ +> path: 'my-file-path.jpg' +> }).then(image => { +> console.log(image); +> }); +> +> // Clean +> ImagePicker.clean().then(() => { +> console.log('removed all tmp images from tmp directory'); +> }).catch(e => { +> alert(e); +> }); +> +> ``` +> +> ## Link +> +> 目前鸿蒙暂不支持 AutoLink，所以 Link 步骤需要手动配置。 +> +> 首先需要使用 DevEco Studio 打开项目里的鸿蒙工程 harmony +> +> ``` +> 在工程根目录的 oh-package.json 添加 overrides字段 +> { +> ... +> "overrides": { +> "@rnoh/react-native-openharmony" : "./react_native_openharmony" +> } +> } +> ``` +> +> +> +> +> ## 配置Entry +> +> 1.entryability下创建ImageEditAbility.ets +> +> ``` +> import UIAbility from '@ohos.app.ability.UIAbility' +> import window from '@ohos.window' +> import abilityAccessCtrl, { Permissions } from '@ohos.abilityAccessCtrl'; +> import AbilityConstant from '@ohos.app.ability.AbilityConstant' +> import Want from '@ohos.app.ability.Want' +> +> +> const TAG = 'ImageEditAbility'; +> +> let names = []; +> +> let filePath : string; +> +> export default class ImageEditAbility extends UIAbility { +> +> +> onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { +> filePath = want.parameters?.imageUri as string; +> } +> +> onWindowStageCreate(windowStage: window.WindowStage) { +> this.setWindowOrientation(windowStage, window.Orientation.PORTRAIT) +> const permissions: Array = [ +> 'ohos.permission.READ_MEDIA', +> 'ohos.permission.WRITE_MEDIA', +> 'ohos.permission.MEDIA_LOCATION', +> ]; +> const atManager = abilityAccessCtrl.createAtManager(); +> atManager.requestPermissionsFromUser(this.context, permissions, (err, data) => { +> if (!err) { +> console.info(TAG,'Failed to requestPermission. Cause: %{public}s', +> JSON.stringify(err) ?? '') +> } else { +> console.info(TAG,'Succeeded in requestPermission') +> } +> let para:Record = { 'filePath': filePath}; +> let storage: LocalStorage = new LocalStorage(para); +> windowStage.loadContent('pages/ImageEdit', storage, (err, data) => { +> if (err.code) { +> console.info(TAG,'Failed to load the content. Cause: %{public}s', +> JSON.stringify(err) ?? '') +> return; +> } +> console.info(TAG,'Succeeded in loading the content') +> }); +> }); +> +> try { +> windowStage.getMainWindowSync().setWindowLayoutFullScreen(true,(err)=>{ +> if (err.code) { +> console.error('Failed to enable the full-screen mode. Cause: ' + JSON.stringify(err)); +> return; +> } +> console.info('Succeeded in enabling the full-screen mode.'); +> }) +> windowStage.getMainWindowSync().setWindowSystemBarEnable(names, (err) => { +> if (err.code) { +> console.error('Failed to set the system bar to be invisible. Cause: ' + JSON.stringify(err)); +> return; +> } +> console.info('Succeeded in setting the system bar to be invisible.'); +> }); +> } catch (exception) { +> console.error('Failed to set the system bar to be invisible. Cause: ' + JSON.stringify(exception)); +> } +> +> } +> +> setWindowOrientation(stage: window.WindowStage, orientation: window.Orientation): void { +> console.info(TAG,"into setWindowOrientation :") +> if (!stage || !orientation) { +> return; +> } +> stage.getMainWindow().then(windowInstance => { +> windowInstance.setPreferredOrientation(orientation); +> }) +> } +> } +> ``` +> +> 2.module.json5注册 ImageEditAbility 增加 requestPermissions +> +> ``` +> { +> "name": "ImageEditAbility", +> "srcEntrance": "./ets/entryability/ImageEditAbility.ets", +> "description": "$string:EntryAbility_desc", +> "icon": "$media:icon", +> "startWindowIcon": "$media:startIcon", +> "startWindowBackground": "$color:start_window_background", +> "visible": true, +> +> } +> +> "requestPermissions": [ +> { +> "name": "ohos.permission.MEDIA_LOCATION", +> "reason": "$string:reason", +> "usedScene": { +> "abilities": [ +> "ImageEditAbility" +> ], +> "when": "inuse" +> } +> }, +> { +> "name": "ohos.permission.READ_MEDIA", +> "reason": "$string:reason", +> "usedScene": { +> "abilities": [ +> "ImageEditAbility" +> ], +> "when": "inuse" +> } +> }, +> { +> "name": "ohos.permission.WRITE_MEDIA", +> "reason": "$string:reason", +> "usedScene": { +> "abilities": [ +> "ImageEditAbility" +> ], +> "when": "inuse" +> } +> } +> ] +> ``` +> +> 3.page下创建ImageEdit.ets +> +> ``` +> import { ImageEditInfo } from 'rnoh-image-crop-picker'; +> +> let storage = LocalStorage.GetShared() +> +> @Entry(storage) +> @Component +> struct ImageEdit { +> +> @LocalStorageLink('filePath') filePath: string = ''; +> +> build() { +> Row(){ +> Column(){ +> ImageEditInfo({filePath: this.filePath}); +> } +> .width('100%') +> } +> .height('100%') +> } +> } +> ``` +> +> 4.main_pages.json添加配置 +> +> ``` +> { +> "src": [ +> "pages/Index", +> "pages/ImageEdit" +> ] +> } +> ``` +> +> +> +> ### 引入原生端代码 +> +> 目前有两种方法： +> +> 1. 通过 har 包引入。 +> 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-image-crop-picker": "file:../../node_modules/@react-native-oh-tpl/react-native-image-crop-picker/harmony/react-native-image-crop-picker.har" +> } +> ``` +> +> 点击右上角的 `sync` 按钮 +> +> 或者在终端执行： +> +> ```bash +> cd entry +> ohpm install +> ``` +> +> 方法二：直接链接源码 +> +> > [!TIP] 源码位于三方库安装路径的 `harmony` 文件夹下。 +> +> 打开 `entry/oh-package.json5`，添加以下依赖 +> +> ```json +> "dependencies": { +> "@rnoh/react-native-openharmony": "file:../react_native_openharmony", +> "@react-native-oh-tpl/react-native-image-crop-picker": "file:../image_crop_picker" +> } +> ``` +> +> 打开终端，执行： +> +> ```bash +> cd entry +> ohpm install --no-link +> ``` +> +> +> +> ### 在 ArkTs 侧引入 ImageCropPickerPackage +> +> 打开 `entry/src/main/ets/RNPackagesFactory.ts`，添加： +> +> ```diff +> ... +> + import {ImageCropPickerPackage} from "@react-native-oh-tpl/image-crop-picker/ts"; +> +> export function createRNPackages(ctx: RNPackageContext): RNPackage[] { +> return [ +> new SamplePackage(ctx), +> + new ImageCropPickerPackage(ctx) +> ]; +> } +> ``` +> +> ### 运行 +> +> 点击右上角的 `sync` 按钮 +> +> 或者在终端执行： +> +> ```bash +> cd entry +> ohpm install +> ``` +> +> 然后编译、运行即可。 +> +> ## 约束与限制 +> +> ### 兼容性 +> +> 本文档内容基于以下版本验证通过： +> +> RNOH：0.72.20; SDK：HarmonyOS-NEXT-DB1; IDE：DevEco Studio 5.0.3.200; ROM：3.0.0.21; +> +> 请到三方库相应的 Releases 发布地址查看 Release 配套的版本信息：[Releases](https://github.com/react-native-oh-library/react-native-image-crop-picker/releases) +> +> ## 属性 +> +> [!tip] "HarmonyOS Support"列为 yes 表示 HarmonyOS 平台支持该属性；no 则表示不支持；partially 表示部分支持。使用方法跨平台一致，效果对标 iOS 或 Android 的效果。 +> +> | Name | Description | Platform | HarmonyOS Support | +> | ----------- | ------------------------------------------------------------ | ----------- | ----------------- | +> | openPicker | Call single image picker with cropping | ios/Android | yes | +> | clean | Module is creating tmp images which are going to be cleaned up automatically somewhere in the future. If you want to force cleanup, you can use `clean` to clean all tmp files, or `cleanSingle(path)` to clean single tmp file. | ios/Android | yes | +> | openCropper | Crop image and rotate, | ios/Android | yes | +> | cleanSingle | Delete a single cache file | ios/Android | yes | +> | openCamera | Select from camera | ios/Android | yes | +> +> cropData +> +> | 名称 | 类型 | 说明 | 是否必填 | 原库平台 | 鸿蒙支持 | +> | ----------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | -------- | -------- | -------- | +> | cropping | bool (default false) | Enable or disable cropping | no | All | yes | +> | `width` | number | Width of result image when used with `cropping` option | no | All | yes | +> | height | number | Height of result image when used with `cropping` option | no | All | yes | +> | multiple | bool (default false) | Enable or disable multiple image selection | no | All | yes | +> | writeTempFile (ios only) | bool (default true) | When set to false, does not write temporary files for the selected images. This is useful to improve performance when you are retrieving file contents with the `includeBase64` option and don't need to read files from disk. | no | ios | yes | +> | includeBase64 | bool (default false) | When set to true, the image file content will be available as a base64-encoded string in the `data` property. Hint: To use this string as an image source, use it like: `` | no | All | yes | +> | includeExif | bool (default false) | Include image exif data in the response | no | All | yes | +> | avoidEmptySpaceAroundImage (ios only) | bool (default true) | When set to true, the image will always fill the mask space. | no | ios | no | +> | cropperActiveWidgetColor (android only) | string (default `"#424242"`) | When cropping image, determines ActiveWidget color. | no | android | no | +> | cropperStatusBarColor (android only) | string (default `#424242`) | When cropping image, determines the color of StatusBar. | no | android | no | +> | cropperToolbarColor (android only) | string (default `#424242`) | When cropping image, determines the color of Toolbar. | no | android | no | +> | cropperToolbarWidgetColor (android only) | string (default `darker orange`) | When cropping image, determines the color of Toolbar text and buttons. | no | android | no | +> | freeStyleCropEnabled | bool (default false) | Enables user to apply custom rectangle area for cropping | no | All | yes | +> | cropperToolbarTitle | string (default `Edit Photo`) | When cropping image, determines the title of Toolbar. | no | All | yes | +> | cropperCircleOverlay | bool (default false) | Enable or disable circular cropping mask. | no | All | yes | +> | disableCropperColorSetters (android only) | bool (default false) | When cropping image, disables the color setters for cropping library. | no | All | no | +> | minFiles (ios only) | number (default 1) | Min number of files to select when using `multiple` option | no | ios | yes | +> | maxFiles (ios only) | number (default 5) | Max number of files to select when using `multiple` option | no | ios | yes | +> | waitAnimationEnd (ios only) | bool (default true) | Promise will resolve/reject once ViewController `completion` block is called | no | ios | no | +> | smartAlbums (ios only) | array ([supported values](https://github.com/ivpusic/react-native-image-crop-picker/blob/master/README.md#smart-album-types-ios)) (default ['UserLibrary', 'PhotoStream', 'Panoramas', 'Videos', 'Bursts']) | List of smart albums to choose from | no | ios | no | +> | useFrontCamera | bool (default false) | Whether to default to the front/'selfie' camera when opened. Please note that not all Android devices handle this parameter, see [issue #1058](https://github.com/ivpusic/react-native-image-crop-picker/issues/1058) | no | All | yes | +> | compressVideoPreset (ios only) | string (default MediumQuality) | Choose which preset will be used for video compression | no | ios | no | +> | compressImageMaxWidth | number (default none) | Compress image with maximum width | no | All | yes | +> | compressImageMaxHeight | number (default none) | Compress image with maximum height | no | All | yes | +> | compressImageQuality | number (default 1 (Android)/0.8 (iOS)) | Compress image with quality (from 0 to 1, where 1 is best quality). On iOS, values larger than 0.8 don't produce a noticeable quality increase in most images, while a value of 0.8 will reduce the file size by about half or less compared to a value of 1. | no | All | yes | +> | loadingLabelText (ios only) | string (default "Processing assets...") | Text displayed while photo is loading in picker | no | ios | yes | +> | mediaType | string (default any) | Accepted mediaType for image selection, can be one of: 'photo', 'video', or 'any' | no | All | yes | +> | showsSelectedCount (ios only) | bool (default true) | Whether to show the number of selected assets | no | ios | yes | +> | sortOrder (ios only) | string (default 'none', supported values: 'asc', 'desc', 'none') | Applies a sort order on the creation date on how media is displayed within the albums/detail photo views when opening the image picker | no | ios | no | +> | forceJpg (ios only) | bool (default false) | Whether to convert photos to JPG. This will also convert any Live Photo into its JPG representation | no | ios | yes | +> | showCropGuidelines (android only) | bool (default true) | Whether to show the 3x3 grid on top of the image during cropping | no | android | yes | +> | showCropFrame (android only) | bool (default true) | Whether to show crop frame during cropping | no | android | yes | +> | hideBottomControls (android only) | bool (default false) | Whether to display bottom controls | no | android | no | +> | enableRotationGesture (android only) | bool (default false) | Whether to enable rotating the image by hand gesture | no | android | yes | +> | cropperChooseText (ios only) | string (default choose) | Choose button text | no | ios | yes | +> | cropperChooseColor (ios only) | string (default `#FFCC00`) | HEX format color for the Choose button. [Default color is controlled by TOCropViewController](https://github.com/TimOliver/TOCropViewController/blob/a942414508012b13102f776eb65dac655f31cabb/Objective-C/TOCropViewController/Views/TOCropToolbar.m#L444). | no | ios | yes | +> | cropperCancelText (ios only) | string (default Cancel) | Cancel button text | no | ios | yes | +> | cropperCancelColor (ios only) | string (default tint `iOS` color ) | HEX format color for the Cancel button. Default value is the default tint iOS color [controlled by TOCropViewController](https://github.com/TimOliver/TOCropViewController/blob/a942414508012b13102f776eb65dac655f31cabb/Objective-C/TOCropViewController/Views/TOCropToolbar.m#L433) | no | ios | yes | +> | cropperRotateButtonsHidden (ios only) | bool (default false) | Enable or disable cropper rotate buttons | no | ios | yes | +> +> ## 遗留问题 +> +> - [ ] 图像将始终填充蒙版空间在harmony框架侧不支持使用 [#I9OKND](https://gitee.com/wuyasmile/usage-docs/issues/I9OKND) +> - [ ] Android Demo中 ActiveWidget 改变颜色 [#I9OKON](https://gitee.com/wuyasmile/usage-docs/issues/I9OKON) +> - [ ] Android Demo中 改变状态栏颜色 [#I9OKPX](https://gitee.com/wuyasmile/usage-docs/issues/I9OKPX) +> - [ ] Android Demo中 改变工具栏颜色 [#I9OKR6](https://gitee.com/wuyasmile/usage-docs/issues/I9OKR6) +> - [ ] 裁剪图像时，禁用裁剪库的颜色设置器 [#I9OKRZ](https://gitee.com/wuyasmile/usage-docs/issues/I9OKRZ) +> - [ ] 裁剪图像时，确定工具栏文本和按钮的颜色 [#I9OKSR](https://gitee.com/wuyasmile/usage-docs/issues/I9OKSR) +> - [ ] 调用ViewController“completion”块，Promise将解析/拒绝，鸿蒙不支持 [#I9OKTJ](https://gitee.com/wuyasmile/usage-docs/issues/I9OKTJ) +> - [ ] Ios支持智能相册列表 [#I9OKU2](https://gitee.com/wuyasmile/usage-docs/issues/I9OKU2) +> - [ ] Ios视频压缩的预设 [#I9OKUD](https://gitee.com/wuyasmile/usage-docs/issues/I9OKUD) +> - [ ] Ios智能相册排序 [#I9OKVG](https://gitee.com/wuyasmile/usage-docs/issues/I9OKVG) +> - [ ] Android Demo 设置是否显示底部控件 [#I9OKVU](https://gitee.com/wuyasmile/usage-docs/issues/I9OKVU) +> +> ## 其他 +> +> ## 开源协议 +> +> 本项目基于 [The MIT License (MIT)](https://github.com/ivpusic/react-native-image-crop-picker/blob/master/LICENSE) ，请自由地享受和参与开源。