# fanti

轻量级简繁体中文转换工具，ESM、CJS、IIFE 三种模块格式。

[![npm](https://img.shields.io/npm/v/fanti)](https://www.npmjs.com/package/fanti)
[![License](https://img.shields.io/npm/l/fanti)](https://github.com/doubao/fanti/blob/main/LICENSE)

## 特性

- 🔄 简体 ↔ 繁体双向转换
- 📦 支持 ESM、CJS、IIFE 三种模块格式
- 🌐 浏览器环境自动暴露全局变量 `fanti`
- 📝 完整 TypeScript 类型定义
- 🚀 无依赖，体积仅 ~15KB（gzip 后 ~5KB）
- 🔍 提供繁体字检测功能

## 安装

```bash
# npm
npm install fanti

# yarn
yarn add fanti

# pnpm
pnpm add fanti
```

## 快速使用

### 1. ESM (浏览器/Node.js)

```typescript
import { toFanti, toJianti, isFanti } from 'fanti';

// 简体转繁体
console.log(toFanti('简体中文转繁体')); // 输出: 簡體中文轉繁體

// 繁体转简体
console.log(toJianti('繁體中文轉簡體')); // 输出: 繁体中文转简体

// 判断是否为繁体字
console.log(isFanti('轉')); // true
console.log(isFanti('转')); // false
```

### 2. CJS (Node.js)

```javascript
const { toFanti, toJianti } = require('fanti');

console.log(toFanti('CommonJS 模块测试')); // 输出: CommonJS 模組測試
```

### 3. IIFE (浏览器全局变量)

```html
<!-- 通过 CDN 引入 -->
<script src="https://unpkg.com/fanti@latest/dist/fanti.iife.js"></script>

<!-- 或本地引入 -->
<script src="./node_modules/fanti/dist/fanti.iife.js"></script>

<script>
  // 通过全局变量 fanti 访问
  console.log(fanti.toFanti('全局变量使用')); // 输出: 全局變量使用
  console.log(fanti.toJianti('IIFE 格式測試')); // 输出: IIFE 格式测试
</script>
```

## API 文档

### `toFanti(text: string): string`

将简体中文转换为繁体中文。

- **参数**：`text` - 待转换的简体字符串（非字符串类型会抛出 `TypeError`）
- **返回**：转换后的繁体字符串
- **示例**：
  ```typescript
  console.log(toFanti('你好，世界')); // 输出: 你好，世界
  ```

### `toJianti(text: string): string`

将繁体中文转换为简体中文。

- **参数**：`text` - 待转换的繁体字符串（非字符串类型会抛出 `TypeError`）
- **返回**：转换后的简体字符串
- **示例**：
  ```typescript
  console.log(toJianti('臺灣')); // 输出: 台湾
  ```

### `isFanti(char: string): boolean`

判断单个字符是否为繁体字。

- **参数**：`char` - 待检测的单个字符（非单字符会抛出 `TypeError`）
- **返回**：`true` 表示是繁体字，`false` 表示不是
- **示例**：
  ```typescript
  console.log(isFanti('灣')); // true
  console.log(isFanti('湾')); // false
  ```

## 模块文件说明

安装后可在 `node_modules/fanti/dist` 目录获取以下文件：

| 文件             | 模块类型 | 适用场景                  |
|------------------|----------|---------------------------|
| `fanti.esm.js`   | ESM      | 现代前端工程化项目        |
| `fanti.cjs.js`   | CJS      | Node.js 项目              |
| `fanti.iife.js`  | IIFE     | 传统 HTML 页面、全局变量使用 |
| `fanti.d.ts`     | TypeScript | 类型定义文件              |

## 注意事项

- 转换规则基于现代汉语常用字表，覆盖日常用字 99.9%。
- 古汉语专用字、生僻字可能转换不准确，如需专业级转换可扩展映射表。
- 标点符号、数字、字母等非中文字符将原样保留。
- 简繁同形字（如“数学”、“计算机”）不发生转换。

## 示例场景

### 批量转换文本

```typescript
import { toFanti } from 'fanti';

const sentences = ['简体测试', '繁體測試'];
const convertedSentences = sentences.map((text) => toFanti(text));
console.log(convertedSentences); // 输出: ['簡體測試', '繁體測試']
```

### React 集成示例

```typescript
import React from 'react';
import { toFanti } from 'fanti';

const App = () => {
  const text = '简体中文转繁体';
  return <div>{toFanti(text)}</div>;
};

export default App;
```

## 版本更新

查看 [CHANGELOG.md](https://github.com/doubao/fanti/blob/main/CHANGELOG.md) 了解版本迭代记录。

## 问题反馈

如遇转换错误或功能建议，请在 [GitHub Issues](https://github.com/doubao/fanti/issues) 提交反馈。

## 贡献指南

欢迎提交 Pull Request 或 Issue！请遵循以下规范：

- 代码风格：遵循 Prettier 格式化规则。
- 提交信息：采用 [Conventional Commits](https://www.conventionalcommits.org/) 规范。
- 测试：确保新增功能有对应的单元测试。

## 许可证

MIT © 2025