# @capacitor-community/camera-preview 中文文档规范地址：https://npmcn.com/package/%40capacitor-community/camera-preview/ 版本：8\.0\.2 npm 元数据更新时间：2026-10-23T21:47:43.748Z 中文译文更新时间：2026-11-09T02:26:43.580Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。原始 npm 页面：https://www.npmjs.com/package/%40capacitor-community/camera-preview 原文对照：https://npmcn.com/package/%40capacitor-community/camera-preview/?lang=original 项目主页：https://github.com/capacitor-community/camera-preview#readme 源码仓库：https://github.com/capacitor-community/camera-preview ## 关键信息（来自 npm 元数据） - 包体积（解压后）：275 kB，36 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - Node.js 要求：\>=18\.0\.0 - 运行依赖：0 个 - peer 依赖：@capacitor/core \>=8\.0\.2 - 首次发布：2020-07-18T11:20:12.053Z - 最新版本发布：2026-09-25T12:34:26.005Z - 近 30 天下载量：124658（2026-10-09 至 2026-11-07，npm 官方下载统计） - 已发布版本数：37（近 12 个月 6 个） ## 中文简介相机预览 ## 安装 ```sh npm install @capacitor-community/camera-preview ``` 也可以使用：`pnpm add @capacitor-community/camera-preview`、`yarn add @capacitor-community/camera-preview`、`bun add @capacitor-community/camera-preview` ## README ![](https://user-images.githubusercontent.com/236501/85893648-1c92e880-b7a8-11ea-926d-95355b8175c7.png) ### 相机预览 **`@capacitor-community/camera-preview`** **第8条** 允许来自 Javascript 和 HTML 相机交互的相机插件 (基于cordova-plugin-camera-preview). 此插件的第8版需要Capacitor 8. 如果您使用Capacitor 7, 请使用 [7.0.5版翻译:](https://github.com/capacitor-community/camera-preview/releases/tag/v7.0.5) 如果您正在使用电容 6, 请使用 [6.0.1版本](https://github.com/capacitor-community/camera-preview/releases/tag/v6.0.1) 如果您使用电容 5, 请使用 [版本5](https://github.com/capacitor-community/camera-preview/releases/tag/v5.0.0) 如果您使用电容 4, 请使用 [版本 4](https://github.com/capacitor-community/camera-preview/releases/tag/v4.0.0) 如果您使用电容 3, 请使用 [版本3](https://github.com/capacitor-community/camera-preview/releases/tag/v3.1.2) 如果您使用电容2, 请使用 [版本 1](https://github.com/capacitor-community/camera-preview/releases/tag/v1.2.1) **公关很受欢迎.** \- 说吧 [@arielhernandezmusa (英语)](https://github.com/arielhernandezmusa) 财务报告和审定财务报表 [@pbowyer (英语)](https://github.com/pbowyer),当前维护者 # 安装 ``` yarn add @capacitor-community/camera-preview or npm install @capacitor-community/camera-preview ``` 然后运行 ``` npx cap sync ``` ## 额外的Android安装步骤 **重要** `camera-preview` 3+需要"Gradle 7."(3+),"Gradle 7. 如果你使用Gradle 4, 请使用 [版本 2](https://github.com/capacitor-community/camera-preview/tree/v2.1.0) 此插件. 打开 `android/app/src/main/AndroidManifest.xml` 及以上 `` 标记添加此行以请求 CAMERA 权限 : ```xml ``` 需要更多帮助咨询 [电容文件](https://capacitorjs.com/docs/android/configuration#configuring-androidmanifestxml)。。。 . ### 变量此插件将使用以下工程变量( 在您的应用程序中定义) `variables.gradle` 文件名 : - `androidxExifInterfaceVersion`页:1 `androidx.exifinterface:exifinterface` (默认 : `1.4.2`(中文(简体) ) ## 额外 iOS 安装步骤您需要添加两个权限到 `Info.plist`。跟踪 [电容文件](https://capacitorjs.com/docs/ios/configuration#configuring-infoplist) 并用原始密钥添加权限 `NSCameraUsageDescription` 财务报告和审定财务报表 `NSMicrophoneUsageDescription`。。。 . `NSMicrophoneUsageDescription` 只有使用音频时才需要。否则设置 `disableAudio` 选项到 `true`,也可以禁用麦克风许可请求. ## 额外的 Web 安装步骤添加 `import { CameraPreview } from '@capacitor-community/camera-preview';` 在要使用插件的文件中. 然后在html中添加 `

