简体中文 | English

src="https://coveralls.io/repos/github/yyz945947732/cnname/badge.svg?branch=master"
alt="Coverage Status"
/>


src="https://img.shields.io/badge/ Vitest-tested-6da13f.svg?logo=vitest&labelColor=edd532"
alt="Test in Vitest"
/>


src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg"
alt="PRs Welcome"
/>


src="https://img.shields.io/badge/license-MIT-blue.svg"
alt="GitHub license"
/>

⚡️ 在线体验

在 StackBlitz 中打开

✨ 特性

- 🎲 轻松简单的生成各种随机中文姓名。
- 🎭 支持丰富的姓氏类型和名字特性。
- ⚡ 轻量级库，快速生成，无额外依赖。
- 🛠 提供多种 API，可自定义生成规则。
- 📚 适用于测试数据、小说创作、游戏角色等场景。

📦 安装

``bash
npm install cnname
`

`bash
yarn add cnname
`

`bash
pnpm install cnname
`

$3

`js
import { getName } from 'cnname';

getName();
// -> 李炜
getName('高');
// -> 高佳倩
getName(5);
// -> ["余嘉扬", "郭东仪", "谢鸿宾", "彭天奇", "关智华"]
getName('张', 5);
// -> ["张腾", "张怡莉", "张瑞宇", "张萍", "张韵思"]
getName({ count: 5, gender: 'female' });
// -> ["庞妙", "黄如嫣", "姜莹", "莫惠安", "周敏"]
`

📖 API

getName(): string

获取一个随机姓名。

getName(surname: string): string

获取指定姓氏的随机姓名。

getName(num: number): string[]

获取指定数量的随机姓名。

getName(surname: string, num: number): string[]

获取指定姓氏和数量的随机姓名。

getName(options: Options): string[]

通过高级选项获取姓名。支持性别、五行、叠字名、复姓等丰富功能。👉 查看文档

🛠️ 工具方法

- isSurname - 判断是否为姓氏。

- getNameStr - 同 getName，但始终返回字符串。

- parseName - 解析名字，返回姓氏等信息。

- getAllSurnames - 获取所有姓氏。

- getSurname - 随机获取姓氏。

- getGivenName - 随机获取名（不含姓氏）。

📚 资源

以下为资源库，如果缺少了你想要的姓氏或名字，欢迎补充。

- 📖 姓氏库

- 📝 名字库

✍️ 示例

`js
import { getName } from 'cnname';

const 主角 = getName();
const 反派 = getName('张');

const novel =

第 1 章 千人围攻

"${主角}，你已经被我们围攻了！！！"

${反派}的厉啸从身后传来，随着尖锐的破空声，一声利箭没入${主角}身旁的黄土墙。

${主角}心头微凉，定睛一看。

只见阴暗的密林四处，已经隐隐约约钻出千道黑色人影。

他们分别是：

${getName(1000).join('，')}。
;
``

👉 输出结果

🔑 许可证

MIT