拼豆图案很适合成为像素画编辑器的起点，因为它天生就是离散网格和有限颜色。但模板不能只是一张参考图：用户导入以后，希望得到的是可改色、可拆层、可继续导出的项目。bitArt 用字符矩阵描述模板，再把字符映射为颜色和像素数组，最终生成普通项目的图层、画布尺寸和调色板。这样“拼豆模板”只是一个高效的新建入口，而不是锁死的图片格式。

用字符矩阵保存图案，比保存整张图片更可编辑

若模板只存成位图，导入后需要再做颜色识别，透明区域和调色板会变得不可靠；若模板只生成像素数组却没有图层和背景，项目进入工作区后又会缺少正常编辑器依赖的结构。另一个容易忽略的问题是卡片预览：直接缩放大模板会花费不必要的渲染成本，而用粗暴裁剪又可能把主题轮廓裁掉。

模板描述、预览和导入结果如何分层

拼豆模板的价值不在于显示一张图，而在于把图案、颜色和底板拆成编辑器能理解的数据。字符矩阵正好提供了这种轻量又可检查的来源。

模板导入要一次构造项目所需的全部状态

当前模板包含 width、height、rows、colors 和 backgroundColor。rows 中每个字符代表一个颜色符号，点号代表透明；colors 将符号映射到具体颜色。createTemplateImportResult 找到模板后，建立“拼豆图案”和锁定“底板”两层，逐行逐列把符号转换为 templatePixels，再同时生成项目名、活动色和去重后的调色板。

这一结果使用与图片导入相同的 ImageImportResult 形状，因此后续新建项目流程不需要知道数据来自拼豆模板还是相册。模板只负责把结构化描述变成标准编辑器输入，工作流继续负责创建项目、持久化和 UI 刷新。

模板导入不是只写一层像素，而是一次构造图案层、底板层和画布信息。

const layers: LayerItem[] = [
  { id: 'layer-1', name: '拼豆图案', visible: true, locked: false, opacity: 1 },
  { id: 'background', name: '底板', visible: true, locked: true, opacity: 1 }
];
const templatePixels = PixelCanvasService.createTransparentPixels(template.width, template.height);
for (let row = 0; row < template.height; row++) {
  const sourceRow = row < template.rows.length ? template.rows[row] : '';
  for (let col = 0; col < template.width; col++) {
    const symbol = sourceRow.length > col ? sourceRow.charAt(col) : '.';
    const color = BeadTemplateService.getColorBySymbol(template.colors, symbol);
    if (color.length > 0) templatePixels[row * template.width + col] = color;
  }
}

小预览和完整导入必须使用不同精度

预览只采样固定数量的格子。sampleIndex 会根据预览格的中心位置映射到源模板，保证大尺寸图案和小尺寸图案都能在卡片中保留主要色块。完整导入则不采样，每一个模板字符都映射到一个画布像素。两条路径不同精度但共享 getTemplateColor 和 getColorBySymbol，预览不会展示出与实际导入不同的配色。

const result: ImageImportResult = {
  layers: layers,
  layersPixels: [templatePixels, PixelCanvasService.createSolidPixels(template.width, template.height,
    template.backgroundColor)],
  activeLayer: 'layer-1',
  canvasSize: Math.max(template.width, template.height),
  canvasWidth: template.width,
  canvasHeight: template.height,
  layerSerial: 2
};

模板生成结果怎样接入新建项目流程

模板导入的输出包含 layers、layersPixels、activeLayer、canvasWidth、canvasHeight 和 layerSerial。它不直接把数据塞进页面属性，而是让新建项目工作流应用。颜色列表也随结果返回，用户打开后立即能从调色板继续画，而不必再次手动取色。

模板结果包含调色板和活动色，使用户进入工作区后能立即在同一套颜色中继续编辑。

