@airpower/enum 2.5.1 → 2.7.0

package/README.md

@@ -1,615 +1,90 @@
 <p align="center">
-  <img width="300" src="./assets/airpower-bg.svg" alt="AirPower-Enum Logo"/>
-</p>
-
-<h1 align="center">AirPower-Enum</h1>
-
-<p align="center">
-  <strong>基于 TypeScript 的 Java 风格枚举字典处理工具</strong>
+  <img width="300" src="./assets/airpower-bg.svg"/>
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/@airpower/enum">
-    <img src="https://img.shields.io/npm/v/@airpower/enum" alt="NPM Version"/>
-  </a>
-  <a href="https://www.npmjs.com/package/@airpower/enum">
-    <img src="https://img.shields.io/npm/dm/@airpower/enum" alt="NPM Downloads"/>
-  </a>
-  <a href="https://github.com/AirPowerTeam/AirPower-Enum/blob/main/LICENSE">
-    <img src="https://img.shields.io/npm/l/@airpower/enum" alt="License"/>
-  </a>
-  <a href="https://www.npmjs.com/package/@airpower/enum">
-    <img src="https://img.shields.io/bundlephobia/min/@airpower/enum" alt="Minified Size"/>
-  </a>
+<a href="https://www.npmjs.com/@airpower/enum">
+<img src="https://img.shields.io/npm/v/@airpower/enum"/>
+</a>
+<a href="https://www.npmjs.com/@airpower/enum">
+<img src="https://img.shields.io/npm/dm/@airpower/enum"/>
+</a>
 </p>
 
 <p align="center">
-  <a href="https://github.com/AirPowerTeam/AirPower-Enum">GitHub</a> ·
-  <a href="https://gitee.com/air-power/AirPower-Enum">Gitee</a> ·
-  <a href="https://www.npmjs.com/package/@airpower/enum">NPM</a>
+<a href="https://github.com/AirPowerTeam/AirPower-Enum">Github</a> /
+<a href="https://gitee.com/air-power/AirPower-Enum">Gitee</a> /
+<a href="https://www.npmjs.com/package/@airpower/enum">NPM</a>
 </p>
 
