添加或更新插件

本指南介绍如何向 Capgo 网站添加新的 Capacitor 插件，或更新现有插件文档。对贡献者、维护者以及协助维护文档的 AI agent 都很有用。

概览

向 Capgo 生态添加新插件时，需要更新网站中的多个文件和位置，确保插件在所有相关位置正确显示：

1. 插件列表配置 - 在主列表中添加插件元数据
2. 插件索引页 - 将插件添加到分类插件列表页
3. 侧边栏导航 - 将插件添加到文档侧边栏
4. 插件文档 - 创建概览和入门指南页面
5. 插件教程 - 创建一份详尽的教程

文件位置

需要更新的关键文件

文件	用途
/src/config/plugins.ts	包含元数据的插件主列表
/src/content/docs/docs/plugins/index.mdx	按分类划分的插件索引页
/astro.config.mjs	侧边栏导航配置
/src/content/docs/docs/plugins/[plugin-name]/	插件文档目录
/src/content/plugins-tutorials/en/	英文教程文件

分步指南

1. 将插件添加到主列表

   打开 /src/config/plugins.ts 并将你的插件添加到 actions 数组中：

   // First, import an appropriate Heroicon
   import YourIconName from 'astro-heroicons/mini/IconName.astro'
   
   // Then add to the actions array
   {
     name: '@capgo/your-plugin-name',
     author: 'github.com/Cap-go',
     description: 'Brief description of what the plugin does',
     href: 'https://github.com/Cap-go/your-plugin-name/',
     title: 'Display Name',
     icon: YourIconName,
   }

   可用图标：检查 /node_modules/astro-heroicons/mini/ 查看可用图标。

2. 将插件添加到索引页

   打开 /src/content/docs/docs/plugins/index.mdx 并将您的插件添加到相应的分类下：

   <LinkCard
     title="Your Plugin Name"
     description="Brief description of what the plugin does"
     href="/docs/plugins/your-plugin-name/"
   />

   分类:

   • ⭐ 精选插件
   • 📱 设备与系统插件
   • 🎥 媒体与相机插件
   • 🛠️ 工具类插件
   • 🤖 AI 与高级媒体
   • 📍 位置与后台服务
   • 📞 通信与分析
   • 🔐 安全与系统
   • 📊 Android 特有功能
   • 📥 下载与导航

3. 添加到侧边栏导航

   打开 /astro.config.mjs 并将您的 plugin 添加到侧边栏配置中（约第 540 行）：

   {
     label: 'Your Plugin Name',
     items: [
       { label: 'Overview', link: '/docs/plugins/your-plugin-name/' },
       { label: 'Getting started', link: '/docs/plugins/your-plugin-name/getting-started' },
     ],
     collapsed: true,
   }

   侧边栏中的 Plugins 按字母顺序排列。

4. 创建插件文档目录

   为你的插件文档创建一个新目录：

   mkdir -p /src/content/docs/docs/plugins/your-plugin-name/

5. 创建插件概览页

   创建 /src/content/docs/docs/plugins/your-plugin-name/index.mdx:

   ---
   title: "@capgo/your-plugin-name"
   description: Brief description of the plugin's purpose
   tableOfContents: false
   next: false
   prev: false
   sidebar:
     order: 1
     label: "Introduction"
   hero:
     tagline: Detailed tagline explaining what the plugin does
     image:
       file: ~public/your-plugin-icon.svg
     actions:
       - text: Get started
         link: /docs/plugins/your-plugin-name/getting-started/
         icon: right-arrow
         variant: primary
       - text: Github
         link: https://github.com/Cap-go/your-plugin-name/
         icon: external
         variant: minimal
   ---
   
   import { Card, CardGrid } from '@astrojs/starlight/components';
   
   <CardGrid stagger>
     <Card title="Feature 1" icon="puzzle">
       Description of first key feature
     </Card>
     <Card title="Feature 2" icon="rocket">
       Description of second key feature
     </Card>
     <Card title="Cross-platform" icon="puzzle">
       Works on both iOS and Android 📱
     </Card>
     <Card title="Comprehensive Documentation" icon="open-book">
       Check the [Documentation](/docs/plugins/your-plugin-name/getting-started/) to master the plugin.
     </Card>
   </CardGrid>

