capacitor-plugins
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseCapacitor Plugins
Capacitor插件
Install, configure, and use Capacitor plugins from official and community sources.
安装、配置并使用来自官方及社区来源的Capacitor插件。
Prerequisites
前置条件
- Capacitor 6, 7, or 8 app.
- Node.js and npm installed.
- For iOS plugins: Xcode installed. CocoaPods or Swift Package Manager (SPM) for dependency management.
- For Android plugins: Android Studio installed.
- Capacitor 6、7或8 应用。
- 已安装Node.js和npm。
- 若使用iOS插件：需安装Xcode，且使用CocoaPods或Swift Package Manager（SPM）进行依赖管理。
- 若使用Android插件：需安装Android Studio。
Agent Behavior
Agent行为规范
- Guide step-by-step. Walk the user through the process one step at a time. Never present multiple unrelated questions at once.
- Auto-detect before asking. Check the project for platforms (,
android/), build tools (ios/,vite.config.ts,angular.json), framework, existing npm registry config, andwebpack.config.jsdependencies. Only ask the user when something cannot be detected.package.json - One decision at a time. When a step requires user input (e.g., encryption yes/no), ask that single question, wait for the answer, then continue to the next step.
- Present clear options. When asking a question, provide concrete choices (e.g., "Do you need SQLite encryption? (yes/no)") instead of open-ended questions.
- 分步引导：逐步引导用户完成流程，切勿同时抛出多个不相关的问题。
- 先自动检测再询问：检查项目中的平台目录（、
android/）、构建工具（ios/、vite.config.ts、angular.json）、框架、现有npm registry配置以及webpack.config.js中的依赖项。仅当无法自动检测时才向用户询问。package.json - 一次一个决策：当步骤需要用户输入时（如是否启用加密），仅提出该单个问题，等待用户回复后再继续下一步。
- 提供明确选项：询问问题时给出具体选项（例如：“是否需要SQLite加密？(是/否)”），而非开放式问题。
Procedures
操作流程
Step 1: Identify the Plugin
步骤1：确定插件
Match the user's request to a plugin from the index below. If the match is ambiguous, ask the user to clarify.
将用户的需求与下方索引中的插件进行匹配。若匹配存在歧义，请让用户进行澄清。
Step 2: Read the Reference File
步骤2：查阅参考文件
Read the corresponding reference file from for the matched plugin.
references/为匹配到的插件查阅目录下对应的参考文件。
references/Step 3: Analyze the Project
步骤3：分析项目
Auto-detect the following by reading project files — do not ask the user for information that can be inferred:
- Platforms: Check which directories exist (,
android/). These are the platforms to configure.ios/ - Build tool / framework: Check for ,
vite.config.ts,angular.json,webpack.config.js, etc.next.config.js - iOS dependency manager: Check if exists (CocoaPods) or if SPM is used.
ios/App/Podfile - Capacitor version: Read version from
@capacitor/core.package.json
通过读取项目文件自动检测以下信息——切勿向用户询问可通过推断获取的信息：
- 平台：检查是否存在对应目录（、
android/），这些即为需要配置的平台。ios/ - 构建工具/框架：检查是否存在、
vite.config.ts、angular.json、webpack.config.js等文件。next.config.js - iOS依赖管理器：检查是否存在（CocoaPods）或是否使用SPM。
ios/App/Podfile - Capacitor版本：从中读取
package.json的版本。@capacitor/core
Step 4: Set Up Prerequisites
步骤4：配置前置要求
If the plugin requires Capawesome Insiders (the reference file states ):
Capawesome Insiders: Yes- Check if the npm registry is already configured by running:
@capawesome-teamnpm config get @capawesome-team:registry - If the registry is not configured, tell the user this plugin requires a Capawesome Insiders license and guide them through the setup:
Ask the user for their license key if needed. Wait for confirmation before continuing.bash
npm config set @capawesome-team:registry https://npm.registry.capawesome.io npm config set //npm.registry.capawesome.io/:_authToken <YOUR_LICENSE_KEY> - If the registry is already configured, skip this and move on.
若插件需要Capawesome Insiders（参考文件中标记为）：
Capawesome Insiders: Yes- 通过运行以下命令检查是否已配置npm registry：
@capawesome-teambashnpm config get @capacitor-team:registry - 若registry未配置，告知用户该插件需要Capawesome Insiders许可证，并引导其完成配置：
若需要，请向用户索要许可证密钥。等待用户确认后再继续。bash
npm config set @capawesome-team:registry https://npm.registry.capawesome.io npm config set //npm.registry.capawesome.io/:_authToken <YOUR_LICENSE_KEY> - 若registry已配置，则跳过此步骤，继续下一步。
Step 5: Install the Plugin
步骤5：安装插件
Run the installation command from the reference file:
bash
npm install <package-name>
npx cap syncIf the reference file lists additional packages (e.g., ), include them.
@sqlite.org/sqlite-wasm运行参考文件中的安装命令：
bash
npm install <package-name>
npx cap sync若参考文件中列出了额外的包（如），请一并安装。
@sqlite.org/sqlite-wasmStep 6: Apply Platform-Specific Configuration
步骤6：应用平台专属配置
For each platform detected in Step 3, apply the configuration from the reference file.
When the reference file offers variants or optional features for a platform (e.g., encryption vs. plain, bundled SQLite vs. default), handle them one at a time:
- Present the choice to the user with a clear question and options.
- Wait for the user's answer.
- Apply only the chosen configuration.
- Move on to the next platform or decision point.
Typical configuration includes:
- Android: Gradle variables in , permissions in
variables.gradle, meta-data entries, ProGuard rulesAndroidManifest.xml - iOS: entries, Podfile or SPM changes,
Info.plistmodificationsAppDelegate.swift
Skip platforms that don't exist in the project.
针对步骤3中检测到的每个平台，应用参考文件中的配置。
当参考文件针对某平台提供变体或可选功能时（如加密版 vs 普通版、捆绑SQLite vs 默认版），需逐一处理：
- 以清晰的问题和选项向用户呈现选择。
- 等待用户回复。
- 仅应用用户选择的配置。
- 进入下一个平台或决策点。
典型配置包括：
- Android：中的Gradle变量、
variables.gradle中的权限、元数据条目、ProGuard规则AndroidManifest.xml - iOS：条目、Podfile或SPM修改、
Info.plist调整AppDelegate.swift
跳过项目中不存在的平台。
Step 7: Apply Web Configuration (if applicable)
步骤7：应用Web配置（如适用）
If the reference file includes a Web configuration section and the project targets the web:
- Apply the configuration matching the detected build tool (Vite, Webpack, Angular CLI, etc.).
- If the build tool is not covered by the reference file, adapt the configuration to the detected build tool and inform the user.
若参考文件包含Web配置章节且项目面向Web平台：
- 应用与检测到的构建工具（Vite、Webpack、Angular CLI等）匹配的配置。
- 若参考文件未覆盖该构建工具，需根据检测到的构建工具调整配置并告知用户。
Step 8: Add Usage Code
步骤8：添加使用代码
Ask the user if they want usage code added to the project. If yes:
- Add the usage code from the reference file.
- Adapt imports, method calls, and options to match the user's project structure and requirements.
询问用户是否需要在项目中添加使用代码。若用户同意：
- 添加参考文件中的使用代码。
- 根据用户的项目结构和需求调整导入语句、方法调用及选项。
Step 9: Sync the Project
步骤9：同步项目
bash
npx cap syncbash
npx cap syncPlugin Index
插件索引
Official Capacitor Plugins
官方Capacitor插件
| Plugin | Package | Reference |
|---|---|---|
| Action Sheet | | |
| App | | |
| App Launcher | | |
| Background Runner | | |
| Barcode Scanner | | |
| Browser | | |
| Camera | | |
| Clipboard | | |
| Cookies | | |
| Device | | |
| Dialog | | |
| File Transfer | | |
| File Viewer | | |
| Filesystem | | |
| Geolocation | | |
| Google Maps | | |
| Haptics | | |
| Http | | |
| InAppBrowser | | |
| Keyboard | | |
| Local Notifications | | |
| Motion | | |
| Network | | |
| Preferences | | |
| Privacy Screen | | |
| Push Notifications | | |
| Screen Orientation | | |
| Screen Reader | | |
| Share | | |
| Splash Screen | | |
| Status Bar | | |
| System Bars | | |
| Text Zoom | | |
| Toast | | |
| Watch | | |
| 插件 | 包名 | 参考文件 |
|---|---|---|
| 操作菜单 | | |
| 应用核心 | | |
| 应用启动器 | | |
| 后台运行器 | | |
| 条码扫描器 | | |
| 浏览器 | | |
| 相机 | | |
| 剪贴板 | | |
| Cookies | | |
| 设备信息 | | |
| 对话框 | | |
| 文件传输 | | |
| 文件查看器 | | |
| 文件系统 | | |
| 地理定位 | | |
| Google地图 | | |
| 触觉反馈 | | |
| Http | | |
| 内置浏览器 | | |
| 键盘 | | |
| 本地通知 | | |
| 运动传感器 | | |
| 网络状态 | | |
| 偏好设置 | | |
| 隐私屏幕 | | |
| 推送通知 | | |
| 屏幕方向 | | |
| 屏幕阅读器 | | |
| 分享 | | |
| 启动屏 | | |
| 状态栏 | | |
| 系统栏 | | |
| 文本缩放 | | |
| 提示框 | | |
| 手表集成 | | |
Capawesome Plugins
Capawesome插件
| Plugin | Package | Reference |
|---|---|---|
| Accelerometer | | |
| Age Signals | | |
| Android Battery Optimization | | |
| Android Dark Mode Support | | |
| Android Edge-to-Edge Support | | |
| Android Foreground Service | | |
| App Review | | |
| App Shortcuts | | |
| App Update | | |
| Apple Sign In | | |
| Asset Manager | | |
| Audio Player | | |
| Audio Recorder | | |
| Background Task | | |
| Badge | | |
| Barometer | | |
| Biometrics | | |
| Bluetooth Low Energy | | |
| Cloudinary | | |
| Contacts | | |
| Datetime Picker | | |
| File Compressor | | |
| File Opener | | |
| File Picker | | |
| Geocoder | | |
| Google Sign In | | |
| libSQL | | |
| Live Update | | |
| Managed Configurations | | |
| Media Session | | |
| NFC | | |
| OAuth | | |
| Pedometer | | |
| Photo Editor | | |
| PostHog | | |
| Printer | | |
| Purchases | | |
| RealtimeKit | | |
| Screen Orientation | | |
| Screenshot | | |
| Secure Preferences | | |
| Share Target | | |
| Speech Recognition | | |
| Speech Synthesis | | |
| SQLite | | |
| Square Mobile Payments | | |
| Superwall | | |
| Torch | | |
| Wi-Fi | | |
| Zip | | |
| 插件 | 包名 | 参考文件 |
|---|---|---|
| 加速度传感器 | | |
| 年龄信号 | | |
| Android电池优化 | | |
| Android深色模式支持 | | |
| Android全屏支持 | | |
| Android前台服务 | | |
| 应用评分 | | |
| 应用快捷方式 | | |
| 应用更新 | | |
| Apple登录 | | |
| 资源管理器 | | |
| 音频播放器 | | |
| 音频录制器 | | |
| 后台任务 | | |
| 角标 | | |
| 气压计 | | |
| 生物识别 | | |
| 低功耗蓝牙 | | |
| Cloudinary集成 | | |
| 联系人 | | |
| 日期时间选择器 | | |
| 文件压缩器 | | |
| 文件打开器 | | |
| 文件选择器 | | |
| 地理编码 | | |
| Google登录 | | |
| libSQL集成 | | |
| 实时更新 | | |
| 托管配置 | | |
| 媒体会话 | | |
| NFC | | |
| OAuth认证 | | |
| 计步器 | | |
| 图片编辑器 | | |
| PostHog集成 | | |
| 打印机 | | |
| 内购 | | |
| RealtimeKit集成 | | |
| 屏幕方向 | | |
| 截图 | | |
| 安全偏好设置 | | |
| 分享目标 | | |
| 语音识别 | | |
| 语音合成 | | |
| SQLite集成 | | |
| Square移动支付 | | |
| Superwall集成 | | |
| 手电筒 | | |
| Wi-Fi管理 | | |
| 压缩解压 | | |
Capacitor Firebase Plugins
Capacitor Firebase插件
| Plugin | Package | Reference |
|---|---|---|
| Analytics | | |
| App | | |
| App Check | | |
| Authentication | | |
| Crashlytics | | |
| Firestore | | |
| Functions | | |
| Messaging | | |
| Performance | | |
| Remote Config | | |
| Storage | | |
| 插件 | 包名 | 参考文件 |
|---|---|---|
| 分析 | | |
| 应用核心 | | |
| 应用校验 | | |
| 身份认证 | | |
| 崩溃分析 | | |
| 云Firestore | | |
| 云函数 | | |
| 消息推送 | | |
| 性能监控 | | |
| 远程配置 | | |
| 云存储 | | |
Capacitor MLKit Plugins
Capacitor MLKit插件
| Plugin | Package | Reference |
|---|---|---|
| Barcode Scanning | | |
| Face Detection | | |
| Face Mesh Detection | | |
| Selfie Segmentation | | |
| Subject Segmentation | | |
| Translation | | |
| 插件 | 包名 | 参考文件 |
|---|---|---|
| 条码扫描 | | |
| 人脸检测 | | |
| 人脸网格检测 | | |
| 自拍分割 | | |
| 主体分割 | | |
| 翻译 | | |
Error Handling
错误处理
- Installation fails: Verify the package name is correct and the plugin version is compatible with the project's Capacitor version. Check version in
@capacitor/core.package.json - fails: Ensure all native dependencies are installed. On iOS with CocoaPods, run
npx cap sync. On Android, sync Gradle files.cd ios/App && pod install - Android build fails: Check that required Gradle variables are set in . Verify permissions are added to
variables.gradle.AndroidManifest.xml - iOS build fails: Check that required entries are present. Verify the deployment target meets the plugin's minimum requirement.
Info.plist - Plugin not found at runtime: Ensure was run after installation. For iOS, verify the dependency was installed (pod for CocoaPods, package for SPM). For Android, verify the Gradle sync completed.
npx cap sync - Permission denied at runtime: Check that permissions are declared in platform config files AND requested at runtime via /
checkPermissions()where applicable.requestPermissions()
- 安装失败：验证包名是否正确，插件版本是否与项目的Capacitor版本兼容。检查中的
package.json版本。@capacitor/core - 失败：确保所有原生依赖已安装。对于使用CocoaPods的iOS项目，运行
npx cap sync。对于Android项目，同步Gradle文件。cd ios/App && pod install - Android构建失败：检查中是否已设置所需的Gradle变量。验证权限是否已添加到
variables.gradle。AndroidManifest.xml - iOS构建失败：检查是否已添加所需的条目。验证部署目标是否满足插件的最低要求。
Info.plist - 运行时未找到插件：确保安装后已运行。对于iOS，验证依赖是否已安装（CocoaPods对应pod，SPM对应包）。对于Android，验证Gradle同步已完成。
npx cap sync - 运行时权限被拒绝：检查权限是否已在平台配置文件中声明，并且在运行时通过/
checkPermissions()请求（如适用）。requestPermissions()