如何用ag-psd轻松读写PSD文件：完整指南

ag-psd是一款功能强大的JavaScript库，专为读取和写入Photoshop PSD文件设计。无论是在Node.js环境还是浏览器中，它都能帮助开发者轻松处理PSD文件的各种元素，无需依赖Adobe Photoshop软件。

🚀 为什么选择ag-psd？

核心优势

• 完全免费开源：采用MIT许可协议，可自由用于商业项目
• 跨平台兼容：同时支持Node.js后端和浏览器前端环境
• 轻量化设计：仅依赖base64-js和pako两个基础库
• 灵活的API：提供简洁直观的接口，轻松实现复杂PSD操作

支持的功能

ag-psd能够处理PSD文件的多种关键元素，包括：

ag-psd支持多种图层效果解析，如图层样式、混合模式等

• 图层结构与属性（名称、可见性、不透明度）
• 基本混合模式与填充不透明度
• 文字图层（基础文本内容与样式）
• 矢量蒙版与图层蒙版
• 智能对象链接文件

💻 快速开始：安装与基础使用

一键安装步骤

npm install ag-psd

如需从源码构建，可先克隆仓库：

git clone https://gitcode.com/gh_mirrors/ag/ag-psd
cd ag-psd
npm install
npm run build

Node.js基础示例

读取PSD文件

import * as fs from 'fs';
import 'ag-psd/initialize-canvas';
import { readPsd } from 'ag-psd';

const buffer = fs.readFileSync('example.psd');
const psd = readPsd(buffer);

// 输出图层信息
console.log('图层数量:', psd.children.length);
console.log('第一个图层名称:', psd.children[0].name);

// 保存第一个图层为PNG
fs.writeFileSync('layer-0.png', (psd.children[0].canvas as any).toBuffer());

创建并写入PSD文件

import * as fs from 'fs';
import 'ag-psd/initialize-canvas';
import { writePsdBuffer } from 'ag-psd';

const psd = {
  width: 800,
  height: 600,
  children: [
    {
      name: '背景图层',
      // 图层属性设置...
    }
  ]
};

const buffer = writePsdBuffer(psd);
fs.writeFileSync('new-file.psd', buffer);

浏览器环境使用

在浏览器中，ag-psd可以直接处理ArrayBuffer格式的PSD文件数据：

import { readPsd } from 'ag-psd';

// 从服务器加载PSD文件
fetch('example.psd')
  .then(response => response.arrayBuffer())
  .then(buffer => {
    const psd = readPsd(buffer);
    // 将图层 canvas 添加到页面
    document.body.appendChild(psd.children[0].canvas);
  });

📝 高级功能详解

文字图层操作

ag-psd支持创建和修改文字图层，包括基本文本内容、字体样式和段落格式：

使用ag-psd更新文字图层后，Photoshop会提示更新图层数据

const psd = {
  width: 400,
  height: 200,
  children: [
    {
      name: '标题文字',
      text: {
        text: 'Hello ag-psd!',
        transform: [1, 0, 0, 1, 50, 100], // 位置变换矩阵
        style: {
          font: { name: 'ArialMT' },
          fontSize: 36,
          fillColor: { r: 255, g: 0, b: 0 } // 红色
        },
        paragraphStyle: {
          justification: 'center' // 居中对齐
        }
      }
    }
  ]
};

图层蒙版处理

ag-psd能够读取和写入图层蒙版数据，实现复杂的图层透明度控制：

ag-psd支持解析和创建带有蒙版的图层

相关功能实现位于源码的src/psdReader.ts和src/psdWriter.ts文件中。

混合模式与效果

支持多种Photoshop混合模式和图层效果的解析：

ag-psd支持多种PS混合模式的解析

⚠️ 注意事项与限制

虽然ag-psd功能强大，但仍有一些限制需要注意：

1. 颜色模式支持：目前主要支持RGB模式，不支持CMYK、索引色等模式
2. 文字图层：垂直文字可能导致PSD文件损坏，不支持段落样式和字符样式
3. 智能对象：部分智能滤镜效果可能无法正确解析
4. 图像重绘：修改图层属性后需要手动更新图像数据

完整的限制列表请参考项目README.md文档。

🔧 开发与贡献

ag-psd是一个活跃发展的开源项目，欢迎开发者参与贡献。项目采用TypeScript开发，主要源码位于src/目录下，测试用例位于test/目录。

开发环境设置：

# 安装依赖
npm install

# 构建项目
npm run build

# 运行测试
npm test

🎯 总结

ag-psd为JavaScript开发者提供了一个强大而灵活的PSD文件处理解决方案，无论是构建自动化工作流、开发设计工具，还是实现Web端PSD预览功能，都能胜任。通过简单的API，即可轻松实现PSD文件的读写与修改，极大地扩展了前端和Node.js应用处理Photoshop文件的可能性。

立即尝试ag-psd，开启你的PSD文件自动化处理之旅吧！