AvatarStack

一个用 SVG 积木图层生成头像的 Node.js 引擎。引擎提供透明画布、按顺序叠加、裁剪、位图导出、种子派生与分享编码；画面内容和所有界面文案都由方案包提供。

安装

npm install avatarstack

需要 Node.js 18.17 或更新版本。

快速开始

const avatarstack = require('avatarstack');

// 默认是中文；服务端可为每个应用创建自己的语言实例。
const avatars = avatarstack.createAvatarStack({ locale: 'en' });
const info = avatars.describeScheme('default');
console.log(info.name);                      // Modern Blocks
console.log(info.fields[0]);                 // { id: 'background', name: 'Background', count: 10, kind: 'layer' }
console.log(info.layers[0].variants[0].name); // Morning mist

const result = await avatars.generateAvatar({
  scheme: 'default',
  seed: '[email protected]',
  shape: 'circle',
  size: 256,
  format: 'png',
});
console.log(result.base64); // data:image/png;base64,...
console.log(result.code);   // 可分享的头像编码

不创建实例也可以直接使用顶层 API：generateAvatar、generateSvg、describeScheme 等；文字默认中文。createAvatarStack('en-US') 也可以。语言只影响描述，不改变 SVG、配置、种子派生和分享编码。

默认方案

默认方案 default 是重新设计的扁平风人物积木。背景、脖颈、服装、耳朵、脸型、脸颊、眉毛、眼睛、鼻子、嘴巴、发型、配饰共有 12 个图层，每层 10 款；另有各 10 款的肤色与发色。所有部件都可以独立选择。

const { describeScheme, getRandomConfig, generateSvg } = require('avatarstack');
const info = describeScheme('default');
const config = getRandomConfig('default');
config.background = 2;
config.hair = 5;
config.skinTone = 3;
console.log(generateSvg({ scheme: 'default', config }));

describeScheme() 的 fields 给前端直接遍历的配置字段顺序和显示名。layers 提供图层顺序、每款的 index/name；palettes 提供已本地化的颜色条目。配置始终使用稳定的英文 id 和数字下标，不受语言影响。

其他内置方案：cat、dog、car、example。它们也自带中英文名称、说明、图层、款式和调色板名称。getAvailableSchemes() 可列出概要。

绘制规则

引擎从透明空画布开始，依照 scheme.layers 的数组顺序绘制：先定义的在下，后定义的在上。背景也是普通图层；需要背景就将它放在图层数组前面。不需要任何图形时，空数组 layers: [] 是合法方案。shape 为 square、rounded 或 circle，它裁剪最终合成画面。SVG/PNG/WebP 可以保留透明区域；JPEG 无透明通道，透明处以白色输出。

config 不传时随机；传入但缺少某些字段时，缺项也会随机。若需要稳定输出，传完整配置，或者使用 seed / code。

const { generateAvatar, generateSvg, decodeAvatarCode } = require('avatarstack');
const svg = generateSvg({ scheme: 'cat', seed: 'alice', size: 200 });
const image = await generateAvatar({ scheme: 'cat', seed: 'alice', format: 'webp' });
const restored = await generateAvatar({ code: image.code });
console.log(decodeAvatarCode(image.code)); // { scheme, config, code }

code 与 scheme、config、seed 互斥。seed 可与 scheme 一起使用，但不能与 config 一起使用。shape、size 和 format 仅控制输出，不写入分享编码。

编写独立方案包

方案是纯 JavaScript 对象，可以放在独立 npm 包中。文案必须随方案一起发布；引擎不维护第三方方案的翻译表。

const { defineScheme, registerScheme } = require('avatarstack');
const t = (zh, en) => ({ zh, en });

const scheme = defineScheme({
  id: 'dots',                    // 小写字母和数字；分享编码前缀
  name: t('彩色圆点', 'Color Dots'),
  description: t('简单示例', 'A simple example'),
  viewBox: '0 0 200 200',
  paletteNames: { color: t('颜色', 'Color') },
  palettes: {
    color: [
      { name: t('红色', 'Red'), fill: '#F87171' },
      { name: t('蓝色', 'Blue'), fill: '#60A5FA' },
    ],
  },
  layers: [
    {
      id: 'background', name: t('背景', 'Background'),
      variants: [() => '<rect width="200" height="200" fill="#FFF7ED"/>'],
      variantNames: [t('暖白', 'Warm white')],
    },
    {
      id: 'dot', name: t('圆点', 'Dot'),
      variants: [
        (ctx) => `<circle cx="100" cy="100" r="35" fill="${ctx.color.fill}"/>`,
        (ctx) => `<circle cx="100" cy="100" r="65" fill="${ctx.color.fill}"/>`,
      ],
      variantNames: [t('小', 'Small'), t('大', 'Large')],
    },
  ],
});

registerScheme(scheme); // 分享编码需要注册；直接传 scheme 对象渲染则不需要

ctx.color 是调色板中选中的条目，ctx.config.color 是其数字下标。默认情况下，多于一款的图层会产生配置字段；用 selectable: true/false 可以显式覆盖。固定图层只渲染第一款。图层顺序也是配置与分享编码的一部分，已发布的方案不要重新排序、改 id 或改变变体数量。语言对象可包含其他语言代码，例如 { zh, en, ja }；找不到请求语言时依次回退到中文、英文和第一个非空翻译。旧方案的字符串 name 仍然可用。

更多开发约定见 贡献指南。 使用 AI 开发方案时，另见 AGENTS.md。

从 1.x 升级

2.x 的 default 方案重新定义了字段、款式和绘图，因此旧版 default-* 分享编码及 seed 产生的视觉结果不兼容。需要长期保存旧头像时，请保留 1.x 版本；若要迁入 2.x，先在 1.x 解码旧编码，再把旧方案以新 id 发布并按该方案重新编码。bgFill 不再绘制引擎背景；请使用方案中的 background 图层。其他内置方案的字段顺序与款式数量未改，它们的分享编码仍可解码，但由于引擎不再自动画背景，画面透明区域会与旧版不同。

API

• createAvatarStack({ locale: 'zh' })：返回绑定语言的实例，默认中文。
• generateAvatar(options)：返回 { base64, rawBase64, format, size, shape, scheme, config, code }；format 支持 png、jpg/jpeg、webp、svg。
• generateSvg(options)：同步返回 SVG 字符串。
• describeScheme(scheme?, locale?)、getAvailableSchemes(locale?)：返回已本地化的界面描述。
• getRandomConfig(scheme?)、normalizeConfig(config, scheme?)：生成和规范化配置。
• defineScheme(scheme)、registerScheme(scheme)、getScheme(id)：方案校验与注册。
• encodeAvatarCode(config, scheme?)、decodeAvatarCode(code)、isValidAvatarCode(code)：分享编码。
• deriveAvatarConfig(seed, scheme?, options?)、deriveAvatarCode(seed, scheme?, options?)：确定性派生；options 支持 salt 与 normalize。

运行 npm test 做校验；node tools/preview.js default --sweep hair 可预览某图层的全部款式。

MIT License.