wg-random-name 随机姓名生成器 (Random Name Generator)

一个功能强大的多语言随机姓名和昵称生成器，支持生成各种类型的随机名称。

特性

• 🎯 随机昵称生成 - 生成有趣的随机昵称
• 👨‍👩‍👧‍👦 姓名生成 - 支持男性、女性和通用姓名生成
• 🏮 中文支持 - 完全支持中文姓氏和名字
• 📚 丰富词库 - 包含大量的形容词、名词和姓氏数据
• 🔧 灵活配置 - 支持单姓和复姓选择
• 📦 轻量级 - 无外部依赖，体积小巧
• 🔷 TypeScript 支持 - 完整的类型定义和接口支持
• 🌐 多模块格式 - 支持 ESM、CJS、UMD 多种模块格式
• 🎨 多种风格 - 支持传统、现代、文艺、古风等多种姓名风格
• 😊 昵称风格 - 支持可爱、搞笑、网络、霸气、清新、二次元等昵称风格
• 🛠️ 自定义配置 - 支持添加自定义姓氏、名字和昵称数据
• 📊 批量生成 - 支持批量生成姓名和昵称
• 🌍 多语言支持 - 支持中文、英文、日语、韩语等多种语言昵称

安装

pnpm install wg-random-name

使用方法

TypeScript / ES6 模块导入

import randomName, {
    RandomName,
    IRandomName,
    NameStyle,
    NickStyle,
    Language,
    CustomConfig,
} from "wg-random-name";

// 使用默认实例
console.log(randomName.getNickName()); // 输出: "快乐的小猫咪"
console.log(randomName.getName()); // 输出: "张伟强"

// 创建新实例
const generator: RandomName = new RandomName();
console.log(generator.getFemaleName()); // 输出: "李美丽"

// 使用接口类型
const nameGenerator: IRandomName = new RandomName();
const nickname: string = nameGenerator.getNickName();

// 使用风格化生成
console.log(randomName.getNickName(NickStyle.CUTE)); // 输出: "萌萌的小兔子"
console.log(randomName.getName(true, NameStyle.CLASSICAL)); // 输出: "司马若汐"
console.log(randomName.getMaleName(true, NameStyle.MODERN)); // 输出: "李浩然"

// 多语言昵称生成
console.log(randomName.getNickName(NickStyle.CUTE, Language.ENGLISH)); // 输出: "AdorableKitten"
console.log(randomName.getNickName(NickStyle.COOL, Language.JAPANESE)); // 输出: "つよいせんし"
console.log(randomName.getNickName(NickStyle.FUNNY, Language.KOREAN)); // 输出: "바보같은원숭이"

// 批量生成
const names = randomName.generateNames(5, {
    gender: "female",
    style: NameStyle.LITERARY,
});
console.log(names); // 输出: ["王诗雅", "张书瑶", "李墨兰", "陈文静", "刘诗韵"]

const nicknames = randomName.generateNickNames(3, NickStyle.FUNNY);
console.log(nicknames); // 输出: ["搞笑的逗比", "幽默的沙雕", "滑稽的憨憨"]

// 多语言批量生成昵称
const englishNicks = randomName.generateNickNames(
    3,
    NickStyle.COOL,
    Language.ENGLISH
);
console.log(englishNicks); // 输出: ["EpicWarrior", "LegendaryKing", "UltimateHero"]

JavaScript ES6 模块导入

import randomName, { RandomName } from "wg-random-name";

// 使用默认实例
console.log(randomName.getNickName()); // 输出: "快乐的小猫咪"
console.log(randomName.getName()); // 输出: "张伟强"

// 创建新实例
const generator = new RandomName();
console.log(generator.getFemaleName()); // 输出: "李美丽"

CommonJS 导入

const randomName = require("wg-random-name").default;
const { RandomName } = require("wg-random-name");

console.log(randomName.getMaleName()); // 输出: "王建国"

UMD 浏览器引入

<!-- 通过 CDN 引入 -->
<script src="https://unpkg.com/wg-random-name/dist/index.umd.js"></script>

<!-- 或者本地引入 -->
<script src="path/to/wg-random-name/dist/index.umd.js"></script>

<script>
    // 全局变量 RandomNameGenerator 可用
    const randomName = new RandomNameGenerator.RandomName();

    console.log("随机昵称:", randomName.getNickName());
    console.log("随机姓名:", randomName.getName());
    console.log("男性姓名:", randomName.getMaleName());
    console.log("女性姓名:", randomName.getFemaleName());

    // 也可以使用默认导出的实例
    console.log("默认实例:", RandomNameGenerator.default.getNickName());
</script>

自定义配置使用

import {
    RandomName,
    NameStyle,
    NickStyle,
    Language,
    CustomConfig,
} from "wg-random-name";