6. 创建入门指南

   创建 /src/content/docs/docs/plugins/your-plugin-name/getting-started.mdx:

   ---
   title: Getting Started
   description: Learn how to install and use the plugin in your Capacitor app.
   sidebar:
     order: 2
   ---
   
   import { Steps } from '@astrojs/starlight/components';
   import { PackageManagers } from 'starlight-package-managers'
   
   <Steps>
   1. **Install the package**
      <PackageManagers pkg="@capgo/your-plugin-name" pkgManagers={['npm', 'pnpm', 'yarn', 'bun']} />
   
   2. **Sync with native projects**
      <PackageManagers type="exec" pkg="cap" args="sync" pkgManagers={['npm', 'pnpm', 'yarn', 'bun']} />
   </Steps>
   
   ## Configuration
   
   ### iOS Configuration
   [iOS-specific setup instructions]
   
   ### Android Configuration
   [Android-specific setup instructions]
   
   ## Usage
   
   [Basic usage examples]
   
   ## API Reference
   
   [Detailed API documentation]
   
   ## Complete Example
   
   [Full working example]
   
   ## Best Practices
   
   [Recommended practices and tips]
   
   ## Platform Notes
   
   [Platform-specific notes and limitations]

7. 创建教程文件

   创建 /src/content/plugins-tutorials/en/your-plugin-name.md:

   ---
   locale: en
   ---
   # Using @capgo/your-plugin-name Package
   
   The `@capgo/your-plugin-name` package [brief description]. In this tutorial, we will guide you through the installation, configuration, and usage of this package in your Ionic Capacitor app.
   
   ## Installation
   
   [Installation steps]
   
   ## Configuration
   
   [Configuration steps for iOS and Android]
   
   ## API Usage
   
   [Detailed API usage examples]
   
   ## Complete Example
   
   [Full working example]
   
   ## Best Practices
   
   [Tips and best practices]
   
   ## Troubleshooting
   
   [Common issues and solutions]
   
   ## Conclusion
   
   [Summary and links to additional resources]

插件文档结构

必需文件

src/content/docs/docs/plugins/your-plugin-name/
├── index.mdx           # Overview page with hero and feature cards
└── getting-started.mdx # Installation and usage guide

src/content/plugins-tutorials/en/
└── your-plugin-name.md # Comprehensive tutorial

可选文件

对于复杂的插件，你可以添加额外的文档页面：

src/content/docs/docs/plugins/your-plugin-name/
├── index.mdx
├── getting-started.mdx
├── api-reference.mdx   # Detailed API documentation
├── examples.mdx        # Additional examples
├── troubleshooting.mdx # Troubleshooting guide
└── migrations.mdx      # Migration guides

内容指南

编写插件描述

• 保持简洁: 描述控制在 100 个字符以内
• 描述具体: 说明插件的功能，而非其定义
• 使用动词: 以 “Control”、“Integrate”、“Enable” 等动词开头

优秀示例:

• “通过简单的开关控制设备的闪光灯和手电筒”
• “将 Crisp 实时聊天和客户支持集成到您的应用中”
• “使用 Face ID 和 Touch ID 实现安全身份验证”

反面示例:

• “一个用于闪光灯的插件”
• “这是一个 Crisp 插件”
• “生物识别插件”

编写文档

1. 从安装步骤开始: 务必以清晰的安装步骤作为开头
2. 提供配置说明: 包含特定平台的配置要求
3. 展示使用示例: 提供可运行的 code 示例
4. 包含 API 参考文档: 记录所有方法和参数
5. 添加完整示例: 展示实际应用场景
6. 列出最佳实践: 分享优化使用的技巧
7. 记录平台差异: 明确 iOS 与 Android 的行为差异
8. 添加故障排除: 解决常见问题

Code 示例

• 所有 code 示例均使用 TypeScript
• 在顶部包含 import 语句
• 添加注释以解释关键步骤
• 展示错误处理机制
• 演示基础与进阶用法

清单

添加新插件时请参考此清单：