` 财务报告和审定财务报表 `CameraPreview.start({ parent: "cameraPreview"});` 将工作. # 方法 ### 开始( 选项) 启动相机预览实例. **机器人:** 返回的许诺只有在本地预览首次交付后才解决准备捕捉它拒绝无法启动相机或预览, 或者没有第一帧在10秒内到达通话 `start()` 当相机已经运行时或开始拒绝. | 选项 | 数值 | 说明 | | --- | --- | --- | | 职位 | 前后键 | 开始预览时显示前相机或后相机。默认值 | | 宽度 | 数字( 整数 !) | (可选) 预览宽度以像素为单位,默认窗口. 屏幕。宽度(仅适用于 Android 和 ios 平台) | | 高度 | 数字( 整数 !) | (可选) 预览高度以像素为单位,默认窗口. 屏幕。高度(仅适用于机器人和ios平台) | | 页:1 | 数字( 整数 !) | (可选) x 来源, 默认 0( 仅适用于 Android 和 ios 平台) | | 尔 | 数字( 整数 !) | (可选) y 来源, 默认 0( 仅适用于 Android 和 ios 平台) | | 转回 | 布尔 | (可选)将您的 html 带入您的预览前, 默认虚假( 仅适用于 Android 和 ios 平台) | | 粘接键 | 编号 | (可选) 预览以像素为单位的底贴. 用于在方向变化时保持适当的预览大小(仅适用于 Android 和 ios 平台) | | 改变方向时旋转 | 布尔 | (可选)在方向变化时旋转预览(仅适用于ios平台;默认值为真) | | 存储到文件 | 布尔 | (可选)抓取图像到一个文件,然后返回文件路径,而不是返回已编码的基数64数据,默认是虚假的. | | 禁用Exif 信头拖取 | 布尔 | (可选) 禁用图像的自动旋转, 让浏览器处理, 默认为真实( 仅适用于 Android 和 ios 平台) | | 启用高分辨率 | 布尔 | (可选) 默认为假 - iOS - 激活高分辨率图像抓取, 以便输出图像来自设备上尽可能高的分辨率 | | 禁用音频 | 布尔 | (可选) 禁用音频流来防止权限请求, 默认为虚假。 (仅适用于网络和iOS) | | 锁定和机器人方向 | 布尔 | (可选) 相机显示时锁定设备方向, 默认为虚假。 (仅适用于Android) | | 启用时间 | 布尔 | (可选) 让相机预览通过. 增加现实用途的理想。默认虚假( 仅适用于 Android 和 Web) | | 启用Zoom | 布尔 | (可选) 设定是否可压缩。默认虚假( 仅适用于 Android 和 ios 平台) | ```javascript import { CameraPreview, CameraPreviewOptions } from '@capacitor-community/camera-preview'; const cameraPreviewOptions: CameraPreviewOptions = { position: 'rear', height: 1920, width: 1080 }; CameraPreview.start(cameraPreviewOptions); ``` 记得在您的应用的 HTML 或 body 元素上添加以下样式 : ```css ion-content { --background: transparent; } ``` 考虑到这将让应用程序上的所有离子内容透明化, 如果你想只显示一页的相机预览, 请在离子内容中添加一个自定义的类, 并使其透明 : ```css .my-custom-camera-preview-content { --background: transparent; } ``` 如果在应用了上述样式后相机预览未显示,则对母组件的根 div 元素应用透明背景颜色例:VueJS >>. App.vue 组件 ```html ``` ### 停止( ) 停止相机预览实例 . ```javascript CameraPreview.stop(); ``` ### 翻转( c) 仅为 Android 和 ios 在后相机和前相机之间切换, 不支持网络 `javascript CameraPreview.flip()` **机器人:** 返回的承诺只有在切换相机交付后才解决第一个预览框架。如果当前预览尚未准备好, 它拒绝中,或者切换相机无法启动或退出。在只有一个设备上相机,它不切换即可解析,保留现有的行为. ### 抓取( 选项) **机器人:** `capture()` 需要一个已交付第一个帧的相机预览。它拒绝如果没有活动相机,则预览尚未准备好,或者另一个捕获工作已经在进行中. 原生抓取和图像处理失败作为承诺拒绝返回,而不是终止Android进程. 如果预览暂停或停止,接受的捕获也会被拒绝,而不是等待, 或如果其输出表面被破坏。 A 类 `flip()` 在抓获期间提出的请求被驳回,无需打断捕捉。如果在图片失败后重新启动预览,则抓取拒绝并 `isCameraStarted()` 变成 `false`。。。 . | 选项 | 数值 | 说明 | | --- | --- | --- | | 质量 | 编号 | (可选) 图片质量, 0 - 100, 默认 85 | | 宽度 | 编号 | (可选) 图片宽度, 默认为 0( Device 默认) | | 高度 | 编号 | (可选) 图片高度, 默认为 0( Device 默认) | ```javascript import { CameraPreviewPictureOptions } from '@capacitor-community/camera-preview'; const cameraPreviewPictureOptions: CameraPreviewPictureOptions = { quality: 50 }; const result = await CameraPreview.capture(cameraPreviewPictureOptions); const base64PictureData = result.value; // do sometime with base64PictureData ``` ### 抓取样本( 选项) | 选项 | 数值 | 说明 | | --- | --- | --- | | 质量 | 编号 | (可选) 图片质量, 0 - 100, 默认 85 | 从视频流中获取一个样本图像。只对Android和iOS来说,网络执行又回到“抓取” 方法。这可用于对视频中的当前帧进行实时分析. 论点\`质量' 默认为\`85'并指定质量/压缩值:\`0=最大压缩'、\`100=最大质量'. ```javascript import { CameraSampleOptions } from '@capacitor-community/camera-preview'; const cameraSampleOptions: CameraSampleOptions = { quality: 50 }; const result = await CameraPreview.captureSample(cameraSampleOptions); const base64PictureData = result.value; // do something with base64PictureData ``` ### 获得支持的 FlashModes () 获取目前启动的相机设备支持的闪存模式。返回包含所支持的闪存的数组模式。见 `[FLASH_MODE](#camera_Settings.FlashMode)` 对于可能返回的值 ```javascript import { CameraPreviewFlashMode } from '@capacitor-community/camera-preview'; const flashModes = await CameraPreview.getSupportedFlashModes(); const supportedFlashModes: CameraPreviewFlashMode[] = flashModes.result; ``` ### 设定FlashMode( 选项) 设定闪存模式。见 `[FLASH_MODE](#camera_Settings.FlashMode)` 关于可能值的详情用于闪存模式. ```javascript const CameraPreviewFlashMode: CameraPreviewFlashMode = 'torch'; CameraPreview.setFlashMode(cameraPreviewFlashMode); ``` ### 只启动记录视频( 选项) -- -- ANDROID 和 iOS 开始捕捉视频 ```javascript const cameraPreviewOptions: CameraPreviewOptions = { position: 'front', width: window.screen.width, height: window.screen.height, }; CameraPreview.startRecordVideo(cameraPreviewOptions); ``` ### 仅停止记录视频( ) -- -- ANDROID 和 iOS 拍完录影带被捕获的视频将作为文件路径返回,视频格式为.mp4 ```javascript const resultRecordVideo = await CameraPreview.stopRecordVideo(); ``` ### setOpacity(选项:相机Opacity Options):承诺-; -- -- -- 仅安地鲁德设定相机预览的不透明性 ```javascript const myCamera = CameraPreview.start({ enableOpacity: true }); myCamera.setOpacity({ opacity: 0.4 }); ``` ### 是CameraStartted() -- -- 仅限ANDROID和iOS 检查或检测相机是否已启动 **机器人:** 此报告相机预览准备, 即本地预览是否有生产了第一个框架,可以使用。没错 `false` 当预览还在开始时,以及 `false` 在预览被暂停、停止或已丢失其输出表面之后. ```javascript const { value } = await CameraPreview.isCameraStarted(); ``` # 设置 ### FLASH MODE 软件闪光模式设置 : | 名称 | 类型 | 默认 | 说明 | | --- | --- | --- | --- | | 关闭 | 字符串 | 关 | | | 打开 | 字符串 | 打开 | | | 阿图 | 字符串 | 自动 | | | (简体中文) | 字符串 | 红眼 | 只有机器人 | | 语句 | 字符串 | 火炬 | | # 演示/实例应用程序可在 [示例应用](https://github.com/capacitor-community/camera-preview/tree/master/example-app) ## 常见问题 ### @capacitor-community/camera-preview 是什么？相机预览 ### 如何安装 @capacitor-community/camera-preview？在项目目录运行 npm install @capacitor-community/camera-preview，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@capacitor/core（\>=8\.0\.2）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @capacitor-community/camera-preview 支持 TypeScript 吗？支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @capacitor-community/camera-preview 支持 ESM 还是 CommonJS？同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @capacitor-community/camera-preview 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=18\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @capacitor-community/camera-preview 可以商用吗？ @capacitor-community/camera-preview 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @capacitor-community/camera-preview 的下载量有多少？根据 npm 官方下载统计，@capacitor-community/camera-preview 在 2026/10/09 – 2026/11/07 这 30 天内被下载 124,658 次，日均约 4,155 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @capacitor-community/camera-preview 还在维护吗？最新版本 8\.0\.2 发布于 2026/09/25（1 个月前）；至今共发布 37 个版本，其中过去 12 个月发布了 6 个；首次发布于 2020/07/18。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。