Capacitor 插件贡献指南

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

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

对于 Android:

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

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

Code 标准指南

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

风格指南遵从性

The Capacitor 插件生态系统严格遵守编码标准，使用工具如 ESLint, 美化器,以及SwiftLint。以下是一些关于所需格式的快速概述:

组件	格式
变量	`deviceInfo` (小驼峰式)
类	`BatteryManager` (帕斯卡式)
方法	`getLanguageCode()` (小驼峰式)
常量	`MAX_RETRY_COUNT` (大写下划线式)

应使用TypeScript以获得更好的类型安全性和ES6+功能，如 async/await此外，请遵循Swift（iOS）和Kotlin（Android）的平台特定编码约定。

错误和类型管理

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

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 product page. Role: Short UI label or navigation item. Message key `native_build_v2_comp_docs_l` (Native Build V2 Comp Docs L). \| Navigation label for Documentation. Page/area: Capgo marketing website. Role: Short UI label or navigation item. Seen in: site footer. Message key `documentation` (Documentation).

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

社区指南

在合作时，遵循以下最佳实践:
快速响应审阅者反馈。
Use GitHub’s suggestion feature to propose code changes.
使用 __CAPGO_KEEP_0__ 的建议功能来提出 __CAPGO_KEEP_1__ 的修改。

For larger changes, it’s a good idea to create an issue first and discuss your approach. The Capacitor team relies on GitHub Actions for automated checks, and all checks must pass before your pull request can be reviewed.

Capgo 集成指南

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

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

概要

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

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

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

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

继续阅读 Capacitor 插件贡献指南

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