AsposeTeXforPython – 常见问题解答

问：什么是 AsposeTeXforPython？

答: AsposeTeXforPython 是一个纯 Python API(通过 pythonnet 在 AsposeTeX .NET 库之上构建)，可以将 LaTeX/TeX 文档渲染并转换为 PDF、XPS、SVG、PNG、JPEG、BMP、TIFF 和其他图像格式，而不需要任何外部 TeX 发行版。它在进程内运行，适用于 Web 服务、桌面应用程序和自动报告生成器。

问：如何安装 AsposeTeXforPython？

答: 运行 pip install aspose-tex-python-net。该包自动捆绑所需的“pythonnet”运行时。将其安装在任何具有 Python3.8 或更高版本的虚拟环境(Windows、Linux、macOS)中。使用以下命令验证安装：

import aspose.tex as tex
print(tex.__version__)

问：我需要本地 TeX 发行版(MiKTeX、TeXLive 等)吗？

答: 不需要。所有解析和渲染逻辑都内置于 AsposeTeX 中，因此您永远不需要外部 TeX 引擎。该库包含 300 多个开箱即用的核心 LaTeX 包和常见类文件。

问：如何使用几行代码将 .tex 文件转换为 PDF？

答: 使用 Object LaTeX 配置、PdfSaveOptions 和 PdfDevice 创建 TeXJob。 将 ASPOSE_TEX_INPUT_FILE 设置为 LaTeX 文件路径，将 ASPOSE_TEX_OUTPUT_DIR 设置为输出目录，或修改示例中的路径。默认值为 hello-world.ltx 和 output。请先应用许可证。示例在主文档所在目录查找其他输入文件，并以非交互方式处理。 许可证

# Convert LaTeX to PDF.
import os
from pathlib import Path
from aspose.tex import Interaction, TeXConfig, TeXJob, TeXOptions
from aspose.tex.io import InputFileSystemDirectory, OutputFileSystemDirectory, OutputMemoryTerminal
from aspose.tex.presentation.pdf import PdfDevice, PdfSaveOptions

# Set these paths to your LaTeX document and output directory.
input_file = Path(os.environ.get("ASPOSE_TEX_INPUT_FILE", "hello-world.ltx")).resolve()
output_dir = Path(os.environ.get("ASPOSE_TEX_OUTPUT_DIR", "output")).resolve()
if not input_file.is_file():
    raise FileNotFoundError(input_file)
output_dir.mkdir(parents=True, exist_ok=True)

# Use the Object LaTeX format and resolve additional inputs beside the main file.
options = TeXOptions.console_app_options(TeXConfig.object_latex)
options.input_working_directory = InputFileSystemDirectory(str(input_file.parent))
options.output_working_directory = OutputFileSystemDirectory(str(output_dir))
options.interaction = Interaction.NONSTOP_MODE
options.terminal_out = OutputMemoryTerminal()
options.save_options = PdfSaveOptions()
device = PdfDevice()
job_result = TeXJob(str(input_file), device, options).run()

输出文件名与输入文件名对应：hello-world.ltx 生成 hello-world.pdf。 LaTeX → PDF

问：AsposeTeXforPython 可以生成哪些输出格式？

答: PDF、XPS、SVG、PNG、JPEG、BMP 和 TIFF。每种格式都可以通过特定的“SaveOptions”对象(例如“PdfSaveOptions”、“PngSaveOptions”、“SvgSaveOptions”)进行控制。

问：如何将自定义字体嵌入到生成的 PDF 中？

答: 字体由 TeX 或 LaTeX 文档及其包选择。有关包资源，请参阅 外部 LaTeX 包。PdfSaveOptions 的 subset_fonts 属性控制是否仅嵌入使用的字形，而不是选择自定义字体。使用同一选项的完整 XPS 示例见 字体子集化。

问：开箱即用支持哪些 LaTeX 包和类？

答: 该库包含常用 LaTeX 包和类。有关支持范围，请参阅 内置包列表。 外部包示例通过 required_input_directory 提供 pgfplots 的源文件。