----
-
-## 📖 目录
-
-- [项目介绍](#-项目介绍)
-- [特性亮点](#-特性亮点)
-- [安装](#-安装)
-- [快速开始](#-快速开始)
-- [API 文档](#-api-文档)
-- [高级用法](#-高级用法)
-- [类型定义](#-类型定义)
-- [构建与开发](#-构建与开发)
-- [常见问题](#-常见问题)
-- [贡献指南](#-贡献指南)
-- [许可证](#-许可证)
-
----
-
 ## 🎉 项目介绍
 
-**AirPower-Enum** 是一个基于 TypeScript 开发的轻量级枚举字典处理工具库，采用类似 Java 枚举的设计模式，为 TypeScript
-项目提供类型安全、功能丰富的枚举操作体验。
-
-通过面向对象的封装，AirPower-Enum 让 TypeScript 枚举不再局限于简单的键值对，而是支持自定义属性、扩展方法、类型推断等高级特性，使代码更加优雅、可维护。
-
----
-
-## ✨ 特性亮点
-
-- 🎯 **Java 风格枚举**：采用经典的 Java 枚举设计模式，熟悉 Java 的开发者可快速上手
-- 🔒 **类型安全**：完整的 TypeScript 泛型支持，提供精确的类型推断和检查
-- 🎨 **多类型支持**：支持 `number`、`string`、`boolean` 三种类型的枚举键
-- 🧩 **可扩展性**：支持自定义属性、方法，可灵活扩展枚举功能
-- 📦 **零依赖**：纯 TypeScript 实现，无任何运行时依赖
-- 🚀 **轻量级**：极小的包体积，不影响项目打包大小
-- 📝 **完整类型声明**：提供完整的 `.d.ts` 类型定义文件
-- 🛠️ **现代化工具链**：基于 Vite 构建，支持 ES Modules
-
----
+**AirPower-Enum** 是一个基于 `TypeScript` 的封装的类似 `Java` 枚举类的枚举字典处理工具。
 
-## 📥 安装
+## 💻 如何安装
 
-### 使用 npm
-
-```bash
+```shell
 npm install @airpower/enum
-```
-
-### 使用 yarn
-
-```bash
+# or
 yarn add @airpower/enum
-```
-
-### 使用 cnpm
-
-```bash
+# or
 cnpm install @airpower/enum
+# or ...
 ```
 
-### 使用 pnpm
-
-```bash
-pnpm add @airpower/enum
-```
-
----
-
-## 🚀 快速开始
-
-### 基础用法
+## 📖 如何使用
 
-#### 数字枚举
-
-```typescript
-import { Enum } from '@airpower/enum'
+```ts
+import type { EnumConstructor } from './enum'
+import { Enum } from './enum'
 
+// 普通数字枚举
 class UserStatus extends Enum {
   static readonly NORMAL = new UserStatus(0, '正常')
   static readonly DISABLED = new UserStatus(1, '禁用')
 }
 
-// 使用示例
-console.log(UserStatus.NORMAL.key) // 输出：0
-console.log(UserStatus.NORMAL.label) // 输出：正常
-```
-
-#### 字符串枚举
-
-```typescript
-import { Enum } from '@airpower/enum'
-
+// 字符串枚举（支持数字、字符串、布尔值）
 class UserGender extends Enum<string> {
   static readonly MALE = new UserGender('MALE', '男')
   static readonly FEMALE = new UserGender('FEMALE', '女')
 }
 
-// 使用示例
-console.log(UserGender.MALE.key) // 输出：MALE
-console.log(UserGender.FEMALE.label) // 输出：女
-```
-
-#### 布尔值枚举
-
-```typescript
-import { Enum } from '@airpower/enum'
-
-class SwitchState extends Enum<boolean> {
-  static readonly ON = new SwitchState(true, '开启')
-  static readonly OFF = new SwitchState(false, '关闭')
-}
-```
-
----
-
-## 📚 API 文档
-
-### 类：`Enum<K>`
-
-枚举基类，所有自定义枚举类需继承此类。
-
-#### 构造函数
-
-```typescript
-constructor(key
-:
-K, label ? : string
-)
-```
-
-| 参数      | 类型       | 必填 | 说明                                  |
-|---------|----------|----|-------------------------------------|
-| `key`   | `K`      | 是  | 枚举键值，支持 `number`、`string`、`boolean` |
-| `label` | `string` | 否  | 枚举描述标签                              |
-
-#### 实例属性
-
-| 属性      | 类型       | 说明        |
-|---------|----------|-----------|
-| `key`   | `K`      | 枚举的值（只读）  |
-| `label` | `string` | 枚举的描述（可选） |
-
-#### 实例方法
-
-##### `equalsKey(key: EnumKey): boolean`
-
-判断实例的 `key` 是否与传入的键值相等。
-
-```typescript
-UserStatus.NORMAL.equalsKey(0) // true
-UserStatus.NORMAL.equalsKey(1) // false
-```
-
----
-
-### 静态方法
-
-#### `Enum.get<K, E>(key: K): E | null`
-
-通过键值查找对应的枚举实例。
-
-```typescript
-const status = UserStatus.get(0)
-console.log(status?.label) // 输出：正常
-```
-
-**泛型参数：**
-
-- `K`：枚举键类型
-- `E`：枚举实例类型（继承自 `Enum<K>`）
-
----
-
-#### `Enum.getLabel<K, E>(key: K, defaultLabel?: string): string`
-
-获取指定键值的枚举标签，如不存在则返回默认值。
-
-```typescript
-UserStatus.getLabel(0) // 输出：正常
-UserStatus.getLabel(999, '未知') // 输出：未知
-UserStatus.getLabel(999) // 输出：-
-```
-
-**参数说明：**
-
-| 参数             | 类型       | 必填 | 默认值   | 说明   |
-|----------------|----------|----|-------|------|
-| `key`          | `K`      | 是  | -     | 枚举键值 |
-| `defaultLabel` | `string` | 否  | `'-'` | 默认标签 |
-
----
-
-#### `Enum.toArray<K, E>(): E[]`
-
-将所有枚举实例转换为数组。
-
-```typescript
-const allStatus = UserStatus.toArray()
-// 输出：[UserStatus { key: 0, label: '正常' }, UserStatus { key: 1, label: '禁用' }]
-
-// 常用于遍历或下拉选项
-allStatus.forEach((item) => {
-  console.log(`${item.key}: ${item.label}`)
-})
-```
-
----
-
-## 🔧 高级用法
-
-### 自定义属性
-
-通过扩展构造函数，可以为枚举添加自定义属性：
-
-```typescript
-import type { EnumConstructor } from '@airpower/enum'
-import { Enum } from '@airpower/enum'
-
+// 扩展自定义属性
 class Platform extends Enum<number> {
-  static readonly MAC = new Platform(1, 'macOS', 'apple.png', '#000')
-  static readonly WINDOWS = new Platform(2, 'Windows', 'windows.png', '#0078D4')
-  static readonly ANDROID = new Platform(3, 'Android', 'android.png', '#3DDC84')
-  static readonly LINUX = new Platform(4, 'Linux', 'linux.png', '#FCC624')
+  static readonly MAC = new Platform(1, 'mac', 'apple.png')
+  static readonly WINDOWS = new Platform(2, 'windows', 'windows.png')
+  static readonly ANDROID = new Platform(3, 'android', 'android.png')
 
   // 自定义属性
   icon!: string
-  color!: string
 
-  constructor(key: number, label?: string, icon?: string, color?: string) {
+  // 1. 通过构造初始化（此时可以设置icon为readonly）
+  constructor(key: number, label?: string, icon?: string) {
     super(key, label)
-    if (icon)
+    if (icon) {
       this.icon = icon
-    if (color)
-      this.color = color
-  }
-}
-
-// 使用自定义属性
-console.log(Platform.MAC.icon) // 输出：apple.png
-console.log(Platform.WINDOWS.color) // 输出：#0078D4
-```
-
----
-
-### 自定义方法
-
-可以在枚举类中定义实例方法和静态方法：
-
-```typescript
-class Priority extends Enum<number> {
-  static readonly LOW = new Priority(1, '低优先级')
-  static readonly MEDIUM = new Priority(2, '中优先级')
-  static readonly HIGH = new Priority(3, '高优先级')
-  static readonly CRITICAL = new Priority(4, '紧急')
-
-  // 实例方法：判断是否为高优先级
-  isHighPriority(): boolean {
-    return this.key >= 3
-  }
-
-  // 实例方法：获取优先级图标
-  getIcon(): string {
-    const icons: Record<number, string> = {
-      1: '🟢',
-      2: '🟡',
-      3: '🟠',
-      4: '🔴'
     }
-    return icons[this.key] || '⚪'
-  }
-
-  // 静态方法：获取所有高优先级项
-  static getHighPriorities(): Priority[] {
-    return this.toArray().filter(p => p.isHighPriority())
-  }
-}
-
-// 使用示例
-console.log(Priority.HIGH.getIcon()) // 输出：🟠
-console.log(Priority.LOW.isHighPriority()) // 输出：false
-console.log(Priority.getHighPriorities()) // 输出：[HIGH, CRITICAL]
-```
-
----
-
-### 链式调用
-
-通过返回 `this` 实现链式调用：
-
-```typescript
-class Config extends Enum<string> {
-  static readonly DEBUG = new Config('DEBUG', '调试模式')
-  static readonly RELEASE = new Config('RELEASE', '发布模式')
-
-  enabled!: boolean
-  timeout!: number
-
-  setEnabled(enabled: boolean): this {
-    this.enabled = enabled
-    return this
   }
 
-  setTimeout(timeout: number): this {
-    this.timeout = timeout
+  // 2. 通过 set 方法初始化
+  setIcon(icon: string) {
+    this.icon = icon
     return this
   }
-}
-
-// 链式调用
-Config.DEBUG.setEnabled(true).setTimeout(3000)
-```
-
----
-
-### 类型安全的高级用法
-
-使用 `EnumConstructor` 类型来编写泛型工具函数：
-
-```typescript
-import type { EnumConstructor } from '@airpower/enum'
-import { Enum } from '@airpower/enum'
-
-/**
- * 通用的枚举选择器组件（以 Vue 3 为例）
- */
-function useEnumSelector<K extends string | number | boolean, E extends Enum<K>>(
-  EnumClass: EnumConstructor<K, E>
-) {
-  const options = EnumClass.toArray()
 
-  const getLabel = (key: K): string => {
-    return EnumClass.getLabel(key, '未知选项')
-  }
-
-  const isSelected = (current: K, target: K): boolean => {
-    return current === target
-  }
-
-  return {
-    options,
-    getLabel,
-    isSelected
+  static getIcon(this: EnumConstructor<number, Platform>, key: number) {
+    return this.get(key)!.icon
   }
 }
 
-// 使用示例
-const { options, getLabel } = useEnumSelector(UserStatus)
-```
-
----
-
-## 📝 类型定义
-
-### `EnumKey`
-
-枚举键的允许类型：
-
-```typescript
-type EnumKey = string | number | boolean
+console.warn(Platform.getIcon(1))
+console.warn(Platform.MAC.icon)
+console.warn(Platform.MAC.equalsKey(2))
 ```
 
----
-
-### `IEnum<K>`
+## ⏰ 欢迎反馈
 
-标准枚举字典接口：
+如有疑问，可以通过本仓库的 **Issues** 与我们联系，如果你有一些代码贡献，可以通过 **Pull Request** 将代码贡献，为这个项目添砖加瓦。
 
-```typescript
-interface IEnum<K extends EnumKey = number> {
-  key: K
-  label?: string
-}
-```
-
----
-
-### `EnumConstructor<K, E>`
-
-枚举类构造器类型：
-
-```typescript
-type EnumConstructor<K extends EnumKey = number, E extends Enum<K> = Enum<K>> = {
-  new(...args: any[]): E
-} & typeof Enum<K>
-```
-
----
-
-## 🛠️ 构建与开发
-
-### 环境要求
-
-- Node.js >= 16.0.0
-- npm >= 7.0.0 或 yarn >= 1.22.0
-
-### 克隆项目
-
-```bash
-git clone https://github.com/AirPowerTeam/AirPower-Enum.git
-cd AirPower-Enum
-```
-
-### 安装依赖
-
-```bash
-npm install
-# 或
-yarn install
-```
-
-### 构建项目
-
-```bash
-npm run build
-# 或
-yarn build
-```
-
-构建脚本执行流程：
-
-1. **ESLint 代码检查** - 确保代码质量
-2. **TypeScript 编译** - 类型检查
-3. **Vite 打包** - 生成 `dist/` 目录
-
-### 构建输出
-
-```
-dist/
-├── main.js          # ES Modules 格式的主文件
-├── index.d.ts       # 类型声明入口
-└── enum/
-    ├── Enum.d.ts    # Enum 类类型定义
-    ├── IEnum.d.ts   # IEnum 接口类型定义
-    └── type.d.ts    # 类型定义
-```
-
----
-
-## ❓ 常见问题
-
-### Q1: 为什么不用 TypeScript 原生 `enum`？
-
-TypeScript 原生 `enum` 存在以下限制：
-
-- 不支持自定义属性和方法
-- 编译后可能产生额外的运行时代码
-- 类型推断不够灵活
-- 不支持泛型
-
-AirPower-Enum 通过类的方式完美解决这些问题。
-
----
-
-### Q2: 如何与前端框架（Vue/React）配合使用？
-
-```typescript
-// Vue 3 示例
-<template>
-    <el-select
-v - model = "status" >
-    <el-option
-v -
-for= "item in UserStatus.toArray()"
-    :
-key = "item.key"
-:
-label = "item.label"
-:
-value = "item.key"
-    / >
-    </el-select>
-    < /template>
-
-    < script
-setup
-lang = "ts" >
-import {ref} from 'vue'
-import {UserStatus} from './enums/UserStatus'
-
-const status = ref(UserStatus.NORMAL.key)
-    < /script>
-```
-
-```typescript
-// React 示例
-function StatusSelect() {
-    const [status, setStatus] = useState(UserStatus.NORMAL.key)
-
-    return (
-        <select value = {status}
-    onChange = {e
-=>
-    setStatus(Number(e.target.value))
-}>
-    {
-        UserStatus.toArray().map(item => (
-            <option key = {item.key}
-        value = {item.key} >
-            {item.label}
-            < /option>
-    ))
-    }
-    </select>
-)
-}
-```
-
----
-
-### Q3: 如何处理枚举的序列化/反序列化？
-
-```typescript
-// 序列化
-const json = JSON.stringify(UserStatus.NORMAL)
-// 输出：{"key":0,"label":"正常"}
-
-// 反序列化
-const data = { key: 0, label: '正常' }
-const status = UserStatus.get(data.key)
-```
-
----
-
-### Q4: 支持常量枚举（const enum）吗？
-
-本库采用运行时类实现，不支持 `const enum`。但这也带来了更好的调试体验和运行时灵活性。
-
----
-
-## 🤝 贡献指南
-
-我们欢迎各种形式的贡献！
-
-### 提交 Issue
-
-遇到问题或有新需求时，欢迎通过 [GitHub Issues](https://github.com/AirPowerTeam/AirPower-Enum/issues) 反馈。
-
-### 提交 PR
-
-1. Fork 本仓库
-2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
-3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
-4. 推送到分支 (`git push origin feature/AmazingFeature`)
-5. 创建 Pull Request
-
-### 开发规范
-
-- 遵循项目的 ESLint 规则
-- 使用 TypeScript 严格模式
-- 为新增功能添加类型定义
-- 保持代码风格一致
-
-### 版本发布自动化流程
-
-- 使用 `eslint --fix` 修复项目中可能出现的问题
-- 更新 `package.json` 中的版本号
-- 使用 `yarn build` 构建项目
-- 使用 `npm publish` 发布包
-- 使用 `git add/commit/push` 将本地所有变更的文件推送到 Github
-
-### 联系方式
-
-- QQ 群：555156313
-- Email：admin@hamm.cn
-
----
-
-## 📄 许可证
-
-本项目采用 [MIT 许可证](LICENSE) 开源。
----
-
-## 👥 团队信息
-
-- **作者**：Hamm
-- **邮箱**：admin@hamm.cn
-- **GitHub**：[@HammCn](https://github.com/HammCn)
-- **团队**：[AirPower Team](https://github.com/AirPowerTeam)
-
----
-
-<p align="center">
-  如果这个项目对你有帮助，欢迎给一个 ⭐️ Star 支持！
-</p>
+如果有更多的需求和建议，欢迎通过本仓库的 `Issues` 提出，也欢迎加入 QQ群 555156313 与我们及时反馈。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@airpower/enum",
   "type": "module",
-  "version": "2.5.1",
+  "version": "2.7.0",
   "description": "AirPower-Enum 是一个基于 TypeScript 的封装的类似 Java 枚举类的枚举字典处理工具。",
   "author": {
     "name": "Hamm",
@@ -34,7 +34,7 @@
     "dist"
   ],
   "scripts": {
-    "build": "eslint src && tsc && vite build"
+    "build": "eslint && tsc && vite build"
   },
   "dependencies": {},
   "devDependencies": {