react-native-multi-capture

基于 VisionCamera 5 的 React Native 连续拍照 / 录像组件，适合巡检、工单、取证、附件采集等需要“一次拍摄多个文件”的场景。

组件内置相机权限页、系统相册选择、最新照片缩略图、照片 / 视频预览、数量限制、录像状态和最终批量确认；宿主只需控制显示状态并处理最终文件。

安装 · 平台配置 · 快速开始 · 核心 Props · 高级用法 · 兼容性

功能概览

连续拍照，快速点击时自动预占名额并串行调用原生相机。
支持 photo、video、mixed 三种媒体模式。
内置系统相册多选，自动遵守剩余文件数量和媒体类型。
内置照片 / 视频全屏预览，可左右滑动并直接完成提交；缩略图列表支持删除。
相册按钮显示系统相册最新照片；没有读取权限时回退到默认图标。
完整的相机 / 麦克风权限请求、永久拒绝和无可用设备页面。
前后镜头切换使用原生 BlurView，在新相机会话启动后平滑淡出。
支持点按对焦、原生缩放手势、闪光灯、录像时长与文件大小限制。
内置中文和英文文案，支持主题、文案、缩略图与业务处理流程覆盖。
提供页面组件和受控全屏 Modal 两种使用方式。

真机演示

界面截图	动态演示（点击打开 MP4）

GIF 可直接在 GitHub README 中预览；点击动态演示可打开约 21 秒的 MP4。

安装

yarn add react-native-multi-capture \
  @react-native-camera-roll/camera-roll \
  @react-native-community/blur \
  react-native-image-picker \
  react-native-vision-camera \
  react-native-nitro-modules \
  react-native-nitro-image \
  react-native-video@7.0.0-beta.10

使用 npm：

npm install react-native-multi-capture \
  @react-native-camera-roll/camera-roll \
  @react-native-community/blur \
  react-native-image-picker \
  react-native-vision-camera \
  react-native-nitro-modules \
  react-native-nitro-image \
  react-native-video@7.0.0-beta.10

iOS 安装原生依赖：

npx pod-install

react-native-video v7 当前仍为 beta，但它与 VisionCamera 5 使用的 Media3 版本兼容。修改任何原生依赖或权限后都需要重新编译 App，Metro 热更新无法完成原生安装。

平台配置

iOS

在宿主应用的 Info.plist 中按需添加：

<key>NSCameraUsageDescription</key>
<string>用于拍摄现场照片和视频</string>
<key>NSMicrophoneUsageDescription</key>
<string>用于录制带声音的视频</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>用于从相册选择照片和视频</string>

NSCameraUsageDescription：必需。
NSMicrophoneUsageDescription：仅在 enableAudio 为 true 时需要。
NSPhotoLibraryUsageDescription：用于相册选择和读取最新照片缩略图。

Android

在 android/app/src/main/AndroidManifest.xml 中按需添加：

<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
<uses-permission
  android:name="android.permission.READ_EXTERNAL_STORAGE"
  android:maxSdkVersion="32" />

CAMERA：必需。
RECORD_AUDIO：仅在 enableAudio 为 true 时需要。
图片读取权限只用于显示最新照片缩略图。用户拒绝后会显示默认图标，不影响系统 Photo Picker。
Android minSdkVersion < 30 且项目没有 androidx.activity:activity:1.9+ 时，需要按 react-native-image-picker 文档启用 Photo Picker backport。

若启用 enableHaptics 且没有传入 onHapticFeedback，还需声明：

<uses-permission android:name="android.permission.VIBRATE" />

快速开始

推荐使用受控的全屏 MultiCaptureModal：

import { useState } from 'react';
import { Button } from 'react-native';
import {
  MultiCaptureModal,
  type CaptureAsset,
} from 'react-native-multi-capture';

export function WorkOrderCamera() {
  const [visible, setVisible] = useState(false);

  return (
    <>
      <Button title="拍摄附件" onPress={() => setVisible(true)} />

      <MultiCaptureModal
        visible={visible}
        mediaType="mixed"
        maxAssets={12}
        maxVideoDuration={30}
        onDone={async (assets: readonly CaptureAsset[]) => {
          await uploadWorkOrderFiles(assets);
          setVisible(false);
        }}
        onCancel={() => setVisible(false)}
      />
    </>
  );
}

onDone 可以返回 Promise。提交期间组件会锁定冲突操作，避免重复提交。 enableAudio 默认为 false；需要录制声音时显式传入 enableAudio。

内置交互

相册选择与预览

相册入口默认开启，不需要传 openLibrary：

