跳到主要内容

PSD 导入

将 Photoshop .psd 文件转换成可继续编辑的 Ydesign 设计稿。

🚧 规划中：@ydesign/psd-import 尚未发布。下文描述的是目标 API 与能力边界，便于提前评估接入方式；包就绪后会按此形态落地，细节可能微调。

@ydesign/psd-import 负责把 PSD 解析成 Ydesign 设计 JSON（与 store.loadJSON() / Fabric 画布使用的同一套结构）：文字仍是可编辑文字，矢量尽量保留为矢量，位图层变成图片。

Beta 预期： 首发会覆盖常见图层类型；复杂智能对象、高级效果、部分混合模式可能需要栅格化或降级。欢迎用真实 PSD 反馈问题，帮助我们迭代。

安装（规划中）​

pnpm add @ydesign/psd-import
# 或
npm install @ydesign/psd-import

基本用法​

psdToJson 接收 PSD 的 ArrayBuffer / Uint8Array，返回一份可直接交给 Store 的设计 JSON。

import { psdToJson } from '@ydesign/psd-import';

const json = await psdToJson({ psd: buffer });

// 载入编辑器
store.loadJSON(json);

返回值对齐设计 JSON（{ width, height, fonts, pages, unit, dpi, ... }），可被 @ydesign/react-editor 的 store.loadJSON 直接消费。

浏览器示例​

从 <input type="file"> 读取字节：

import { psdToJson } from '@ydesign/psd-import';

async function handleFileUpload(file: File) {
  const buffer = await file.arrayBuffer();
  const json = await psdToJson({ psd: buffer });
  store.loadJSON(json);
}

适合「用户上传 PSD → 打开编辑」的产品流程。解析全程在本地完成，不会把文件上传到 Ydesign 服务器。

Node.js 示例​

从磁盘读取：

import { readFile } from 'node:fs/promises';
import { psdToJson } from '@ydesign/psd-import';

const buffer = await readFile('./design.psd');
const json = await psdToJson({ psd: buffer });

// 写入模板库、批量转 JSON、或再交给云渲染 / Node 出图

适合后台批量转换、模板入库、CI 流水线。大文件优先走 Node（内存上限更高）。

工作原理​

目标不是把 PSD「压成一张图」，而是尽量把图层映射成 彼此独立、可再编辑 的 Ydesign 元素：

PSD 图层映射结果
文字层可编辑文本：字族、字重、样式、字号、颜色、对齐、行高、字距等尽量保留
形状 / 矢量层SVG / 矢量元素：填充、渐变、描边尽量保留
位图 / 栅格层图片元素。若图层效果（渐变叠加、色相/饱和度、亮度对比度等）无法用 schema 原生表达，会把效果烘焙进该层像素，其余图层仍保持独立
蒙版 / 组效果应用到下层内容，避免整份文档被压扁
混合模式schema 支持的直接透传；不支持的模式只对依赖图层做局部扁平化

PSD 自带的合成预览图不会作为最终稿使用——每个元素应尽量保持可选中、可编辑。

平台支持​

环境支持
浏览器（客户端）✅ 规划支持
Node.js（服务端）✅ 规划支持

处理在本地完成，不依赖外部渲染服务。若你后续要出高清图，可把得到的 JSON 交给 云渲染 API 或 服务端图像生成。

错误处理（规划）​

解析失败时，导入器会抛出带结构化字段的 Error，大致形态：

try {
  const json = await psdToJson({ psd: buffer });
  store.loadJSON(json);
} catch (err) {
  // err.code === 'IMPORT_FAILED'
  // err.details?.format === 'psd'
  // err.cause → 底层解析错误
  console.error(err);
}

具体错误码会在包发布时写入 changelog / README，并尽量与其它导入包保持一致。

相关导入 / 导出​

能力说明
PDF 导出客户端 / 服务端出 PDF
大尺寸 & 高清导出印刷级分辨率
云渲染 API托管服务端出图
SVG / PDF 导入后续单独成包，与 PSD 导入并列

常见问题​

导入结果和 PS 里不完全一样？​

  • 导入前可先简化 PSD：合并无用组、栅格化复杂智能对象
  • 3D 图层、视频层、复杂图层组合（Layer Comp）等高级特性不在首批支持范围
  • 打开浏览器 / Node 控制台，查看警告信息

字体丢失或回退？​

  • 导入 JSON 里字体按 字族名 引用；渲染环境若未安装 / 未加载对应字体，会回退到默认字体
  • 出图前请用 store.addFont / 云渲染的 fonts 字段把字体 URL 声明完整，参见 字体一致性

文件很大？​

  • 几百 MB 以内的 PSD，浏览器通常还能解析；超大文件或批量任务请在 Node.js 中调用 psdToJson()
  • 导入后再导出高清图时，注意浏览器 canvas 上限，必要时走 云渲染

和 Fabric 的关系？​

  • @ydesign/psd-import 只负责 PSD → 设计 JSON
  • 真正上画布由 @ydesign/core（Fabric）+ @ydesign/react-editor 的 loadJSON 完成
  • 这样浏览器与 Node 可以共用同一份解析结果，不必各写一套转换

路线图​

阶段内容
现在文档与 API 形态冻结；可用手写 / 其他工具生成 JSON 接入编辑器
包首发@ydesign/psd-import：文字 / 位图 / 常见矢量与蒙版
后续更完整的效果与混合模式、智能对象策略、与模板库打通

有 PSD 样例或业务场景，欢迎通过 定价页 或社区渠道反馈，我们会优先覆盖高频用例。