enum-plus/docs/plugin-development.zh-CN.md

A drop-in replacement for native enum. Like native enum but much better!

# 插件开发指南

本指南提供了如何为 enum-plus 库开发插件的全面概述。它涵盖了必要的步骤、最佳实践和示例，帮助你创建增强 enum-plus 功能的插件。

## 开始之前

在开始插件开发之前，你需要对 enum-plus 库及其核心概念有基本的了解。请熟悉 [文档](../README.md)，并探索现有插件以了解它们的结构。

你需要判断插件的通用性，以决定是否应该维护在enum-plus官方仓库中，还是作为第三方插件独立维护。如果插件的功能符合：

1. **开放性**：基于公开的框架或技术，即非某个公司或组织的私有技术
2. **通用性**：用于使用此技术的大多数用户
3. **相关性**：与枚举库的概念密切相关

那么它可能适合维护在官方仓库中，请继续阅读本指南后面的内容。否则，可能更适合作为第三方插件独立维护。

对于第三方插件，你可以参考本指南中的内容，也可以不遵循本指南，但请确保插件的质量和文档清晰。请把插件发布到 npm，并把你的插件链接分享到这里 [插件生态](../README.zh-CN.md#插件生态)，让更多人知道你的插件。

> 官方插件或第三方插件对于我们来说同等重要，我们欢迎任何有价值的插件。

## 插件结构

> 你可以参考 [plugin-sample](https://github.com/shijistar/enum-plus/tree/main/packages/plugin-sample) 以获取完整示例。

一个典型的 enum-plus 插件由以下组件组成：

1. **插件元数据**：有关插件的信息，例如名称、版本和描述。它们定义在 `package.json` 文件中。
2. **核心功能**：插件的主要逻辑，扩展或修改 enum-plus 的行为，它们放置于 `src` 目录中。请遵循以下指南：
   1. 请使用 TypeScript 开发插件。
   2. 编写类型声明，扩展 `EnumExtension` 类型。确保方法签名与功能实现一致。请记住，`类型声明`与`功能实现`同样重要。
   3. 应该让插件的功能更明确、内聚，与插件的名称保持一致。不得包含无关的功能，其它功能应该在新插件中实现。
   4. 为函数和变量使用有意义的名称，以增强代码可读性。
   5. 确保 `package.json` 中 `peerDependencies` 字段指定的目标版本的 enum-plus 兼容。
   6. 如果可能，输出代码应兼容 `ES2015` 及以上版本。无论如何，至少应该向下兼容到 `ES2020`。
3. **插件选项**：可选地，你可以为用户提供配置选项，以自定义插件的行为。请遵循以下模式以获得更好的灵活性：
   1. 避免硬编码值，应该使用选项以允许用户自定义插件的行为。
   2. 为选项提供合理的默认值，以确保插件开箱即用。
   3. 校验选项值，以确保它们具有正确的类型并在可接受范围内。
4. **文档**：请为你的插件提供清晰简明的文档，包括安装说明、使用示例和 API 参考。这可以在 `README.md` 文件中完成。如果可能，请用英语和中文两种语言编写文档。如果只能选择一种语言，请选择英语，因为它是默认语言。
5. **测试**：实现测试以确保插件按预期工作。你需要为 `Jest` 编写测试。请遵循以下指南：
   1. 为每个函数和组件编写单元测试。
   2. 测试覆盖率应确保达到 `100%`，以确保所有关键路径都经过测试。
   3. 使用有意义的测试名称来描述每个测试的目的。

## 插件发布

当你的插件准备好后，你可以将其发布到 npm。请遵循以下步骤：

1. 确保你的 `package.json` 文件已正确配置，包含必要的元数据和依赖项。
2. 使用 `npm run build` 命令构建插件。
3. 使用 `npm run test` 命令测试构建的插件，以确保其按预期工作。
4. 在发布之前添加标签。标签应采用 `plugin-{plugin-name}@{version}` 格式，例如 `plugin-sample@1.0.0`。请勿使用 `vx.x.x` 格式，因为这种格式被 enum-plus 核心库保留使用。
5. 在 enum-plus 存储库的 [Releases](https://github.com/shijistar/enum-plus/releases) 部分创建新版本。发布名称应与你在上一步中创建的标签相同。
   1. 请勿在没有 enum-plus 仓库中创建发布的情况下，直接将插件发布到 npm。
   2. 请勿使用 `npm publish` 命令手动发布插件。
6. 定期关注 [Issues](https://github.com/shijistar/enum-plus/issues) 频道，以获取用户的反馈或错误报告。请对与你的插件相关的问题做出回应。