vue-text-avatar-generator

Vue 3 轻量级文字头像生成器组件，支持自定义文字/背景色、随机飞书风格配色、高清圆形头像下载，适配多场景业务需求（如组织架构、用户头像等）。

特性

✅ 支持 1-5 个字符（中英文），自动智能换行（4/5字自动拆分为两行）
✅ 自定义背景色 + 随机飞书风格配色池，支持实时预览
✅ 生成 3 倍高清圆形头像，无锯齿模糊问题
✅ 灵活控制输入框显隐，支持父组件传值自动生成
✅ 轻量无冗余依赖，仅依赖 Vue 3 核心

安装

# npm
npm install vue-text-avatar-generator --save

# yarn
yarn add vue-text-avatar-generator

# pnpm
pnpm add vue-text-avatar-generator

快速开始

1. 全局注册（推荐用于全项目使用）

// main.js / main.ts
import { createApp } from 'vue';
import App from './App.vue';
import TextAvatarGenerator from 'vue-text-avatar-generator';

const app = createApp(App);
app.use(TextAvatarGenerator); // 全局注册组件
app.mount('#app');

2. 按需引入（推荐用于局部使用）

<template>
  <TextAvatarGenerator 
    :value="avatarText" 
    :show-download-btn="true"
    :enable-input="false"
    @fileGenerated="handleFileGenerated"
  />
</template>

<script setup>
import { ref } from 'vue';
import TextAvatarGenerator from 'vue-text-avatar-generator';

// 自定义头像文字
const avatarText = ref('财务部');

// 监听头像生成成功事件
const handleFileGenerated = (file) => {
  console.log('生成的高清头像文件：', file);
  // 可在此处实现文件上传、本地保存等逻辑
};
</script>

API 参考

Props（属性）

| 名称 | 类型 | 默认值 | 说明 | |------|------|--------|------| | value | String | "" | 头像显示的文字内容，传值后自动生成对应头像 | | showDownloadBtn | Boolean | false | 是否显示下载按钮，点击可下载高清头像（PNG格式） | | enableInput | Boolean | true | 是否显示输入框和“生成图标”按钮，false则隐藏输入区域 |

Events（事件）

| 名称 | 触发时机 | 回调参数 | 说明 | |------|----------|----------|------| | fileGenerated | 头像生成成功后 | Blob 文件对象 | 返回生成的高清头像文件，包含文件名、大小等信息 |

常用场景示例

场景1：父组件传值（隐藏输入框，仅展示头像+下载）

适用于“固定文字头像”场景（如组织架构、部门头像）

<template>
  <!-- 隐藏输入框，直接显示“技术部”头像 + 下载按钮 -->
  <TextAvatarGenerator 
    value="技术部" 
    :show-download-btn="true"
    :enable-input="false"
    @fileGenerated="handleDownload"
  />
</template>

<script setup>
const handleDownload = (file) => {
  console.log('下载的头像文件：', file.name); // 输出示例：avatar-技术部-1711000000000-ultra-hd.png
};
</script>

场景2：用户输入（显示输入框，自定义生成）

适用于“用户自主生成头像”场景（如个人中心、自定义头像）

<template>
  <!-- 显示输入框，用户输入文字后点击生成/下载 -->
  <TextAvatarGenerator 
    :show-download-btn="true"
    @fileGenerated="handleGenerated"
  />
</template>

<script setup>
const handleGenerated = (file) => {
  alert('头像生成成功！可点击下载按钮保存');
};
</script>

场景3：自定义颜色 + 随机配色

组件内置飞书风格配色池，支持手动选择自定义颜色或点击“随机颜色”切换

<template>
  <TextAvatarGenerator 
    value="市场部" 
    :show-download-btn="true"
    :enable-input="false"
  />
</template>

注意事项

1. 字符限制：建议传入 1-5 个字符，超出 5 个字符会被截断（输入框已限制 maxlength=5）；
2. 浏览器兼容性：兼容现代浏览器（Chrome/Firefox/Safari/Edge），不支持 IE；
3. 高清生成：组件默认生成 3 倍高清头像（600*600 画布），下载后无模糊问题；
4. 样式适配：组件内置基础样式，可通过自定义 CSS 覆盖 .text-icon-generator 类名调整样式。

目录结构

vue-text-avatar-generator/
├── src/
│   ├── components/
│   │   └── TextAvatarGenerator.vue  # 核心组件（包含画布绘制、颜色逻辑）
│   └── index.js                     # 插件入口（注册组件，支持全局引入）
├── package.json                     # npm 包配置（含导出、依赖、脚本）
├── vite.config.js                   # Vite 库模式打包配置（样式内联，无额外CSS）
├── README.md                        # 完整使用文档
└── .npmignore                       # npm 发布忽略规则（仅发布dist/src/README）

开源协议

MIT License