Capacitor 插件贡献指南

Capacitor 插件连接了Web技术与native设备功能，实现跨平台应用开发本指南将帮助您:

设置您的环境: 必须使用的工具包括 Node.js, Xcode, 和 Android Studio 遵循 __CAPGO_KEEP_0__ 标准
Follow Code StandardsTypeScript TypeScript, Swift, 和 Kotlin 使用一致的命名约定和错误处理。
彻底测试: 为 JavaScript、iOS 和 Android 编写单元测试以确保可靠性。
清晰文档: 使用 JSDoc 和 README 文件以便于采用。
提交 Pull Request: 在贡献之前确保高质量的 code, 测试和文档。

开源贡献指南

环境设置

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

所需工具和技能

开始之前，请确保你已经安装以下工具:

类别	要求
核心工具	Node.js (LTS), npm 6+, Git
IDE/编辑器	Visual Studio Code 或你偏好的编辑器
iOS 开发	Xcode, SwiftLint, CocoaPods
安卓开发	安卓Studio,安卓SDK,JDK

您还应该对TypeScript进行Web开发和Swift(iOS)或Java/Kotlin(安卓)进行原生开发任务感到舒适 [1][2].

设置单元仓库

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

分叉和克隆仓库
首先，分叉Capacitor插件仓库到GitHub。然后，克隆您的分叉仓库：
```
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 Developer帐户和必要的证书。
Use SwiftLint (optional) for maintaining code quality.

For Android:

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

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

Code Standards Guide

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

Style Guide Compliance

The Capacitor plugin ecosystem 严格遵守编码标准的 __CAPGO_KEEP_0__ 插件生态系统使用工具如 ESLint, Prettier以及 SwiftLint。以下是一些必需的格式化内容:

组件	格式
变量	`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编写适用于的JSDoc注释。例如：

/**
 * @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 Live Update Dashboard Interface

Capgo’s open-source tools make it easy to deploy and test updates quickly. Here’s how to use it:

更新频道例如dev, staging,和production 使用CI/CD工具自动部署
立即推送更新
__CAPGO_KEEP_0__ Live Update Dashboard Interface
通过__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 流程

一旦您对更改进行了彻底的测试，就按照以下步骤提交您的拉取请求：

PR 提交清单

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

类别	需要检查的内容
Code质量	- 确保Swift/Kotlin实现与WebAPI一致。
测试	- 为新功能添加单元测试。 - 确认 CI/CD pipeline 检查成功。
文档	context:Capgo Builder / native cloud build 产品页面

context:Capgo 市场网站

- 更新 README、内联文档和 CHANGELOG 等内容。

社区指南
在协作时，遵循以下最佳实践:
Use GitHub’s suggestion feature to propose code changes.
保持讨论聚焦于技术细节。

使用 Capacitor 的建议功能来提出 GitHub 的修改建议。

Capgo 集成指南

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

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

概要

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

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

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

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

继续阅读 Capacitor 插件贡献指南

如果您正在使用 Capacitor 插件贡献指南 来规划原生插件工作，连接它与 Capgo 插件目录在 Capgo 插件目录中 Capacitor 插件由 Capgo 提供在 Capacitor 插件由 Capgo 中添加或更新插件为添加或更新插件的实现细节 Ionic 企业插件替代品为 Ionic 企业插件替代品的产品工作流程 Capgo 本机构建为 Capgo 本机构建的产品工作流程