创建沉浸式文档，使用户能够在 PDF 中直接旋转、缩放和浏览三维模型，是提升产品目录、工程报告和培训手册的强大方式。Aspose.Words Cloud SDK for .NET 提供了基于云的库，能够在将 DOCX 文件转换为 PDF 时轻松嵌入并保留 3D 内容。本指南将教您如何在 C# 中生成交互式 3D PDF，查看完整代码示例，探索等效的 cURL REST 调用，并了解实际应用的部署注意事项。

3D PDF 生成场景需求

开发人员在构建工程门户或交互式产品手册时，通常需要交付包含嵌入式 3D 模型的 PDF。典型的需求包括：

  • 源文档必须是已经包含 U3D 或 PRC 3D 模型的 DOCX 文件，格式分别为 U3D 或 PRC。
  • 生成的 PDF 必须保留 3D 数据，以便 Adobe Acrobat 等查看器能够交互式渲染。
  • 转换过程应实现自动化，在服务器上运行，并能够在大批量处理时无需人工干预。

传统的桌面工具在云环境中无法可靠地进行脚本化，并且在转换过程中常常会剥离 3D 流。因此，需要一种能够在保留 3D 模型的同时提供 PDF/A 合规性的编程解决方案。

方法：利用 Aspose.Words Cloud 进行 3D PDF

Aspose.Words Cloud SDK for .NET 提供一套基于 REST 的操作，这些操作在 Aspose 的安全服务器上运行。关键功能包括：

  • 直接将 DOCX 文件上传到 Aspose Cloud 存储。
  • PdfSaveOptionsData 允许您控制 PDF 合规性、字段更新，以及关键的嵌入式 3D 内容的保留。
  • 异步转换方法返回流，允许您直接将输出文件写入磁盘。

这些功能共同实现了一个简洁的 3D 转 PDF 工作流，可集成到 CI 流水线、Web 服务或后台作业中。详细的 API 信息可在官方文档和API 参考中找到。

在 C# 中生成交互式 3D PDF：实现

以下是实现的逐步演练。每一步都包含直接取自完整示例的简短代码摘录。

安装 Aspose.Words Cloud SDK for .NET

首先，将 NuGet 包添加到您的项目中。

dotnet add package Aspose.Words-Cloud

您也可以从下载页面下载二进制文件。

配置 WordsApi 客户端

使用您的客户端凭据创建一个 Configuration 对象并实例化 WordsApi。

var config = new Configuration
{
    ClientId = "YOUR_CLIENT_ID",
    ClientSecret = "YOUR_CLIENT_SECRET"
};
var wordsApi = new WordsApi(config);

WordsApi 类的文档位于 API 参考。

上传包含嵌入式 3D 模型的 DOCX

打开本地 DOCX 文件并将其上传到 Aspose Cloud 存储，覆盖同名的任何现有文件。

using (var fileStream = File.OpenRead(localDocxPath))
{
    var uploadRequest = new UploadFileRequest(fileStream, remoteFileName);
    await wordsApi.UploadFileAsync(uploadRequest);
}

确保 DOCX 已经包含 U3D 或 PRC 模型；这就是 SDK 保留的 3D Model Format。

设置 PDF 保存选项以保留 3D 内容

配置 PdfSaveOptionsData 以保留 3D 流并使用 PDF/A‑1b 合规性。

var pdfOptions = new PdfSaveOptionsData
{
    UpdateFields = false,
    Compliance = PdfCompliance.PdfA1b,
    SaveFormat = "pdf"
};

这些选项是 3D to PDF Workflow 工作流的一部分，确保交互式模型保持完整。

转换并下载交互式 3D PDF

调用转换请求并将生成的流写入本地 PDF 文件。

var convertRequest = new ConvertDocumentRequest(
    remoteFileName,
    format: "pdf",
    saveOptions: pdfOptions
);

using (var pdfStream = await wordsApi.ConvertDocumentAsync(convertRequest))
using (var fileWriter = File.Create(outputPdfPath))
{
    await pdfStream.CopyToAsync(fileWriter);
}

转换后，您可以选择从云存储中删除临时文件。

完整代码示例：在 C# 中生成交互式 3D PDF

以下代码演示了从头到尾的完整过程。

using System;
using System.IO;
using System.Threading.Tasks;
using Aspose.Words.Cloud.Sdk;
using Aspose.Words.Cloud.Sdk.Model;
using Aspose.Words.Cloud.Sdk.Model.Requests;