问：如何使用非内置的第三方“.sty”或类文件？

答: 将 TeXOptions.required_input_directory 设置为包含所需包文件的 InputFileSystemDirectory。完整示例从 ExternalLaTeXPackages/packages 加载 fancybox.sty，并将 required-input-fs.tex 转换为 PNG。有关 ZIP 归档和兼容性限制，请参阅 外部 LaTeX 包。

请先应用 许可证。将 ASPOSE_TEX_INPUT_DIR 设置为包含 ExternalLaTeXPackages 的文件夹（默认为 input），其中应保留两个 .tex 文件和 packages 子目录。将 ASPOSE_TEX_OUTPUT_DIR 设置为输出文件夹（默认为 output）。

# Load an external LaTeX package from a directory.
import os
from pathlib import Path
from os import path
from io import BytesIO
from aspose.tex import Interaction, TeXConfig, TeXJob, TeXOptions
from aspose.tex.io import InputFileSystemDirectory, InputZipDirectory, OutputFileSystemDirectory, OutputMemoryTerminal
from aspose.tex.presentation.image import ImageDevice, PngSaveOptions

output_dir = Path(os.environ.get("ASPOSE_TEX_OUTPUT_DIR", "output")).resolve()
output_dir.mkdir(parents=True, exist_ok=True)
input_dir = Path(os.environ.get("ASPOSE_TEX_INPUT_DIR", "input")).resolve() / "ExternalLaTeXPackages"
# Create conversion options for Object LaTeX format upon Object TeX engine extension.
options = TeXOptions.console_app_options(TeXConfig.object_latex)
options.interaction = Interaction.NONSTOP_MODE
options.terminal_out = OutputMemoryTerminal()
# Specify a file system working directory for the output.
options.output_working_directory = OutputFileSystemDirectory(str(output_dir))
# Specify a file system working directory for the required input.
# The directory containing packages may be located anywhere.
options.required_input_directory = InputFileSystemDirectory(path.join(str(input_dir), "packages"))
# Initialize the options for saving in PNG format.
options.save_options = PngSaveOptions()
# Run LaTeX to PNG conversion.
TeXJob(path.join(str(input_dir), "required-input-fs.tex"), ImageDevice(True), options).run()

问：引擎的主要限制是什么？

答:

限制	详情
Shell 转义符 (\write18)	出于安全考虑已禁用。
完全 TikZ 外部化	不支持；大多数 TikZ 图形会在进程内渲染，但极其复杂的图形可能会失败。
Unicode 字体覆盖范围	仅完全支持具有完整字形集的 TrueType/OpenType 字体；旧版 Type1 字体可能需要转换。
超大文档（>500 页）	可能会占用大量内存；请考虑使用 Document.save(output_stream, options) 流式传输页面。

问：如何应用许可证密钥以及有哪些可用的许可模式？

答: 请在使用其他 Aspose.TeX 类之前应用许可证。将 ASPOSE_TEX_PYTHON_NET_LICENSE_PATH 设置为许可证文件路径，或将 Aspose.TeX.Python-net.lic 放在工作目录中。

# Apply a license from a file before using other Aspose.TeX classes.
import os
from aspose.tex import License

# Set this environment variable, or place the license in the working directory.
license_path = os.environ.get(
    "ASPOSE_TEX_PYTHON_NET_LICENSE_PATH", "Aspose.TeX.Python-net.lic"
)
license = License()
license.set_license(license_path)

有关从文件、流以及通过 Metered 应用许可证的示例和评估版限制，请参阅 许可证。

问：该库对于并行转换来说是线程安全的吗？

答: 是的，前提是每个线程创建自己的“Document”实例。在任何并行工作开始之前，必须设置诸如“许可证”之类的静态对象。

问：AsposeTeXforPython 需要哪个 .NET 运行时版本？

答: 该软件包附带 .NET6 (x64) 运行时二进制文件。它们在第一次导入时由 pythonnet 自动加载；您不需要手动安装.NET。