• 已将插件添加到 /src/config/plugins.ts
• 从 Heroicons 中选择了合适的图标
• 已将插件添加到 /src/content/docs/docs/plugins/index.mdx 至正确的分类下
• 已在侧边栏添加入口 /astro.config.mjs
• 已创建插件文档目录
• 已创建 index.mdx 概览页面
• 已创建 getting-started.mdx 指南
• Created tutorial in /src/content/plugins-tutorials/en/
• 包含安装指南
• 已编写 iOS 配置文档
• 完善 Android 配置文档
• 提供使用示例
• 添加 API 参考
• 包含完整的运行示例
• 列出最佳实践
• 添加平台特定说明
• 测试所有链接是否有效

图标参考

插件常用的图标（来自 astro-heroicons/mini/):

图标	使用场景
BoltIcon	闪光灯、电源、能量
CameraIcon	相机、照片、视频
ChatBubbleLeftIcon	聊天、消息、通信
FingerPrintIcon	生物识别、安全、身份验证
MapPinIcon	位置、地理定位、地图
SpeakerWaveIcon	音频、声音、音乐
VideoCameraIcon	视频、录制、流媒体
CreditCardIcon	支付、购买
PlayCircleIcon	媒体播放器、视频播放器
SignalIcon	连接、网络、信标
RadioIcon	信标、广播、无线
ChatBubbleOvalLeftIcon	社交媒体、微信

更新现有插件

更新现有插件时：

1. 更新版本号 并在文档中同步
2. 添加迁移指南 若存在破坏性变更
3. 更新 API 引用 并包含新方法
4. 添加新示例 以演示新功能
5. 更新平台版本要求 如有变更
6. 修订最佳实践 基于新功能
7. 保持教程时效性 使用最新的 API

语言路径

使用英文编写并审核插件文档。本地化路径由站点元数据生成，并通过 translation Worker 在边缘侧进行翻译。

测试你的更改

添加或更新插件文档后：

1. 在本地构建站点:

   bun run build

2. 检查错误:

   • 验证所有链接是否有效
   • 确保图片加载正常
   • 确认 code 示例有效
   • 测试导航功能

3. 预览网站:

   bun run dev

4. 确认你的插件已显示:

   • 检查插件列表页
   • 检查侧边栏导航
   • 测试所有文档页面
   • 确认教程页面正常运行

常见陷阱

注意

避免以下常见错误：

1. 忘记同步：务必运行 bunx cap sync 在示例中
2. 命名不一致: 在所有地方保持插件名称一致
3. 缺少平台配置: 需同时记录 iOS 和 Android 的配置步骤
4. 链接失效: 使用相对链接并确保其可用
5. 缺少错误处理: 示例代码中务必包含 try-catch
6. 缺少 import 语句: 示例中需包含所有必要的 import
7. 描述不清晰: 请具体说明插件的功能

获取帮助

如果你在添加或更新插件文档时需要帮助：

• Discord：加入我们的 Discord 社区
• GitHub：在 网站仓库上提交 issue
• 邮箱：联系团队： support@capgo.app

示例

可以参考这些文档齐全的插件：

• 更新器: /src/content/docs/docs/plugins/updater/ （包含多个页面的复杂插件）
• 闪光灯: /src/content/docs/docs/plugins/flash/ （简单插件，适合入门参考）
• 社交登录: /src/content/docs/docs/plugins/social-login/ （包含子页面的插件）

总结

在 Capgo 文档中添加插件需要：

1. 在主配置中添加元数据
2. 将插件添加到分类索引页
3. 配置侧边栏导航
4. 创建完善的文档页面
5. 编写详细的教程
6. 在本地测试所有更改

按照本指南操作，你可以确保插件文档保持一致，并让用户更容易找到它们。

继续阅读：添加或更新插件

如果你正在使用 添加或更新插件 要规划原生插件工作，请将其与 Capgo 插件目录 查看 Capgo 插件目录中的产品工作流， Capgo 提供的 Capacitor 插件 查看由 Capgo 提供的 Capacitor 插件中的实现细节， Ionic Enterprise 插件替代方案 用于 Ionic Enterprise 插件替代方案的产品工作流， Capgo Native Build 用于 Capgo Native Builds 的产品工作流，以及 Capacitor 插件：你需要知道的事 了解 Capacitor 插件的实际应用场景，请参阅：Capacitor Plugins: What You Need to Know。