@ohmi/react-native-image-picker

v7.0.3-0.2.3

Published

5 months ago

A React Native module that allows you to use native UI to select media from the device library or directly from the camera

0High
0Medium
0Low

react-native react-native-image-picker react native image picker harmony

模板版本：v0.3.0

本项目基于 [email protected] 开发。

1. 安装与使用

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

npm

npm install @ohmi/react-native-image-picker

yarn

yarn add @ohmi/react-native-image-picker

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

import React from 'react';
import { View, Text } from 'react-native';
import ImagePicker from 'react-native-image-picker';

const App = () => {
  const [urlInfo, setUrlInfo] = React.useState<string>();
  return (
    <View style={{ flex: 1, marginTop: 100 }}>
      <View style={{
        width: 160,
        height: 36,
        backgroundColor: 'hsl(190,50%,70%)',
        paddingHorizontal: 16,
        paddingVertical: 8,
        borderRadius: 8
      }} onTouchEnd={() => {
        ImagePicker.launchImageLibrary({ mediaType: 'photo', selectionLimit: 1 }, (data) => {
          if (data.assets?.length) {
            setUrlInfo(JSON.stringify(data.assets))
          }
        })
      }}>
        <Text style={{ width: '100%', height: '100%', fontWeight: 'bold', textAlign: 'center' }}>选择</Text>
      </View>
      <Text>{urlInfo}</Text>
    </View>
  );
};

export default App;

2. Manual Link

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

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

2.1. Overrides RN SDK

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

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

{
  "overrides": {
    "@rnoh/react-native-openharmony": "^0.72.38" // ohpm 在线版本
    // "@rnoh/react-native-openharmony" : "./react_native_openharmony.har" // 指向本地 har 包的路径
    // "@rnoh/react-native-openharmony" : "./react_native_openharmony" // 指向源码路径
  }
}

2.2. 引入原生端代码

目前有两种方法：

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

方法一：通过 har 包引入（推荐）

[!TIP] har 包位于三方库安装路径的 harmony 文件夹下。

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

"dependencies": {
    "@ohmi/react-native-image-picker": "file:../../node_modules/@ohmi/react-native-image-picker/harmony/image_picker.har",
  }

点击右上角的 sync 按钮

或者在终端执行：

cd entry
ohpm install

方法二：直接链接源码

[!TIP] 如需使用直接链接源码，请参考直接链接源码说明

2.3. 配置 CMakeLists 和引入 RNImagePickerPackage

打开 entry/src/main/cpp/CMakeLists.txt，添加：

