Stirling-PDF JavaScript API：在网页中集成PDF处理功能

滕娴殉

382人浏览 · 2025-10-01 03:41:32

滕娴殉 · 2025-10-01 03:41:32 发布

Stirling-PDF JavaScript API：在网页中集成PDF处理功能

你还在为网页端PDF处理功能开发烦恼吗？Stirling-PDF提供的JavaScript API让你无需从零构建复杂的PDF处理逻辑，只需简单调用API接口就能实现PDF合并、拆分、添加水印等专业功能。本文将带你快速掌握如何在网页中集成这些强大的PDF处理能力。

读完本文你将学会：

如何通过JavaScript调用Stirling-PDF的合并和拆分API
处理文件上传与API响应的完整流程
实现PDF合并、拆分功能的前端代码示例
了解Stirling-PDF提供的其他PDF处理API

认识Stirling-PDF API

Stirling-PDF是一个开源的本地托管网络应用，提供了丰富的PDF处理功能。其后台通过RESTful API提供服务，前端可以通过JavaScript轻松调用这些API。项目的核心API控制器集中在src/main/java/stirling/software/SPDF/controller/api/目录下，包含了合并、拆分、旋转、添加水印等多种PDF操作。

API基础信息

Stirling-PDF的API基础路径为/api/v1，主要支持POST请求，采用multipart/form-data格式上传文件。所有API控制器都使用了Spring的@RestController注解，例如合并功能的MergeController和拆分功能的SplitPDFController。

准备工作

在开始集成前，请确保你已经按照LocalRunGuide.md成功部署了Stirling-PDF服务。默认情况下，API服务将在本地的8080端口运行，基础URL为http://localhost:8080/api/v1。

实现PDF合并功能

PDF合并是最常用的PDF处理功能之一。Stirling-PDF提供了/api/v1/general/merge-pdfs端点来实现这一功能。

API端点详情

URL: /api/v1/general/merge-pdfs
方法: POST
内容类型: multipart/form-data
请求参数:
- fileInput: 多个PDF文件
- sortType: 排序类型，可选值有orderProvided、byFileName、byDateModified、byDateCreated、byPDFTitle
- removeCertSign: 是否移除证书签名，布尔值

JavaScript实现代码

async function mergePDFs() {
  const fileInput = document.getElementById('pdfFiles');
  const files = fileInput.files;
  
  if (files.length < 2) {
    alert('请选择至少两个PDF文件');
    return;
  }
  
  const formData = new FormData();
  
  // 添加所有选中的PDF文件
  for (let i = 0; i < files.length; i++) {
    formData.append('fileInput', files[i]);
  }
  
  // 设置排序类型 (可选，默认为orderProvided)
  formData.append('sortType', 'orderProvided');
  
  // 是否移除证书签名 (可选，默认为false)
  formData.append('removeCertSign', 'false');
  
  try {
    const response = await fetch('http://localhost:8080/api/v1/general/merge-pdfs', {
      method: 'POST',
      body: formData
    });
    
    if (!response.ok) {
      throw new Error('合并PDF失败: ' + response.statusText);
    }
    
    // 获取合并后的PDF blob
    const blob = await response.blob();
    
    // 创建下载链接
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = 'merged.pdf';
    document.body.appendChild(a);
    a.click();
    
    // 清理
    setTimeout(() => {
      document.body.removeChild(a);
      URL.revokeObjectURL(url);
    }, 0);
    
  } catch (error) {
    console.error('合并PDF时出错:', error);
    alert('合并PDF失败: ' + error.message);
  }
}

HTML表单

<div class="pdf-merge-section">
  <h3>PDF合并工具</h3>
  <input type="file" id="pdfFiles" accept=".pdf" multiple>
  <button onclick="mergePDFs()">合并PDF文件</button>
</div>

MergeController中的mergePdfs方法会处理请求，将多个PDF文件合并为一个，并返回合并后的PDF文件。该方法支持多种排序方式，可以根据文件名、修改日期、创建日期或PDF标题对文件进行排序。

实现PDF拆分功能

另一个常用功能是PDF拆分，Stirling-PDF提供了/api/v1/general/split-pages端点，可以将PDF文件按页码拆分为多个文件。

API端点详情

URL: /api/v1/general/split-pages
方法: POST
内容类型: multipart/form-data
请求参数:
- fileInput: 单个PDF文件
- pageNumbers: 页码或页码范围，如"1,3-5,7"

JavaScript实现代码

async function splitPDF() {
  const fileInput = document.getElementById('pdfFile');
  const pageNumbersInput = document.getElementById('pageNumbers');
  const file = fileInput.files[0];
  const pageNumbers = pageNumbersInput.value;
  
  if (!file) {
    alert('请选择一个PDF文件');
    return;
  }
  
  if (!pageNumbers) {
    alert('请输入页码或页码范围');
    return;
  }
  
  const formData = new FormData();
  formData.append('fileInput', file);
  formData.append('pageNumbers', pageNumbers);
  
  try {
    const response = await fetch('http://localhost:8080/api/v1/general/split-pages', {
      method: 'POST',
      body: formData
    });
    
    if (!response.ok) {
      throw new Error('拆分PDF失败: ' + response.statusText);
    }
    
    // 获取拆分后的ZIP文件
    const blob = await response.blob();
    
    // 创建下载链接
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = 'split_pdfs.zip';
    document.body.appendChild(a);
    a.click();
    
    // 清理
    setTimeout(() => {
      document.body.removeChild(a);
      URL.revokeObjectURL(url);
    }, 0);
    
  } catch (error) {
    console.error('拆分PDF时出错:', error);
    alert('拆分PDF失败: ' + error.message);
  }
}

HTML表单

<div class="pdf-split-section">
  <h3>PDF拆分工具</h3>
  <input type="file" id="pdfFile" accept=".pdf" single>
  <div>
    <label for="pageNumbers">页码或页码范围 (例如: 1,3-5,7):</label>
    <input type="text" id="pageNumbers" placeholder="输入页码或范围">
  </div>
  <button onclick="splitPDF()">拆分PDF文件</button>
</div>

SplitPDFController的splitPdf方法会根据提供的页码将PDF文件拆分为多个文件，并将这些文件打包成ZIP格式返回。你可以指定单个页码(如"1,3,5")或页码范围(如"1-5,7-10")。

其他实用API

除了合并和拆分，Stirling-PDF还提供了许多其他实用的API：

OCR文字识别

通过OCRController的/ocr-pdf端点可以对扫描版PDF进行文字识别，使其可搜索和复制。使用方法可参考HowToUseOCR.md。

添加水印

WatermarkController提供了/add-watermark端点，可以为PDF添加文字水印，支持自定义水印文本、颜色、大小和位置。

PDF压缩

CompressController的/compress-pdf端点可以减小PDF文件大小，便于存储和传输。

页面旋转

RotationController提供了/rotate-pdf端点，可以旋转PDF页面，支持顺时针和逆时针旋转。

错误处理与最佳实践

错误处理

在调用API时，应该妥善处理可能出现的错误，例如网络问题、文件过大或格式错误等。以下是一个通用的错误处理示例：

async function callStirlingApi(endpoint, formData) {
  try {
    const response = await fetch(`http://localhost:8080/api/v1${endpoint}`, {
      method: 'POST',
      body: formData
    });
    
    if (!response.ok) {
      const errorDetails = await response.text();
      throw new Error(`API请求失败: ${response.status} - ${errorDetails}`);
    }
    
    return response;
  } catch (error) {
    console.error('API调用错误:', error);
    // 可以在这里添加错误日志记录或用户提示
    throw error;
  }
}