for (let row = 0; row < BEAD_PREVIEW_SAMPLE_SIZE; row++) {
  const sourceRow = BeadTemplateService.sampleIndex(row, BEAD_PREVIEW_SAMPLE_SIZE, template.height);
  for (let col = 0; col < BEAD_PREVIEW_SAMPLE_SIZE; col++) {
    const sourceCol = BeadTemplateService.sampleIndex(col, BEAD_PREVIEW_SAMPLE_SIZE, template.width);
    const color = BeadTemplateService.getTemplateColor(template, sourceRow, sourceCol);
    cells.push({
      id: template.id + '-' + row.toString() + '-' + col.toString() + '-' + color,
      color: color
    });
  }
}

模板转换时不要丢掉的编辑语义

• 不要把点号当成白色；它表示透明，底板颜色由单独背景层提供。
• 小预览可以采样，真正创建项目时必须逐格导入，不可复用采样后的低分辨率数组。
• 模板导入应创建可编辑图层和正常项目字段，不能只返回一张不可操作的预览图。

字符矩阵还有一个额外好处：模板内容易于审阅和版本控制。一个颜色符号的变动、某一行像素的修正都能精确表达，而不是在二进制图片中难以比较。对像素画这种网格创作工具，数据结构本身就可以成为创作素材的一部分。

把模板当作数据而不是贴图

拼豆模板的实际检查应从符号表开始。选一个同时包含点号、多个颜色符号和非方形尺寸的模板，逐行比对 rows 与导入后图案层的像素。点号只应在图案层保留透明，底板层再提供背景色；某个未知符号也应按明确规则处理，而不是随机落成黑色。这样模板数据有错误时可以直接定位到哪一行哪个符号。

之后检查项目体验：导入后图层是否可编辑、底板是否锁定、调色板是否包含模板颜色、活动色是否来自第一种有效颜色。小预览可以省略很多格子，但完整导入不允许省略。把预览、模板文本和最终图层放在同一个检查视角里，才能证明它是一条可维护的数据链路，而不是一次偶然正确的转换。

模板尺寸与颜色表需要一起校验

模板 rows 的长度可能短于声明的 width，数据服务不能默认每一行都完整。当前导入逻辑会在缺失位置按点号处理，避免访问越界；颜色符号找不到映射时也返回空色，而不是猜测一个默认颜色。这样模板数据即使有局部缺口，结果仍保持可编辑和可诊断。开发时可以额外统计每个符号的使用次数，快速发现颜色表中从未使用或 rows 中未知的符号。

模板的宽高也不必强制为正方形。拼豆图案可能是横向徽章、纵向挂饰或长条文字，项目结果应保留原始 canvasWidth 与 canvasHeight，而不是只保存一个最大边 canvasSize。后续在画布上缩放、居中、导出时都依赖这两个维度，模板导入如果在这里丢失矩形尺寸，后面再补救会把错误扩散到视口和图片导出。

怎样确认模板仍是可编辑项目

模板检查应把透明、底板、调色板和尺寸同时列入验证，而不是只看图案轮廓。

• 选择一个含透明孔洞的模板，确认孔洞显示底板颜色但图案层该处保持透明。
• 导入后隐藏图案层，确认底板仍在；隐藏底板，确认透明区域正确。
• 比较卡片预览与完整导入后的主要轮廓和配色，确认没有明显错位。
• 从导入后的调色板选择模板色继续绘制，确认颜色列表已带入项目。

拼豆模板检查记录
点号保持透明，不替换成白色
导入生成图案层和锁定底板层
预览与完整导入的主色和轮廓一致
模板色自动进入项目调色板

拼豆模板目前不解决的工作

当前模板是内置字符矩阵，不包含拍照识别拼豆盘、自动计算颗数、品牌色号匹配或打印排版。这些可以成为后续独立能力，但不应在模板导入阶段混进编辑器的基本像素数据路径。

这一篇的重点是把字符化拼豆图案转换成可继续编辑的像素项目。模板和素材会带来更多配置项，下一篇把自动保存、导出和洋葱皮等设置怎样规范化讲清楚。