project(rnapp)
cmake_minimum_required(VERSION 3.4.1)
set(CMAKE_SKIP_BUILD_RPATH TRUE)
set(RNOH_APP_DIR "${CMAKE_CURRENT_SOURCE_DIR}")
set(NODE_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/../../../../../node_modules")
+ set(OH_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/../../../oh_modules")
set(RNOH_CPP_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../../../../../react-native-harmony/harmony/cpp")
set(LOG_VERBOSITY_LEVEL 1)
set(CMAKE_ASM_FLAGS "-Wno-error=unused-command-line-argument -Qunused-arguments")
set(CMAKE_CXX_FLAGS "-fstack-protector-strong -Wl,-z,relro,-z,now,-z,noexecstack -s -fPIE -pie")
set(WITH_HITRACE_SYSTRACE 1) # for other CMakeLists.txt files to use
add_compile_definitions(WITH_HITRACE_SYSTRACE)

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

# RNOH_BEGIN: manual_package_linking_1
add_subdirectory("../../../../sample_package/src/main/cpp" ./sample-package)
+ add_subdirectory("${OH_MODULES}/@ohmi/react-native-image-picker/src/main/cpp" ./image_picker)
# RNOH_END: manual_package_linking_1

file(GLOB GENERATED_CPP_FILES "./generated/*.cpp")

add_library(rnoh_app SHARED
    ${GENERATED_CPP_FILES}
    "./PackageProvider.cpp"
    "${RNOH_CPP_DIR}/RNOHAppNapiBridge.cpp"
)
target_link_libraries(rnoh_app PUBLIC rnoh)

# RNOH_BEGIN: manual_package_linking_2
target_link_libraries(rnoh_app PUBLIC rnoh_sample_package)
+ target_link_libraries(rnoh_app PUBLIC rnoh_image_picker)
# RNOH_END: manual_package_linking_2

打开 entry/src/main/cpp/PackageProvider.cpp，添加：

#include "RNOH/PackageProvider.h"
#include "generated/RNOHGeneratedPackage.h"
#include "SamplePackage.h"
+ #include "RNImagePickerPackage.h"

using namespace rnoh;

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

2.4. 在 ArkTs 侧引入 RNImagePickerPackage

打开 entry/src/main/ets/RNPackagesFactory.ts，添加：

import type {RNPackageContext, RNPackage} from 'rnoh/ts';
import {SamplePackage} from 'rnoh-sample-package/ts';
+ import { RNImagePickerPackage } from '@ohmi/react-native-image-picker/ts';

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

2.5. 添加相机权限

打开 entry/src/main/module.json5，添加：

{
  "module": {
    ...
    "requestPermissions": [
    ...
      {
        "name": "ohos.permission.CAMERA",
        "reason": "$string:CAMERA",
        "usedScene": {
          "abilities": [
            "EntryAbility"
          ],
          "when": "always"
        }
      },
    ]
  }
}

2.6. 运行

点击右上角的 sync 按钮

或者在终端执行：

cd entry
ohpm install

然后编译、运行即可。

3. 约束与限制

3.1. 兼容性

要使用此库，需要使用正确的 React-Native 和 RNOH 版本。另外，还需要使用配套的 DevEco Studio 和手机 ROM。

请到三方库相应的 Releases 发布地址查看 Release 配套的版本信息：@ohmi/react-native-image-picker Releases

4. API

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

[!TIP] "HarmonyOS Support"列为 yes 表示 HarmonyOS 平台支持该属性；no 则表示不支持；partially 表示部分支持。使用方法跨平台一致，效果对标 iOS 或 Android 的效果。

| Name | Description | Type | Required | Platform | HarmonyOS Support | | ------------------ | ----------------------------------------- | -------- | -------- | ----------- | ----------------- | | showImagePicker | Both launchCamera and launchImageLibrary. | function | yes | iOS Android | yes | | launchCamera | Launch camera to take photo or video. | function | yes | iOS Android | yes | | launchImageLibrary | Launch gallery to pick image or video. | function | yes | iOS Android | yes |

属性

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

[!TIP] "HarmonyOS Support"列为 yes 表示 HarmonyOS 平台支持该属性；no 则表示不支持；partially 表示部分支持。使用方法跨平台一致，效果对标 iOS 或 Android 的效果。

ImagePickerOptions

| Name | Description | Type | Required | Platform | HarmonyOS Support | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------- | -------- | ----------- | ----------------- | | title | Specify null or empty string to remove the title | string | no | iOS Android | yes | | cancelButtonTitle | Specify null or empty string to remove this button | string | no | iOS Android | yes | | takePhotoButtonTitle | Specify null or empty string to remove this button | string | no | iOS Android | yes | | chooseFromLibraryButtonTitle | Specify null or empty string to remove this button | string | no | iOS Android | yes | | chooseWhichLibraryTitle | Specify null or empty string to use default Android title. Is shown when user has multiple apps that can open library. | string | no | Android | no | | customButtons | An array containing objects with the name and title of buttons | ImagePickerCustomButtonOptions[] | no | iOS Android | yes | | cameraType | 'front' or 'back' | 'front' | 'back' | no | iOS | yes | | mediaType | 'photo', 'video', or 'mixed' on iOS, 'photo' or 'video' on Android | 'photo' | 'video' | 'mixed' | yes | iOS Android | yes | | maxWidth | Photos only | number | no | iOS Android | yes | | maxHeight | Photos only | number | no | iOS Android | yes | | quality | 0 to 1, photos only | number | no | iOS Android | no | | videoQuality | 'low', 'medium', or 'high' on iOS, 'low' or 'high' on Android | 'low' | 'medium' | 'high' | no | iOS Android | no | | durationLimit | Max video recording time, in seconds | number | no | iOS Android | no | | rotation | Photos only, 0 to 360 degrees of rotation | number | no | Android | no | | allowsEditing | bool - enables built-in iOS functionality to resize the image after selection | boolean | no | iOS | yes | | noData | If true, disables the base64 data field from being generated (greatly improves performance on large photos) | boolean | no | iOS Android | yes | | storageOptions | If this key is provided, the image will be saved in your app's Documents directory on iOS, or your app's Pictures directory on Android (rather than a temporary directory) | ImagePickerStorageOptions | no | iOS Android | no | | permissionDenied | Options when the permission is denied | ImagePickerPermissionDeniedOptions | no | Android | yes | | tintColor | Application color scheme | string | no | iOS | no |

launchCamera Options

| Name | Description | Type | Required | Platform | HarmonyOS Support | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------- | -------- | ----------- | ----------------- | | cameraType | 'front' or 'back' | 'front' | 'back' | no | iOS | yes | | mediaType | 'photo', 'video', or 'mixed' on iOS, 'photo' or 'video' on Android | 'photo' | 'video' | 'mixed' | yes | iOS Android | yes | | maxWidth | Photos only | number | no | iOS Android | yes | | maxHeight | Photos only | number | no | iOS Android | yes | | quality | 0 to 1, photos only | number | no | iOS Android | no | | videoQuality | 'low', 'medium', or 'high' on iOS, 'low' or 'high' on Android | 'low' | 'medium' | 'high' | no | iOS Android | no | | durationLimit | Max video recording time, in seconds | number | no | iOS Android | no | | rotation | Photos only, 0 to 360 degrees of rotation | number | no | Android | no | | noData | If true, disables the base64 data field from being generated (greatly improves performance on large photos) | boolean | no | iOS Android | yes | | storageOptions | If this key is provided, the image will be saved in your app's Documents directory on iOS, or your app's Pictures directory on Android (rather than a temporary directory) | ImagePickerStorageOptions | no | iOS Android | no | | permissionDenied | Options when the permission is denied | ImagePickerPermissionDeniedOptions | no | Android | yes |

launchImageLibrary Options

| Name | Description | Type | Required | Platform | HarmonyOS Support | | ---------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------- | -------- | ----------- | ----------------- | | mediaType | 'photo', 'video', or 'mixed' on iOS, 'photo' or 'video' on Android | 'photo' | 'video' | 'mixed' | yes | iOS Android | yes | | maxWidth | Photos only | number | no | iOS Android | yes | | maxHeight | Photos only | number | no | iOS Android | yes | | quality | 0 to 1, photos only | number | no | iOS Android | no | | videoQuality | 'low', 'medium', or 'high' on iOS, 'low' or 'high' on Android | 'low' | 'medium' | 'high' | no | iOS Android | no | | rotation | Photos only, 0 to 360 degrees of rotation | number | no | Android | no | | allowsEditing | bool - enables built-in iOS functionality to resize the image after selection | boolean | no | iOS | yes | | noData | If true, disables the base64 data field from being generated (greatly improves performance on large photos) | boolean | no | iOS Android | yes | | permissionDenied | Options when the permission is denied | ImagePickerPermissionDeniedOptions | no | Android | yes | | tintColor | Application color scheme | string | no | iOS | no |

ImagePickerCustomButtonOptions

| Name | Description | Type | Required | Platform | HarmonyOS Support | | ----- | ------------------- | ------ | -------- | ----------- | ----------------- | | name | Custom button name | string | no | iOS Android | yes | | title | Custom button title | string | no | iOS Android | yes |

ImagePickerStorageOptions

| Name | Description | Type | Required | Platform | HarmonyOS Support | | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | -------- | ----------- | ----------------- | | skipBackup | If true, the photo will NOT be backed up to iCloud | boolean | no | iOS | no | | path | If set, will save the image at Documents/[path]/ rather than the root Documents for iOS, and Pictures/[path]/ on Android. | string | no | iOS Android | no | | cameraRoll | If true, the cropped photo will be saved to the iOS Camera Roll or Android DCIM folder. | boolean | no | iOS Android | no | | waitUntilSaved | If true, will delay the response callback until after the photo/video was saved to the Camera Roll. If the photo or video was just taken, then the file name and timestamp fields are only provided in the response object when this AND cameraRoll are both true. | boolean | no | iOS | no |

ImagePickerPermissionDeniedOptions

| Name | Description | Type | Required | Platform | HarmonyOS Support | | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------ | -------- | -------- | ----------------- | | title | Title of explaining permissions dialog. By default Permission denied. | string | no | Android | yes | | text | Message of explaining permissions dialog. By default To be able to take pictures with your camera and choose images from your library.. | string | no | Android | yes | | reTryTitle | Title of re-try button. By default re-try | string | no | Android | yes | | okTitle | Title of ok button. By default I'm sure | string | no | Android | yes |

ImagePickerResponse

| Name | Description | Type | Required | Platform | HarmonyOS Support | | ---------------- | ---------------------------------------------------------------------- | ------- | -------- | ----------- | ----------------- | | didCancel | Informs you if the user cancelled the process | boolean | no | iOS Android | yes | | error | Contains an error message, if there is one | string | no | iOS Android | yes | | customButton | If the user tapped one of your custom buttons, contains the name of it | string | no | iOS Android | yes | | data | The base64 encoded image data (photos only) | string | no | iOS Android | yes | | uri | The uri to the local file asset on the device (photo or video) | string | no | iOS Android | yes | | origURL | The URL of the original asset in photo library, if it exists | string | no | iOS | yes | | isVertical | Will be true if the image is vertically oriented | boolean | no | iOS Android | yes | | width | Image dimensions (photos only) | number | no | iOS Android | yes | | height | Image dimensions (photos only) | number | no | iOS Android | yes | | fileSize | The file size (photos only) | number | no | iOS Android | yes | | type | The file type (photos only) | string | no | iOS Android | yes | | fileName | The file name, if available | string | no | iOS Android | yes | | path | The file path | string | no | iOS Android | yes | | latitude | Latitude metadata, if available | number | no | iOS Android | no | | longitude | Longitude metadata, if available | number | no | iOS Android | no | | timestamp | Timestamp metadata, if available, in ISO8601 UTC format | string | no | iOS Android | yes | | originalRotation | Rotation degrees (photos only) | number | no | Android | yes |