Capacitor 插件贡献指南

Capacitor 将 web 技术与原生设备功能连接起来，实现跨平台应用开发。本指南将帮助您：

设置您的环境:像 Node.js, Xcode, 和 Android Studio 是必需的。
遵循 Code 标准:使用 TypeScript, Swift, 和简化中文遵循一致的命名规范和错误处理
彻底测试: 为 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

对于 web 开发，您应该也要熟悉 TypeScript，另外对于 native 开发任务，您应该也要熟悉 Swift (用于 iOS) 或 Java/Kotlin (用于 Android) [1][2].

设置单元仓库

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

fork 仓库
开始通过 fork Capacitor 插件仓库于 GitHub，然后克隆您的 fork 仓库：

git clone https://github.com/your-username/capacitor-plugins.git
cd capacitor-plugins
npm install

安装依赖项并构建
运行以下命令来安装所需的所有内容并构建插件：
```
npm run build
```
Set Up Version Control
使用分支管理您的修改并保持您的分支与上游仓库同步。

Preparing Native Platforms

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

For iOS:

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

For Android:

Install Android Studio along with the latest SDK and a virtual device.
确保您已安装 JDK。
在 Android Studio 中正确配置 Android SDK。

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

Code 标准指南

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

风格指南遵从性

__CAPGO_KEEP_0__ 插件生态系统 Capacitor plugin ecosystem ESLint Prettier, ,和 SwiftLint。以下是一些必需的格式化要求：__CAPGO_KEEP_0__

组件	格式
变量	`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 文档: 使用 @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)
}

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

完整插件测试

To ensure your plugin performs well across different scenarios, test various categories:

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

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

在不同网络条件下成功上传
准确的进度报告
__CAPGO_KEEP_0__

OTA测试 Capgo

Capgo实时更新控制台界面

Capgo的开源工具使其易于部署和测试更新。以下是如何使用它：

设置更新频道例如dev、staging和生产。
使用CI/CD工具自动部署。
立即推送更新。
通过__CAPGO_KEEP_0__控制台监控性能和问题。 Capgo.

对于分阶段发布，Capgo允许您限制更新到小部分用户。例如，您可以每24小时将新版本发布到25%的用户：

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

这种分阶段的方法通过利用社区反馈在全面发布之前就能早期识别问题。

Pull Request 流程

您经过彻底测试后，请按照以下步骤提交您的Pull Request：

PR 提交清单

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

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

社区指南

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

快速响应审阅者反馈。
保持讨论聚焦于技术细节。
使用 GitHub 的建议功能来提出 code 的更改。
提交小型、聚焦的 pull 请求，仅处理一个特性或问题一次。

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

Capgo 集成指南

如果你的插件涉及实时更新，请在提交之前确保它与 Capgo 完美兼容：

Version Control
使用清晰的语义版本控制您的插件，并在更改日志中记录所有更改。Capgo系统帮助跟踪用户设备上的版本采用率.
CI/CD Integration
将Capgo集成到CI/CD管道中，以自动化更新部署.
Update Monitoring
监控部署成功率并确保遵守应用商店指南.

Summary

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

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

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

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

继续阅读 Capacitor 插件贡献指南

如果您正在使用 Capacitor 插件贡献指南 来规划原生插件工作，连接它与 Capgo 插件目录 for the product workflow in Capgo Plugin Directory, Capacitor Plugins by Capgo for the implementation detail in Capacitor Plugins by Capgo, __CAPGO_KEEP_0__ 由 __CAPGO_KEEP_1__ 来查看实现细节在 __CAPGO_KEEP_0__ 由 __CAPGO_KEEP_1__ 中的插件，为 Ionic Enterprise Plugin Alternatives 产品工作流程， Capgo 原生构建为 Capgo 原生构建产品工作流程，