// 创建自定义配置
const customConfig: CustomConfig = {
    customFamilyNames: ["欧阳", "司马", "上官", "东方"],
    customGivenNames: ["星辰", "月影", "风华", "雪莲"],
    customNickHeaders: ["超级", "终极", "无敌", "神级"],
    customNickFoots: ["大师", "专家", "达人", "高手"],
    language: Language.CHINESE, // 设置默认语言
    mixWithDefault: true, // 与默认数据混合使用
};

// 使用自定义配置创建生成器
const customGenerator = new RandomName(customConfig);

console.log(customGenerator.getName()); // 可能输出: "欧阳星辰"
console.log(customGenerator.getNickName()); // 可能输出: "超级大师"

// 动态添加自定义数据
const generator = new RandomName();
generator.addCustomData({
    customFamilyNames: ["慕容", "轩辕"],
    nameStyle: NameStyle.CLASSICAL,
    language: Language.ENGLISH, // 设置默认语言为英文
    mixWithDefault: false, // 仅使用自定义数据
});

console.log(generator.getName()); // 输出自定义姓氏的名字
console.log(generator.getNickName()); // 输出英文昵称

// 重置为默认配置
generator.resetToDefault();

// 获取可用的选项列表
const options = generator.getAvailableOptions();
console.log(options.nameStyles); // ['traditional', 'modern', 'literary', 'classical']
console.log(options.nickStyles); // ['cute', 'funny', 'internet', 'cool', 'fresh', 'anime']
console.log(options.languages); // ['zh', 'en', 'ja', 'ko']

API 文档

枚举: NameStyle

姓名风格枚举，定义了不同的姓名生成风格。

enum NameStyle {
    TRADITIONAL = "traditional", // 传统正式
    MODERN = "modern", // 现代时尚
    LITERARY = "literary", // 文艺清新
    CLASSICAL = "classical", // 古风雅致
}

枚举: NickStyle

昵称风格枚举，定义了不同的昵称生成风格。

enum NickStyle {
    CUTE = "cute", // 俏皮可爱
    FUNNY = "funny", // 风趣幽默
    INTERNET = "internet", // 网络流行
    COOL = "cool", // 霸气威武
    FRESH = "fresh", // 文艺小清新
    ANIME = "anime", // 二次元
}

枚举: Language

支持的语言枚举，定义了可用的语言选项。

enum Language {
    CHINESE = "zh", // 中文
    ENGLISH = "en", // 英文
    JAPANESE = "ja", // 日语
    KOREAN = "ko", // 韩语
}

接口: CustomConfig

自定义配置接口，用于定制生成器的行为。

interface CustomConfig {
    customFamilyNames?: string[]; // 自定义姓氏列表
    customGivenNames?: string[]; // 自定义名字列表
    customNickHeaders?: string[]; // 自定义昵称前缀
    customNickFoots?: string[]; // 自定义昵称后缀
    nameStyle?: NameStyle; // 姓名风格
    nickStyle?: NickStyle; // 昵称风格
    language?: Language; // 默认语言设置
    mixWithDefault?: boolean; // 是否混合使用自定义和默认数据
}

接口: IRandomName

TypeScript 接口定义，描述了随机姓名生成器的契约。

interface IRandomName {
    nickHeader: string[];
    nickFoot: string[];
    femaleNameItems: string[];
    maleNameItems: string[];
    familyNameItemsSin: string[];
    familyNameItemsSur: string[];
    allName: string[];
    familyNameItemsAll: string[];

    getNickHeader(style?: NickStyle, language?: Language): string;
    getNickFoot(style?: NickStyle, language?: Language): string;
    getNickName(style?: NickStyle, language?: Language): string;
    getFamilyName(sur?: boolean): string;
    getFemaleName(sur?: boolean, style?: NameStyle): string;
    getMaleName(sur?: boolean, style?: NameStyle): string;
    getName(sur?: boolean, style?: NameStyle): string;
    generateNames(count: number, options?: GenerateOptions): string[];
    generateNickNames(
        count: number,
        style?: NickStyle,
        language?: Language
    ): string[];
    addCustomData(config: CustomConfig): void;
    resetToDefault(): void;
    getConfig(): CustomConfig;
    getAvailableOptions(): {
        nameStyles: NameStyle[];
        nickStyles: NickStyle[];
        languages: Language[];
    };
}

类: RandomName

实现了 IRandomName 接口的具体类。

构造函数

constructor(config?: CustomConfig)

创建 RandomName 实例，可选择传入自定义配置。

// 使用默认配置
const generator1 = new RandomName();

// 使用自定义配置
const generator2 = new RandomName({
    customFamilyNames: ["欧阳", "司马"],
    nameStyle: NameStyle.CLASSICAL,
    mixWithDefault: true,
});

方法

getNickName(style?: NickStyle, language?: Language): string

生成随机昵称，由形容词前缀和名词后缀组成。

• style (可选): 昵称风格
• language (可选): 语言设置