问：如何设置光栅输出的页面大小、方向和 DPI？

答: 在 LaTeX 源代码中设置页面大小和方向。例如，将下面的 A4 横向文档保存为 landscape.ltx：

\documentclass{article}
\usepackage[a4paper,landscape]{geometry}
\begin{document}
Hello, World!
\end{document}

在将保存选项赋给作业之前设置 PngSaveOptions.resolution。此示例使用 300 DPI。将 ASPOSE_TEX_INPUT_FILE 设置为 landscape.ltx，将 ASPOSE_TEX_OUTPUT_DIR 设置为输出目录，或使用默认路径：

# Convert an A4 landscape LaTeX document to PNG at 300 DPI.
import os
from pathlib import Path
from aspose.tex import Interaction, TeXConfig, TeXJob, TeXOptions
from aspose.tex.io import InputFileSystemDirectory, OutputFileSystemDirectory, OutputMemoryTerminal
from aspose.tex.presentation.image import ImageDevice, PngSaveOptions

# Set these paths to your LaTeX document and output directory.
input_file = Path(os.environ.get("ASPOSE_TEX_INPUT_FILE", "landscape.ltx")).resolve()
output_dir = Path(os.environ.get("ASPOSE_TEX_OUTPUT_DIR", "output")).resolve()
if not input_file.is_file():
    raise FileNotFoundError(input_file)
output_dir.mkdir(parents=True, exist_ok=True)

# Use the Object LaTeX format and resolve additional inputs beside the main file.
options = TeXOptions.console_app_options(TeXConfig.object_latex)
options.input_working_directory = InputFileSystemDirectory(str(input_file.parent))
options.output_working_directory = OutputFileSystemDirectory(str(output_dir))
options.interaction = Interaction.NONSTOP_MODE
options.terminal_out = OutputMemoryTerminal()
# Page size and orientation are defined in the LaTeX input (geometry package).
# Set the raster resolution in dots per inch.
save_options = PngSaveOptions()
save_options.resolution = 300
options.save_options = save_options
device = ImageDevice(True)
job_result = TeXJob(str(input_file), device, options).run()

结果为 landscape.png，尺寸约为 3508 × 2480 像素。

问：我可以直接从字符串或内存流渲染 LaTeX 吗？

答: 将完整的 LaTeX 文档编码为二进制 BytesIO 流，传给使用 TeXConfig.object_latex 的 TeXJob。作业期间保持流打开。输出为 texput.xps 和 texput.log。 将 ASPOSE_TEX_OUTPUT_DIR 设置为输出目录（默认 output）。请先应用许可证。 Licensing.

# Render LaTeX supplied as a binary in-memory stream to XPS.
import os
from pathlib import Path
from aspose.tex import Interaction, TeXConfig, TeXJob, TeXOptions
from io import BytesIO
from aspose.tex.io import OutputFileSystemDirectory, OutputMemoryTerminal
from aspose.tex.presentation.xps import XpsDevice

output_dir = Path(os.environ.get("ASPOSE_TEX_OUTPUT_DIR", "output")).resolve()
output_dir.mkdir(parents=True, exist_ok=True)

options = TeXOptions.console_app_options(TeXConfig.object_latex)
options.interaction = Interaction.NONSTOP_MODE
options.output_working_directory = OutputFileSystemDirectory(str(output_dir))
options.terminal_out = OutputMemoryTerminal()
latex_source = r"\documentclass{article} \begin{document} Hello, World! \end{document}"
device = XpsDevice()
with BytesIO(latex_source.encode("ascii")) as input_stream:
    job_result = TeXJob(input_stream, device, options).run()

问：在哪里可以找到官方文档、代码示例和支持渠道？

答: 检查下一个资源：

• 官方文档
• 入门指南
• 代码示例和 GitHub 要点
• 支持论坛
• 问题跟踪器(客户专用)- 购买后提供

所有示例均提供 Python 和 C# 版本；得益于 pythonnet，C# 代码可以直接翻译。