pinyin-ruby 1.0.0

package/README.md

@@ -0,0 +1,180 @@
+# pinyin-ruby
+
+根据拼音规则生成带注音的Ruby标签的拼音工具（支持 HTML <ruby> 输出）
+
+## 安装
+
+```bash
+npm install pinyin-ruby
+```
+
+或使用 pnpm：
+
+```bash
+pnpm add pinyin-ruby
+```
+
+## 用法
+
+### 基础用法
+
+```typescript
+import { ruby } from 'pinyin-ruby';
+
+// 生成 HTML ruby 标签（默认）
+ruby('中文');
+// 输出: <ruby>中<rt>zhōng</rt></ruby><ruby>文<rt>wén</rt></ruby>
+
+// 生成纯文本格式
+ruby('中文', { format: 'text' });
+// 输出: 中(zhōng)文(wén)
+
+// 生成 XML 格式
+ruby('中文', { format: 'xml' });
+// 输出: <ruby><base>中</base><rt>zhōng</rt></ruby><ruby><base>文</base><rt>wén</rt></ruby>
+```
+
+### 自定义拼音风格
+
+```typescript
+// 不带声调
+ruby('中文', { style: 'normal' });
+// 输出: <ruby>中<rt>zhong</rt></ruby><ruby>文<rt>wen</rt></ruby>
+
+// 用数字标注声调
+ruby('中文', { style: 'tone2' });
+// 输出: <ruby>中<rt>zho1ng</rt></ruby><ruby>文<rt>we2n</rt></ruby>
+
+// 只获取首字母
+ruby('中文', { style: 'initials' });
+// 输出: <ruby>中<rt>zh</rt></ruby><ruby>文<rt>w</rt></ruby>
+
+// 只获取首字母（小写）
+ruby('中文', { style: 'first_letter' });
+// 输出: <ruby>中<rt>z</rt></ruby><ruby>文<rt>w</rt></ruby>
+```
+
+### 处理非中文字符
+
+```typescript
+// 默认跳过非中文字符
+ruby('hello中文world');
+// 输出: <ruby>中<rt>zhōng</rt></ruby><ruby>文<rt>wén</rt></ruby>
+
+// 保留非中文字符
+ruby('hello中文world', { skipNonChinese: false });
+// 输出: hello<ruby>中<rt>zhōng</rt></ruby><ruby>文<rt>wén</rt></ruby>world
+```
+
+### 处理多音字
+
+```typescript
+// 默认只返回第一个拼音
+ruby('行走', { format: 'text' });
+// 输出: 行(xíng)走(zǒu)
+
+// 返回所有拼音（用顿号分隔）
+rubyHeteonym('行走', { format: 'text' });
+// 输出: 行(xíng、háng)走(zǒu)
+```
+
+### 获取详细信息
+
+```typescript
+import { rubyDetails } from 'pinyin-ruby';
+
+const details = rubyDetails('中文');
+// 返回:
+// [
+//   {
+//     char: '中',
+//     pinyin: 'zhōng',
+//     isChinese: true,
+//     html: '<ruby>中<rt>zhōng</rt></ruby>',
+//     xml: '<ruby><base>中</base><rt>zhōng</rt></ruby>',
+//     text: '中(zhōng)'
+//   },
+//   {
+//     char: '文',
+//     pinyin: 'wén',
+//     isChinese: true,
+//     html: '<ruby>文<rt>wén</rt></ruby>',
+//     xml: '<ruby><base>文</base><rt>wén</rt></ruby>',
+//     text: '文(wén)'
+//   }
+// ]
+```
+
+## API 文档
+
+### `ruby(text, options?): string`
+
+将文本转换为带注音的 Ruby 标签。
+
+**参数：**
+- `text` - 输入的文本
+- `options` - 配置选项
+  - `format?: 'html' | 'xml' | 'text'` - Ruby 标签的格式（默认：'html'）
+  - `style?: string` - 拼音风格（详见 pinyin 文档）
+  - `heteronym?: boolean` - 是否返回多音字
+  - `skipNonChinese?: boolean` - 是否跳过非中文字符（默认：true）
+  - 其他选项参考 [pinyin](https://pinyin.js.org/) 库
+
+**返回值：**
+- 转换后的 Ruby 标签字符串
+
+### `rubyDetails(text, options?): RubyItem[]`
+
+获取文本的详细拼音和 Ruby 标签信息。
+
+**参数：**
+- `text` - 输入的文本
+- `options` - 配置选项
+
+**返回值：**
+- Ruby 标签详细信息数组，每项包含：
+  - `char` - 原始字符
+  - `pinyin` - 拼音
+  - `isChinese` - 是否是中文字符
+  - `html` - HTML 格式的 Ruby 标签
+  - `xml` - XML 格式的 Ruby 标签
+  - `text` - 纯文本格式
+
+### `rubyHeteonym(text, options?): string`
+
+生成支持多拼音的 Ruby 标签（多音字用顿号分隔）。
+
+**参数：**
+- `text` - 输入的文本
+- `options` - 配置选项
+
+**返回值：**
+- 支持多拼音的 Ruby 标签字符串
+
+## 拼音风格对照表
+
+| 风格 | 输入 | 输出示例 | 说明 |
+|------|------|---------|------|
+| `tone` | 中 | zhōng | 带声调（默认） |
+| `tone2` | 中 | zho1ng | 声调用数字标注在拼音中间 |
+| `to3ne` | 中 | zho3ng | 声调用数字标注在拼音末尾 |
+| `normal` | 中 | zhong | 不带声调 |
+| `initials` | 中 | ZH | 声母（大写） |
+| `first_letter` | 中 | Z | 首字母（大写） |
+| `passport` | 中 | ZHONG | 护照拼音（大写，无声调） |
+
+## 应用场景
+
+- **教学工具**：为汉字添加拼音注音，辅助儿童和外国学习者学习汉语
+- **文本处理**：批量为文档添加拼音
+- **Web 应用**：在网页上显示带拼音的汉字
+- **电子书**：为电子书内容添加拼音注音
+- **辅助阅读**：为生僻字和难字添加拼音辅助阅读
+
+## 与拼音库的关系
+
+`pinyin-ruby` 是基于 [pinyin](https://pinyin.js.org/) 库的扩展，提供了更便捷的 Ruby 标签生成功能。
+
+## License
+
+MIT

package/lib/cjs/index.js

@@ -0,0 +1,164 @@
+"use strict";
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ruby = ruby;
+exports.rubyDetails = rubyDetails;
+exports.rubyHeteonym = rubyHeteonym;
+const pinyin_1 = __importDefault(require("pinyin"));
+/**
+ * 生成单个字符的 Ruby 标签
+ */
+function generateRubyTag(char, py, format) {
+    if (!py || py.length === 0) {
+        return char;
+    }
+    const pinyinStr = py[0];
+    switch (format) {
+        case 'html':
+            return `<ruby>${char}<rt>${pinyinStr}</rt></ruby>`;
+        case 'xml':
+            return `<ruby><base>${char}</base><rt>${pinyinStr}</rt></ruby>`;
+        case 'text':
+            return `${char}(${pinyinStr})`;
+        default:
+            return `<ruby>${char}<rt>${pinyinStr}</rt></ruby>`;
+    }
+}
+/**
+ * 判断是否是中文字符
+ */
+function isChinese(char) {
+    const code = char.charCodeAt(0);
+    return code >= 0x4e00 && code <= 0x9fff;
+}
+/**
+ * 将文本转换为带注音的 Ruby 标签
+ * @param text - 输入的文本
+ * @param options - 配置选项
+ * @returns 转换后的 Ruby 标签字符串
+ *
+ * @example
+ * ```typescript
+ * import { ruby } from 'pinyin-ruby';
+ *
+ * // 默认生成 HTML ruby 标签
+ * ruby('中文');
+ * // 输出: <ruby>中<rt>zhōng</rt></ruby><ruby>文<rt>wén</rt></ruby>
+ *
+ * // 生成纯文本格式
+ * ruby('中文', { format: 'text' });
+ * // 输出: 中(zhōng)文(wén)
+ *
+ * // 自定义拼音风格
+ * ruby('中文', { style: 'normal' });
+ * // 输出: <ruby>中<rt>zhong</rt></ruby><ruby>文<rt>wen</rt></ruby>
+ * ```
+ */
+function ruby(text, options) {
+    if (!text) {
+        return '';
+    }
+    const _a = options || {}, { format = 'html', skipNonChinese = true } = _a, pinyinOptions = __rest(_a, ["format", "skipNonChinese"]);
+    const pinyinResult = (0, pinyin_1.default)(text, pinyinOptions);
+    const result = [];
+    for (let i = 0; i < text.length; i++) {
+        const char = text[i];
+        const py = pinyinResult[i];
+        if (!isChinese(char)) {
+            // 非中文字符的处理
+            if (!skipNonChinese) {
+                result.push(char);
+            }
+            continue;
+        }
+        result.push(generateRubyTag(char, py, format));
+    }
+    return result.join('');
+}
+/**
+ * 生成带注音的 Ruby 标签详细信息
+ * @param text - 输入的文本
+ * @param options - 配置选项
+ * @returns Ruby 标签详细信息数组
+ */
+function rubyDetails(text, options) {
+    if (!text) {
+        return [];
+    }
+    const pinyinOptions = Object.assign({}, options);
+    const pinyinResult = (0, pinyin_1.default)(text, pinyinOptions);
+    const result = [];
+    for (let i = 0; i < text.length; i++) {
+        const char = text[i];
+        const py = pinyinResult[i];
+        const chinese = isChinese(char);
+        const pinyinStr = chinese && py && py[0] ? py[0] : '';
+        result.push({
+            char,
+            pinyin: pinyinStr,
+            isChinese: chinese,
+            html: chinese ? generateRubyTag(char, py, 'html') : char,
+            xml: chinese ? generateRubyTag(char, py, 'xml') : char,
+            text: chinese ? generateRubyTag(char, py, 'text') : char,
+        });
+    }
+    return result;
+}
+/**
+ * 生成复杂的多拼音格式（支持多音字）
+ */
+function rubyHeteonym(text, options) {
+    if (!text) {
+        return '';
+    }
+    const _a = options || {}, { format = 'html', skipNonChinese = true } = _a, pinyinOptions = __rest(_a, ["format", "skipNonChinese"]);
+    const pinyinResult = (0, pinyin_1.default)(text, Object.assign(Object.assign({}, pinyinOptions), { heteronym: true }));
+    const result = [];
+    for (let i = 0; i < text.length; i++) {
+        const char = text[i];
+        const py = pinyinResult[i];
+        if (!isChinese(char)) {
+            if (!skipNonChinese) {
+                result.push(char);
+            }
+            continue;
+        }
+        if (!py || py.length === 0) {
+            result.push(char);
+            continue;
+        }
+        const pinyinStr = py.join('、');
+        switch (format) {
+            case 'html':
+                result.push(`<ruby>${char}<rt>${pinyinStr}</rt></ruby>`);
+                break;
+            case 'xml':
+                result.push(`<ruby><base>${char}</base><rt>${pinyinStr}</rt></ruby>`);
+                break;
+            case 'text':
+                result.push(`${char}(${pinyinStr})`);
+                break;
+            default:
+                result.push(`<ruby>${char}<rt>${pinyinStr}</rt></ruby>`);
+        }
+    }
+    return result.join('');
+}
+exports.default = {
+    ruby,
+    rubyDetails,
+    rubyHeteonym,
+};

package/lib/esm/index.js

@@ -0,0 +1,156 @@
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+import pinyin from 'pinyin';
+/**
+ * 生成单个字符的 Ruby 标签
+ */
+function generateRubyTag(char, py, format) {
+    if (!py || py.length === 0) {
+        return char;
+    }
+    const pinyinStr = py[0];
+    switch (format) {
+        case 'html':
+            return `<ruby>${char}<rt>${pinyinStr}</rt></ruby>`;
+        case 'xml':
+            return `<ruby><base>${char}</base><rt>${pinyinStr}</rt></ruby>`;
+        case 'text':
+            return `${char}(${pinyinStr})`;
+        default:
+            return `<ruby>${char}<rt>${pinyinStr}</rt></ruby>`;
+    }
+}
+/**
+ * 判断是否是中文字符
+ */
+function isChinese(char) {
+    const code = char.charCodeAt(0);
+    return code >= 0x4e00 && code <= 0x9fff;
+}
+/**
+ * 将文本转换为带注音的 Ruby 标签
+ * @param text - 输入的文本
+ * @param options - 配置选项
+ * @returns 转换后的 Ruby 标签字符串
+ *
+ * @example
+ * ```typescript
+ * import { ruby } from 'pinyin-ruby';
+ *
+ * // 默认生成 HTML ruby 标签
+ * ruby('中文');
+ * // 输出: <ruby>中<rt>zhōng</rt></ruby><ruby>文<rt>wén</rt></ruby>
+ *
+ * // 生成纯文本格式
+ * ruby('中文', { format: 'text' });
+ * // 输出: 中(zhōng)文(wén)
+ *
+ * // 自定义拼音风格
+ * ruby('中文', { style: 'normal' });
+ * // 输出: <ruby>中<rt>zhong</rt></ruby><ruby>文<rt>wen</rt></ruby>
+ * ```
+ */
+export function ruby(text, options) {
+    if (!text) {
+        return '';
+    }
+    const _a = options || {}, { format = 'html', skipNonChinese = true } = _a, pinyinOptions = __rest(_a, ["format", "skipNonChinese"]);
+    const pinyinResult = pinyin(text, pinyinOptions);
+    const result = [];
+    for (let i = 0; i < text.length; i++) {
+        const char = text[i];
+        const py = pinyinResult[i];
+        if (!isChinese(char)) {
+            // 非中文字符的处理
+            if (!skipNonChinese) {
+                result.push(char);
+            }
+            continue;
+        }
+        result.push(generateRubyTag(char, py, format));
+    }
+    return result.join('');
+}
+/**
+ * 生成带注音的 Ruby 标签详细信息
+ * @param text - 输入的文本
+ * @param options - 配置选项
+ * @returns Ruby 标签详细信息数组
+ */
+export function rubyDetails(text, options) {
+    if (!text) {
+        return [];
+    }
+    const pinyinOptions = Object.assign({}, options);
+    const pinyinResult = pinyin(text, pinyinOptions);
+    const result = [];
+    for (let i = 0; i < text.length; i++) {
+        const char = text[i];
+        const py = pinyinResult[i];
+        const chinese = isChinese(char);
+        const pinyinStr = chinese && py && py[0] ? py[0] : '';
+        result.push({
+            char,
+            pinyin: pinyinStr,
+            isChinese: chinese,
+            html: chinese ? generateRubyTag(char, py, 'html') : char,
+            xml: chinese ? generateRubyTag(char, py, 'xml') : char,
+            text: chinese ? generateRubyTag(char, py, 'text') : char,
+        });
+    }
+    return result;
+}
+/**
+ * 生成复杂的多拼音格式（支持多音字）
+ */
+export function rubyHeteonym(text, options) {
+    if (!text) {
+        return '';
+    }
+    const _a = options || {}, { format = 'html', skipNonChinese = true } = _a, pinyinOptions = __rest(_a, ["format", "skipNonChinese"]);
+    const pinyinResult = pinyin(text, Object.assign(Object.assign({}, pinyinOptions), { heteronym: true }));
+    const result = [];
+    for (let i = 0; i < text.length; i++) {
+        const char = text[i];
+        const py = pinyinResult[i];
+        if (!isChinese(char)) {
+            if (!skipNonChinese) {
+                result.push(char);
+            }
+            continue;
+        }
+        if (!py || py.length === 0) {
+            result.push(char);
+            continue;
+        }
+        const pinyinStr = py.join('、');
+        switch (format) {
+            case 'html':
+                result.push(`<ruby>${char}<rt>${pinyinStr}</rt></ruby>`);
+                break;
+            case 'xml':
+                result.push(`<ruby><base>${char}</base><rt>${pinyinStr}</rt></ruby>`);
+                break;
+            case 'text':
+                result.push(`${char}(${pinyinStr})`);
+                break;
+            default:
+                result.push(`<ruby>${char}<rt>${pinyinStr}</rt></ruby>`);
+        }
+    }
+    return result.join('');
+}
+export default {
+    ruby,
+    rubyDetails,
+    rubyHeteonym,
+};

package/lib/types/index.d.ts

@@ -0,0 +1,80 @@
+import type { IPinyinOptions } from 'pinyin/lib/types/declare';
+/**
+ * Ruby 标签的类型定义
+ */
+export interface RubyOptions extends IPinyinOptions {
+    /**
+     * Ruby 标签的格式
+     * 'html': 生成 HTML ruby 标签
+     * 'xml': 生成 XML 格式
+     * 'text': 生成纯文本格式，用于控制台显示
+     */
+    format?: 'html' | 'xml' | 'text';
+    /**
+     * 是否分组处理（将单个汉字的拼音合并）
+     */
+    group?: boolean;
+    /**
+     * 是否跳过非中文字符
+     */
+    skipNonChinese?: boolean;
+}
+/**
+ * 将文本转换为带注音的 Ruby 标签
+ * @param text - 输入的文本
+ * @param options - 配置选项
+ * @returns 转换后的 Ruby 标签字符串
+ *
+ * @example
+ * ```typescript
+ * import { ruby } from 'pinyin-ruby';
+ *
+ * // 默认生成 HTML ruby 标签
+ * ruby('中文');
+ * // 输出: <ruby>中<rt>zhōng</rt></ruby><ruby>文<rt>wén</rt></ruby>
+ *
+ * // 生成纯文本格式
+ * ruby('中文', { format: 'text' });
+ * // 输出: 中(zhōng)文(wén)
+ *
+ * // 自定义拼音风格
+ * ruby('中文', { style: 'normal' });
+ * // 输出: <ruby>中<rt>zhong</rt></ruby><ruby>文<rt>wen</rt></ruby>
+ * ```
+ */
+export declare function ruby(text: string, options?: RubyOptions): string;
+/**
+ * 生成带注音的 Ruby 标签（仅处理中文字符）
+ * 返回数组格式，便于进一步处理
+ */
+export interface RubyItem {
+    /** 原始字符 */
+    char: string;
+    /** 拼音 */
+    pinyin: string;
+    /** 是否是中文字符 */
+    isChinese: boolean;
+    /** 生成的 Ruby HTML 标签 */
+    html: string;
+    /** 生成的 Ruby XML 格式 */
+    xml: string;
+    /** 生成的纯文本格式 */
+    text: string;
+}
+/**
+ * 生成带注音的 Ruby 标签详细信息
+ * @param text - 输入的文本
+ * @param options - 配置选项
+ * @returns Ruby 标签详细信息数组
+ */
+export declare function rubyDetails(text: string, options?: RubyOptions): RubyItem[];
+/**
+ * 生成复杂的多拼音格式（支持多音字）
+ */
+export declare function rubyHeteonym(text: string, options?: RubyOptions): string;
+declare const _default: {
+    ruby: typeof ruby;
+    rubyDetails: typeof rubyDetails;
+    rubyHeteonym: typeof rubyHeteonym;
+};
+export default _default;

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "pinyin-ruby",
+  "version": "1.0.0",
+  "description": "生成带注音的Ruby标签的拼音工具（支持 HTML <ruby> 输出）",
+  "types": "./lib/types/index.d.ts",
+  "main": "./lib/cjs/index.js",
+  "module": "./lib/esm/index.js",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "import": "./lib/esm/index.js",
+      "require": "./lib/cjs/index.js"
+    }
+  },
+  "files": [
+    "lib"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json && tsc -p tsconfig.esm.json",
+    "test": "jest",
+    "dev": "tsc -p tsconfig.json --watch"
+  },
+  "peerDependencies": {
+    "pinyin": ">=4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0",
+    "pinyin": "^4.0.0"
+  },
+  "keywords": [
+    "pinyin",
+    "ruby",
+    "annotation",
+    "汉字",
+    "拼音",
+    "注音"
+  ],
+  "author": "mkoplqq2006",
+  "license": "MIT"
+}
+