根据 mediaType 和剩余数量配置系统选择器。
选择结束后自动进入内置全屏预览。
照片使用 contain 模式显示；视频自动播放并提供系统控制条。
可以左右滑动查看本次会话的全部文件。
预览顶部可直接完成提交。
摄像头无权限或设备没有可用相机时，仍可从相册选择并完成提交。

传入 enableLibraryPicker={false} 可隐藏相册入口；传入 enablePreview={false} 可关闭内置预览。宿主已有媒体查看器时，可以使用 onPreviewAsset 接管预览。

权限页面

autoRequestPermissions 默认为 true。首次进入会请求必要权限；永久拒绝后显示 “去开启权限”并打开系统设置。开启录音时，麦克风权限也会成为必要权限。

防误退

通过 onRequestClose 接入宿主自己的确认弹窗：

<MultiCaptureModal
  visible={visible}
  onRequestClose={async ({ assets, isBusy }) => {
    if (isBusy) return false;
    if (assets.length === 0) return true;
    return showDiscardConfirm();
  }}
  onDone={handleDone}
  onCancel={() => setVisible(false)}
/>

没有提供 onRequestClose 时，空闲状态允许关闭，拍摄或处理中拒绝关闭。

中文、英文与主题

界面默认使用中文。切换内置英文：

<MultiCaptureModal locale="en" {...props} />

覆盖部分文案或颜色：

<MultiCaptureModal
  strings={{ done: '提交' }}
  theme={{ accentColor: '#4F8CFF' }}
  {...props}
/>

也可以导入 zhCNStrings、enStrings、multiCaptureLocales 和 defaultTheme 构建自己的配置。

核心 Props

Prop	类型	默认值	说明
`maxAssets`	`number`	`10`	已完成文件与在途任务的共同上限
`mediaType`	`'photo' \| 'video' \| 'mixed'`	`'photo'`	可用媒体类型
`initialMode`	`'photo' \| 'video'`	`'photo'`	mixed 模式初始页签；video 模式固定为 video
`initialCameraPosition`	`'front' \| 'back'`	`'back'`	初始摄像头
`initialAssets`	`CaptureAssetInput[]`	`[]`	会话初始文件
`enableAudio`	`boolean`	`false`	录像是否录音
`enablePreview`	`boolean`	`true`	内置照片 / 视频预览
`enableLibraryPicker`	`boolean`	`true`	系统相册入口与最新照片缩略图
`enableHaptics`	`boolean`	`false`	使用 RN Vibration 提供快门触觉反馈
`maxVideoDuration`	`number`	-	单段录像最大秒数
`maxVideoFileSize`	`number`	-	单段录像最大字节数
`openLibrary`	`function`	-	覆盖内置系统选择器
`processAsset`	`function`	-	串行处理捕获或选择的文件
`onPreviewAsset`	`function`	-	使用宿主预览器代替内置预览
`onAssetsChange`	`function`	-	文件增加或删除后的回调
`onDone`	`function`	必填	完成回调，可异步
`onCancel`	`function`	必填	关闭回调
`onRequestClose`	`function`	-	防误退判定
`onError`	`function`	-	结构化错误回调
`locale`	`'zh-CN' \| 'en'`	`'zh-CN'`	内置语言
`strings`	`Partial<MultiCaptureStrings>`	-	文案覆盖
`theme`	`Partial<MultiCaptureTheme>`	深色	颜色覆盖

完整接口见中文 API 参考。

返回数据

interface CaptureAsset {
  id: string;
  uri: string;
  path: string;
  type: 'photo' | 'video';
  fileName: string;
  mimeType: string;
  width?: number;
  height?: number;
  duration?: number;
  size?: number;
  metadata?: Readonly<Record<string, unknown>>;
}

VisionCamera 捕获结果位于临时目录。库不会自动移动或删除这些文件；上传后的持久化、移动和清理策略由宿主负责。视频 duration 是组件记录的近似秒数，如需精确元数据，可在 processAsset 中补齐。

高级用法

压缩、水印或上传前处理

processAsset 会在文件加入列表前执行，并与拍照任务串行：

<MultiCaptureModal
  processAsset={async (asset) => {
    if (asset.type !== 'photo') return asset;

    const compressed = await compressPhoto(asset.path);
    return {
      ...asset,
      path: compressed.path,
      uri: `file://${compressed.path}`,
      size: compressed.size,
    };
  }}
  {...props}
/>

覆盖系统相册选择器

宿主已有定制相册时，可以通过 openLibrary 返回统一的 CaptureAssetInput：