namespace Generate3DPdfExample
{
    class Program
    {
        static async Task Main(string[] args)
        {
            // -----------------------------------------------------------------
            // 1. Configure Aspose.Words Cloud client (replace with your credentials)
            // -----------------------------------------------------------------
            var config = new Configuration
            {
                ClientId = "YOUR_CLIENT_ID",
                ClientSecret = "YOUR_CLIENT_SECRET"
            };
            var wordsApi = new WordsApi(config);

// -----------------------------------------------------------------
            // 2. Define file names and paths (generic placeholders)
            // -----------------------------------------------------------------
            const string localDocxPath = "input.docx";   // DOCX that already contains an embedded 3D model (U3D/PRC)
            const string remoteFileName = "input.docx"; // Name used in Aspose Cloud storage
            const string outputPdfPath = "output.pdf";

// -----------------------------------------------------------------
            // 3. Upload the DOCX to Aspose Cloud storage (overwrites if exists)
            // -----------------------------------------------------------------
            using (var fileStream = File.OpenRead(localDocxPath))
            {
                var uploadRequest = new UploadFileRequest(fileStream, remoteFileName);
                await wordsApi.UploadFileAsync(uploadRequest);
            }

// -----------------------------------------------------------------
            // 4. Prepare PDF save options – enable 3D content preservation
            // -----------------------------------------------------------------
            var pdfOptions = new PdfSaveOptionsData
            {
                // Preserve the embedded 3D model; the option name may vary depending on API version.
                // Setting 'UpdateFields' to false speeds up conversion when fields are not required.
                UpdateFields = false,
                // Use PDF/A-1b compliance to keep the document portable while still supporting 3D.
                Compliance = PdfCompliance.PdfA1b,
                // Ensure the output is a single PDF file.
                SaveFormat = "pdf"
            };

// -----------------------------------------------------------------
            // 5. Convert the uploaded DOCX to PDF with the defined options
            // -----------------------------------------------------------------
            var convertRequest = new ConvertDocumentRequest(
                remoteFileName,
                format: "pdf",
                saveOptions: pdfOptions
            );

using (var pdfStream = await wordsApi.ConvertDocumentAsync(convertRequest))
            using (var fileWriter = File.Create(outputPdfPath))
            {
                await pdfStream.CopyToAsync(fileWriter);
            }

// -----------------------------------------------------------------
            // 6. Clean up remote file (optional)
            // -----------------------------------------------------------------
            var deleteRequest = new DeleteFileRequest(remoteFileName);
            await wordsApi.DeleteFileAsync(deleteRequest);

Console.WriteLine($"3D PDF generated successfully at '{Path.GetFullPath(outputPdfPath)}'.");
        }
    }
}

注意： 此代码示例演示了核心功能。在将其用于项目之前，请确保更新文件路径（input.docx、output.pdf 等）以匹配实际文件位置，验证所有必需的依赖项已正确安装，并在开发环境中彻底测试。如果遇到任何问题，请参阅官方文档或联系支持团队获取帮助。

使用 cURL 和 REST API 执行 3D PDF 转换

相同的操作可以通过对 Aspose.Words Cloud REST 端点的 cURL 调用来执行。

  1. 获取访问令牌 (将占位符替换为您的凭据。)
curl -X POST "https://api.aspose.cloud/connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"
  1. 上传 DOCX 包含 3D 模型。
curl -X PUT "https://api.aspose.cloud/v4.0/words/storage/file/input.docx" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @input.docx
  1. 请求 PDF 转换并保留 3D.
curl -X POST "https://api.aspose.cloud/v4.0/words/input.docx/saveAs/pdf" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "PdfSaveOptions": {
            "UpdateFields": false,
            "Compliance": "PdfA1b"
        }
      }' \
  -o output.pdf
  1. 下载生成的 PDF（之前的命令已经将其保存到本地，但您也可以直接获取它）。

有关请求体和其他参数的更多详细信息，请参阅官方 API 文档。

3D PDF 生成的部署注意事项

在将此解决方案集成到生产环境时，请牢记以下要点：

  • 服务器位置 - 转换在 Aspose 的云服务器上运行，请确保您的网络允许对 api.aspose.cloud 的出站 HTTPS 流量。
  • 许可 - 生产环境使用需要商业许可证。您可以从临时许可证页面获取临时许可证。
  • 可伸缩性 - 由于 API 是无状态的，您可以在多个工作实例之间并行上传和转换，以处理大批量任务，支持完整的 3D 到 PDF 自动化。

结论

使用 Aspose.Words Cloud SDK for .NET 在 C# 中生成交互式 3D PDF 变得简单。按照上述步骤，您可以嵌入 U3D 或 PRC 模型，在 PDF 转换过程中保留它们，并通过 .NET 库或直接的 REST 调用来自动化工作流。请确保为生产环境获取合适的许可证，并在支持 3D 的查看器（如 Adobe Acrobat）中测试生成的 PDF。借助此功能，您可以为工程、营销和培训场景提供更丰富、更具吸引力的文档。

常见问题

如何使用 Aspose.Words Cloud 在 C# 中生成交互式 3D PDF？
使用 SDK 上传已包含 U3D 或 PRC 模型的 DOCX，配置 PdfSaveOptionsData 以保留 3D 流，并调用 ConvertDocumentAsync。本文中的完整代码示例展示了确切的步骤顺序。

我可以在 PDF 转换中嵌入哪些 3D 模型格式？
Aspose.Words Cloud 支持 U3D 和 PRC 格式，这些是 PDF 中交互式 3D 内容的标准格式。

是否可以在不编写任何 C# 代码的情况下运行转换？
是的，可以使用针对 Aspose.Words Cloud REST API 的 cURL 命令执行相同的过程，如 cURL 部分所示。

我在哪里可以找到定价和授权信息？
商业授权详情可在产品页面查看，您可以从临时授权页面获取用于评估的临时授权。

Read More