randomName.getNickName(); // "温柔的小兔子"
randomName.getNickName(NickStyle.CUTE); // "萌萌的小猫咪"
randomName.getNickName(NickStyle.COOL); // "霸气的战神"
randomName.getNickName(NickStyle.CUTE, Language.ENGLISH); // "AdorableKitten"
randomName.getNickName(NickStyle.COOL, Language.JAPANESE); // "つよいせんし"

getName(sur?: boolean, style?: NameStyle): string

生成随机姓名（不区分性别）。

• sur (可选): 是否包含复姓，默认为 true
• style (可选): 姓名风格

randomName.getName(); // "欧阳明华" (包含复姓)
randomName.getName(false); // "李明" (仅单姓)
randomName.getName(true, NameStyle.CLASSICAL); // "司马若汐"

getFemaleName(sur?: boolean, style?: NameStyle): string

生成随机女性姓名。

• sur (可选): 是否包含复姓，默认为 true
• style (可选): 姓名风格

randomName.getFemaleName(); // "司马婉儿"
randomName.getFemaleName(false); // "王美丽"
randomName.getFemaleName(true, NameStyle.MODERN); // "李梓涵"

getMaleName(sur?: boolean, style?: NameStyle): string

生成随机男性姓名。

• sur (可选): 是否包含复姓，默认为 true
• style (可选): 姓名风格

randomName.getMaleName(); // "诸葛亮明"
randomName.getMaleName(false); // "张伟"
randomName.getMaleName(true, NameStyle.LITERARY); // "王墨轩"

generateNames(count: number, options?: GenerateOptions): string[]

批量生成姓名。

• count: 生成数量
• options (可选): 生成选项
• gender: 性别 ('male' | 'female' | 'mixed')，默认 'mixed'
• sur: 是否包含复姓，默认 true
• style: 姓名风格

randomName.generateNames(5); // 生成5个混合性别的姓名
randomName.generateNames(3, { gender: "female", style: NameStyle.CLASSICAL });
// 生成3个古风女性姓名: ["司马若汐", "欧阳清歌", "上官慕雪"]

generateNickNames(count: number, style?: NickStyle, language?: Language): string[]

批量生成昵称。

• count: 生成数量
• style (可选): 昵称风格
• language (可选): 语言设置

randomName.generateNickNames(5); // 生成5个随机昵称
randomName.generateNickNames(3, NickStyle.FUNNY);
// 生成3个搞笑昵称: ["搞笑的逗比", "幽默的沙雕", "滑稽的憨憨"]
randomName.generateNickNames(3, NickStyle.COOL, Language.ENGLISH);
// 生成3个英文霸气昵称: ["EpicWarrior", "LegendaryKing", "UltimateHero"]

addCustomData(config: CustomConfig): void

添加自定义数据配置。

randomName.addCustomData({
    customFamilyNames: ["慕容", "轩辕"],
    customGivenNames: ["星辰", "月影"],
    mixWithDefault: true,
});

resetToDefault(): void

重置为默认配置，清除所有自定义数据。

randomName.resetToDefault();

getConfig(): CustomConfig

获取当前的自定义配置。

const config = randomName.getConfig();
console.log(config); // 当前配置对象

getAvailableOptions(): { nameStyles: NameStyle[], nickStyles: NickStyle[], languages: Language[] }

获取所有可用的选项列表。

const options = randomName.getAvailableOptions();
console.log(options.nameStyles); // ['traditional', 'modern', 'literary', 'classical']
console.log(options.nickStyles); // ['cute', 'funny', 'internet', 'cool', 'fresh', 'anime']
console.log(options.languages); // ['zh', 'en', 'ja', 'ko']

getFamilyName(sur?: boolean): string

获取随机姓氏。

• sur (可选): 是否包含复姓，默认为 true

randomName.getFamilyName(); // "欧阳"
randomName.getFamilyName(false); // "李"

getNickHeader(): string

获取随机昵称前缀（形容词）。

randomName.getNickHeader(); // "快乐的"

getNickFoot(): string

获取随机昵称后缀（名词）。

randomName.getNickFoot(); // "小猫咪"

TypeScript 自定义生成器

import { RandomName, IRandomName } from "wg-random-name";

class CustomNameGenerator extends RandomName {
    // 可以扩展或重写方法
    public getCustomName(): string {
        return `${this.getNickHeader()}${this.getFamilyName(false)}`;
    }

    // 生成指定数量的姓名
    public generateNames(
        count: number,
        includeCompoundSurname: boolean = true
    ): string[] {
        const names: string[] = [];
        for (let i = 0; i < count; i++) {
            names.push(this.getName(includeCompoundSurname));
        }
        return names;
    }
}

const customGenerator: CustomNameGenerator = new CustomNameGenerator();
console.log(customGenerator.getCustomName()); // "快乐的张"

const names: string[] = customGenerator.generateNames(5, false);
console.log("生成的姓名:", names);

许可证

ISC License

贡献

欢迎提交 Issue 和 Pull Request！