<MultiCaptureModal
  openLibrary={async ({ remaining, mediaType }) => {
    const picked = await yourPicker({ limit: remaining, mediaType });
    if (picked.cancelled) return null;

    return picked.files.map((file) => ({
      uri: file.uri,
      type: file.kind === 'video' ? 'video' : 'photo',
      fileName: file.name,
      mimeType: file.mimeType,
      size: file.size,
      width: file.width,
      height: file.height,
    }));
  }}
  {...props}
/>

自定义结果同样经过媒体类型过滤、数量限制、processAsset 和预览流程。

直接作为页面使用

import { MultiCaptureCamera } from 'react-native-multi-capture';

export function CameraScreen() {
  return (
    <MultiCaptureCamera
      mediaType="photo"
      maxAssets={20}
      onDone={(assets) => navigation.navigate('Upload', { assets })}
      onCancel={() => navigation.goBack()}
    />
  );
}

并发与生命周期保证

快门按下时同步预占数量，连续点击不会突破 maxAssets。
拍照和 processAsset 共用串行 Promise 链，不会并发调用原生拍照。
onDone 等待照片处理链结束；录像、相册选择、镜头切换和提交会互斥。
每段视频使用新的 VisionCamera Recorder。
预览或 App 进入后台时暂停相机，返回前台后按条件恢复。
卸载时取消仍在录制的视频，并阻止异步结果继续更新状态。

兼容性

项目	支持范围
React Native	`>= 0.79`；example 使用 `0.86.2`
React	`>= 19`；example 使用 `19.2.3`
react-native-vision-camera	`>= 5.0 < 6`；example 使用 `5.2.0`
react-native-video	`>= 7.0.0-beta.10 < 8`
react-native-image-picker	`>= 8.2.1 < 9`
@react-native-camera-roll/camera-roll	`>= 7.10.2 < 8`
@react-native-community/blur	`>= 4.4 < 5`
iOS	`>= 15.1`
New Architecture	支持；example 使用 RN 默认新架构

VisionCamera 4 与 5 的 API 不兼容，本库仅支持 VisionCamera 5。VisionCamera 5 使用 Nitro 生成的 Swift / C++ bridge，请在宿主应用的 Xcode、NDK 和 React Native 组合中验证原生构建。

从旧 CountCamera 迁移

旧概念	新 API
`maxFiles`	`maxAssets`
`mediaType="any"`	`mediaType="mixed"`
`cameraMode="multiple"`	默认连续拍摄
`cameraMode="single"`	`maxAssets={1}`
`defaultCameraPos`	`initialCameraPosition`
`onSuccess`	`onDone`
ImageCropPicker	内置系统选择器；`openLibrary` 可覆盖
`compressPhoto`	`processAsset`
Reanimated / Gesture Handler	RN Animated / VisionCamera 原生手势
`openCountCamera()`	受控 `MultiCaptureModal`

旧组件的条码识别属于独立能力，本库不默认引入扫码依赖。

运行 example

corepack yarn install

# iOS
cd example
bundle install
bundle exec pod install --project-directory=ios
cd ..
corepack yarn example ios

# Android
corepack yarn example android

相机捕获必须在真机测试。模拟器只适合检查权限页和非相机 UI。

开发验证

corepack yarn lint
corepack yarn typecheck
corepack yarn test
corepack yarn prepare
corepack yarn pack:check

更多实现说明见架构文档。

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
.codebase-memory		.codebase-memory
.github		.github
.yarn/releases		.yarn/releases
assets/CountCamera		assets/CountCamera
docs		docs
example		example
scripts		scripts
src		src
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.nvmrc		.nvmrc
.watchmanconfig		.watchmanconfig
.yarnrc.yml		.yarnrc.yml
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.en.md		README.en.md
README.md		README.md
babel.config.js		babel.config.js
eslint.config.mjs		eslint.config.mjs
jest.config.js		jest.config.js
package.json		package.json
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json
turbo.json		turbo.json
yarn.lock		yarn.lock

Navigation Menu

Repository files navigation

react-native-multi-capture

功能概览

真机演示

安装

平台配置

iOS

Android

快速开始

内置交互

相册选择与预览

权限页面

防误退

中文、英文与主题

核心 Props

返回数据

高级用法

压缩、水印或上传前处理

覆盖系统相册选择器

直接作为页面使用

并发与生命周期保证

兼容性

从旧 CountCamera 迁移

运行 example

开发验证

License

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

react-native-multi-capture

功能概览

真机演示

安装

平台配置

iOS

Android

快速开始

内置交互

相册选择与预览

权限页面

防误退

中文、英文与主题

核心 Props

返回数据

高级用法

压缩、水印或上传前处理

覆盖系统相册选择器

直接作为页面使用

并发与生命周期保证

兼容性

从旧 CountCamera 迁移

运行 example

开发验证

License

About

Resources

Code of conduct

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages