Capacitor 插件贡献指南

Capacitor 插件将web技术与native设备功能连接起来，从而使跨平台应用开发. 本指南将帮助您：

设置您的环境: 使用的工具包括 Node.js, Xcode和 Android Studio 是必不可少的。
遵循 Code 标准：使用 TypeScript, Swift，和 Kotlin 以一致的命名约定和错误处理方式
彻底测试为 JavaScript、iOS 和 Android 编写单元测试以确保可靠性。
明确说明使用 JSDoc 和 README 文件进行易于采用的文档
提交拉取请求在贡献之前确保高质量的 code 测试和文档

开源贡献指南

开发环境设置

创建一个合适的开发环境对于高效的插件开发至关重要。一个准备好的设置使编码、测试和部署插件变得更加流畅。

您需要的工具和技能

在开始之前，请确保您安装了以下工具：

分类	需求
核心工具	Node.js (LTS), npm 6+, Git
IDE/编辑器	Visual Studio Code 或您的喜爱的编辑器
iOS 开发	Xcode, SwiftLint, CocoaPods
Android 开发	Android Studio, Android SDK, JDK

您还应该对 TypeScript 的 Web 开发以及 Swift (用于 iOS) 或 Java/Kotlin (用于 Android) 的本机开发任务感到舒适 [1][2].

设置单元仓库

The Capacitor 插件生态系统依赖于单元仓库结构。这一方法确保您的工作从一开始就符合社区标准。

分叉和克隆仓库
首先，分叉 GitHub 上的 Capacitor 插件仓库，然后克隆您的分叉仓库：
```
git clone https://github.com/your-username/capacitor-plugins.git
cd capacitor-plugins
npm install
```
安装依赖项和构建
运行以下命令来安装所需的所有内容并构建插件：
```
npm run build
```
设置版本控制
使用特性分支来跟踪您的更改，并确保您的分叉仓库与上游仓库保持同步。

准备本机平台

为了跨平台开发，您需要配置 iOS 和 Android 环境。

对于 iOS：

从 Mac App Store 下载 Xcode。
使用以下命令安装命令行工具：
```
xcode-select --install
```
使用以下命令安装 CocoaPods：
```
sudo gem install cocoapods
```
设置 Apple 开发者账户和必要的证书。
Use SwiftLint (optional) for maintaining code quality.

对于 Android：

安装 Android Studio、最新的 SDK 和虚拟设备。
确保您已安装 JDK。
在 Android Studio 中正确配置 Android SDK。

一旦这些平台设置完成，您就可以按照既定的编码实践并深入插件开发。

Code 标准指南

现在您的开发环境已经设置好，按照这些指南来构建易于维护和使用的插件。

风格指南遵守性

The Capacitor 插件生态系统使用工具如 ESLint、Prettier 和 SwiftLint 强制执行严格的编码标准。以下是所需格式的快速概述：组件, 格式变量

enforces strict coding standards using tools like ESLint, Prettier, and SwiftLint. Here’s a quick overview of the required formatting:	The __CAPGO_KEEP_0__ plugin ecosystem enforces strict coding standards using tools like ESLint, Prettier, and SwiftLint. Here’s a quick overview of the required formatting:
Component, Format, Variables	`deviceInfo` 小写字母
分类	`BatteryManager` 帕斯卡大小写
方法	`getLanguageCode()` 小写字母
常量	`MAX_RETRY_COUNT` 蛇形大写

插件应使用 TypeScript 以获得更好的类型安全性和 ES6+ 的功能，如 async/await.另外，遵循 Swift（iOS）和 Kotlin（Android）平台特有的编码规范。

错误和类型管理

跨平台兼容性中，错误处理的统一是至关重要的。以下是一个例子：

async checkPermissions(): Promise<PermissionStatus> {
  try {
    const result = await this.implementation.checkPermissions();
    return result;
  } catch (error) {
    throw new Error(`Permission check failed: ${error.message}`);
  }
}

为了类型安全：

专注于特定场景的界面
为平台特定变体应用联合类型

Code 文档

良好的文档是使插件易于使用和可访问的关键。遵循这些实践：

API 文档:编写与 JSDoc 一起工作的注释。 @capacitor/docgen例如：

/**
 * @description Get the device's current battery level
 * @returns Promise with the battery level percentage
 */
async getBatteryLevel(): Promise<{ level: number }>;

README 结构:包含安装步骤、配置说明、平台特定要求、使用示例和详细的API参考。

良好的文档确保您的插件易于采用并为更广泛的Capacitor社区做出贡献。

sbb-itb-f9944d2

插件测试指南

测试Capacitor插件涉及关注几个关键领域，以确保平稳的功能和可靠性。

原生桥接测试

原生桥接测试确保JavaScript和原生code之间的通信正常。要开始测试，请设置一个适合每个平台的测试环境。

以下是 Jest JavaScript侧的单元测试示例：

// Example of a Jest unit test for the JavaScript bridge
describe('DeviceInfo Plugin', () => {
  test('getBatteryLevel returns valid percentage', async () => {
    const result = await DeviceInfo.getBatteryLevel();
    expect(result.level).toBeGreaterThanOrEqual(0);
    expect(result.level).toBeLessThanOrEqual(100);
  });
});

在原生侧进行测试时，使用XCTest进行iOS测试，JUnit进行Android测试。以下是Android的示例：

@Test
fun testBatteryLevel() {
    val plugin = DeviceInfo()
    val result = plugin.getBatteryLevel()
    assertTrue(result.level in 0..100)
}

一旦确认核心桥接功能正常工作后，就可以测试完整的用户工作流程。

完整插件测试

为了确保您的插件在不同场景下表现良好，测试各种类别：

测试类别	关键关注点领域
集成测试	跨平台功能
性能测试	资源使用情况和响应时间
安全测试	数据处理和权限检查

对于具有复杂功能的插件，模拟真实世界的用户场景。例如，如果您正在测试DeviceInfo插件，请检查：

在不同网络条件下进行成功上传
准确的进度报告
在大文件传输期间的内存使用

OTA测试与 Capgo

Capgo 实时更新控制台界面

Capgo 提供开源工具，方便快速部署和测试更新。以下是使用说明：

设置更新频道例如开发、测试和生产。
使用 CI/CD 工具自动部署。
立即推送更新。
通过 __CAPGO_KEEP_0__ 控制台监控性能和问题。对于分阶段发布，Capgo 允许您限制更新到小部分用户。例如，您可以每 24 小时将新版本推送到 25% 的用户：.

For phased rollouts, Capgo allows you to limit updates to a small percentage of users. For instance, you can roll out a new version to 25% of users every 24 hours:

// Example configuration for staged rollout
{
  "plugin": "camera-plugin",
  "version": "1.2.0",
  "rollout": {
    "percentage": 25,
    "interval": "24h"
  }
}

拉取请求流程

__CAPGO_KEEP_0__

您已经彻底测试了您的更改后，请按照以下步骤提交您的拉取请求：

拉取请求提交清单

在提交之前，请确保您已经覆盖了这些关键领域：

类别	检查什么
Code 质量	- 确保 Swift/Kotlin 实现与 web API 一致。
测试	- 为新功能添加单元测试。 - 确认 CI/CD pipeline 检查成功。
文档	- 更新 README、内联文档和 CHANGELOG 如有需要。

社区守则

在协作时，遵循以下最佳实践：

及时响应审阅者反馈。
保持讨论聚焦于技术细节。
GitHub的建议功能建议使用code的修改。
提交小型、聚焦的pull请求，仅解决一个特性或问题。

对于更大的修改，建议在提交之前先创建一个问题并讨论你的方法。Capacitor团队依赖GitHub Actions进行自动检查，所有检查必须通过才能进行审阅。

Capgo集成指南

如果你的插件涉及实时更新，请确保在提交之前确保它与Capgo无缝工作：

版本控制
为你的插件使用清晰的语义版本控制，并在changelog中记录所有修改。Capgo的系统帮助跟踪用户设备上的版本采用率。
CI/CD集成
将 Capgo 集成到您的 CI/CD pipeline 中，以便自动化更新部署。
更新监控
监控部署成功率并确保遵守应用商店的指南。

概要

要想以有意义的方式贡献您的插件，很重要的是要遵循已建立的流程并符合社区标准。这包括遵循 Capacitor 的编码指南，并对您的工作进行彻底的测试。

PR 检查清单强调了高质量提交的必要性。如果您的插件支持实时更新，集成到 Capgo（如前所述）可以帮助您快速发布更新，而无需等待应用商店批准。

一旦您的 PR 被合并，保持参与并跟踪问题和发布版本更新。与社区保持活跃、持续维护并跟上 Capacitor 更新将确保您的插件始终有用和相关。

注意用户反馈并根据需要进行更新。这项持续的努力有助于维护整个生态系统的整体质量，并使您的插件对开发者有价值。