在 Python via Java 中管理 PowerPoint 文本段落

概述

Aspose.Slides for Python via Java 将文本表示为文本框、段落和部分的层次结构:

  • TextFrame 表示形状中的文本容器,并提供对其段落集合的访问。
  • Paragraph 表示文本框中的一个段落,并提供对其部分以及段落级格式的访问。
  • Portion 表示段落中的一段文本运行。每个部分可以拥有自己的文本和字符级格式。

因此,一个段落可以通过使用多个部分来包含具有不同字体、颜色、大小和其他格式的文本。

创建和格式化段落

在形状的文本框中创建段落,并使用部分来格式化各个文本运行。本节展示如何在每个段落中组合多个部分并应用不同的颜色、字体大小和样式。

使用多个部分创建段落

以下 Python 示例创建了三个段落,每个段落在通过 Paragraph.getPortions 返回的集合中包含三个文本运行。它复用默认段落及其空部分,然后添加其余的段落和部分。格式通过 Portion.getPortionFormat 应用:每个段落的第一个部分为红色、粗体、15 磅;第二个为蓝色、斜体、18 磅。第三个部分保留默认格式:

import jpype
import asposeslides

if not jpype.isJVMStarted():
    jpype.startJVM()

from asposeslides.api import FillType, NullableBool, Paragraph, Portion, Presentation, SaveFormat, ShapeType
from java.awt import Color

presentation = Presentation()
try:
    slide = presentation.getSlides().get_Item(0)

    shape = slide.getShapes().addAutoShape(ShapeType.Rectangle, 50, 150, 300, 150)
    text_frame = shape.getTextFrame()

    first_paragraph = text_frame.getParagraphs().get_Item(0)
    first_paragraph.getPortions().add(Portion())
    first_paragraph.getPortions().add(Portion())

    second_paragraph = Paragraph()
    second_paragraph.getPortions().add(Portion())
    second_paragraph.getPortions().add(Portion())
    second_paragraph.getPortions().add(Portion())
    text_frame.getParagraphs().add(second_paragraph)

    third_paragraph = Paragraph()
    third_paragraph.getPortions().add(Portion())
    third_paragraph.getPortions().add(Portion())
    third_paragraph.getPortions().add(Portion())
    text_frame.getParagraphs().add(third_paragraph)

    paragraph_count = text_frame.getParagraphs().getCount()
    for paragraph_index in range(paragraph_count):
        paragraph = text_frame.getParagraphs().get_Item(paragraph_index)
        portion_count = paragraph.getPortions().getCount()
        for portion_index in range(portion_count):
            portion = paragraph.getPortions().get_Item(portion_index)
            portion.setText(f"Portion {paragraph_index + 1}.{portion_index + 1}")

            if portion_index == 0:
                portion.getPortionFormat().getFillFormat().setFillType(FillType.Solid)
                portion.getPortionFormat().getFillFormat().getSolidFillColor().setColor(Color.RED)
                portion.getPortionFormat().setFontBold(NullableBool.True_)
                portion.getPortionFormat().setFontHeight(15)
            elif portion_index == 1:
                portion.getPortionFormat().getFillFormat().setFillType(FillType.Solid)
                portion.getPortionFormat().getFillFormat().getSolidFillColor().setColor(Color.BLUE)
                portion.getPortionFormat().setFontItalic(NullableBool.True_)
                portion.getPortionFormat().setFontHeight(18)

    presentation.save("paragraphs_with_portions.pptx", SaveFormat.Pptx)
finally:
    presentation.dispose()

创建项目符号和编号列表

使用符号、数字或自定义图像将段落文本组织为列表。本节示例涵盖项目符号格式、多级列表以及自定义起始编号。

创建项目符号或编号列表

项目符号和编号可以使相关项目更易于浏览。在 Aspose.Slides 中,列表设置通过 BulletFormat 定义。

此 Python 示例在同一文本框中添加了符号项目符号和编号项目。BulletFormat.setType 选择项目符号类型,BulletFormat.setChar 提供符号,BulletFormat.setNumberedBulletStyle 选择编号样式。两个项目均使用黑色项目符号,高度为 100%,段落缩进为 25 磅:

import jpype
import asposeslides

if not jpype.isJVMStarted():
    jpype.startJVM()

from asposeslides.api import BulletType, ColorType, NullableBool, NumberedBulletStyle, Paragraph, Presentation, SaveFormat, ShapeType
from java.awt import Color

presentation = Presentation()
try:
    slide = presentation.getSlides().get_Item(0)

    shape = slide.getShapes().addAutoShape(ShapeType.Rectangle, 200, 200, 400, 200)
    text_frame = shape.getTextFrame()
    text_frame.getParagraphs().clear()

    symbol_paragraph = Paragraph()
    symbol_paragraph.setText("Welcome to Aspose.Slides")
    symbol_paragraph.getParagraphFormat().getBullet().setType(BulletType.Symbol)
    symbol_paragraph.getParagraphFormat().getBullet().setChar("•")
    symbol_paragraph.getParagraphFormat().setIndent(25)
    symbol_paragraph.getParagraphFormat().getBullet().getColor().setColorType(ColorType.RGB)
    symbol_paragraph.getParagraphFormat().getBullet().getColor().setColor(Color.BLACK)
    symbol_paragraph.getParagraphFormat().getBullet().setBulletHardColor(NullableBool.True_)
    symbol_paragraph.getParagraphFormat().getBullet().setHeight(100)
    text_frame.getParagraphs().add(symbol_paragraph)

    numbered_paragraph = Paragraph()
    numbered_paragraph.setText("This is a numbered item")
    numbered_paragraph.getParagraphFormat().getBullet().setType(BulletType.Numbered)
    numbered_paragraph.getParagraphFormat().getBullet().setNumberedBulletStyle(NumberedBulletStyle.BulletCircleNumWDBlackPlain)
    numbered_paragraph.getParagraphFormat().setIndent(25)
    numbered_paragraph.getParagraphFormat().getBullet().getColor().setColorType(ColorType.RGB)
    numbered_paragraph.getParagraphFormat().getBullet().getColor().setColor(Color.BLACK)
    numbered_paragraph.getParagraphFormat().getBullet().setBulletHardColor(NullableBool.True_)
    numbered_paragraph.getParagraphFormat().getBullet().setHeight(100)
    text_frame.getParagraphs().add(numbered_paragraph)

    presentation.save("bulleted_and_numbered_list.pptx", SaveFormat.Pptx)
finally:
    presentation.dispose()

使用图片项目符号

图片项目符号允许使用自定义图像代替符号或数字。

此 Python 示例将图像作为 PPImage 添加到演示文稿的图像集合,并将其用作段落项目符号。它调用 BulletFormat.setType 使用图片项目符号,并通过 BulletFormat.getPicture 分配图像。BulletFormat.setHeight 设置为 100% 以相对于段落文本对项目符号进行尺寸调整:

import jpype
import asposeslides

if not jpype.isJVMStarted():
    jpype.startJVM()

from asposeslides.api import BulletType, Images, Paragraph, Presentation, SaveFormat, ShapeType

presentation = Presentation()
try:
    slide = presentation.getSlides().get_Item(0)

    bullet_image = Images.fromFile("bullets.png")
    try:
        presentation_image = presentation.getImages().addImage(bullet_image)
    finally:
        bullet_image.dispose()

    shape = slide.getShapes().addAutoShape(ShapeType.Rectangle, 200, 200, 400, 200)
    text_frame = shape.getTextFrame()
    text_frame.getParagraphs().clear()

    paragraph = Paragraph()
    paragraph.setText("Welcome to Aspose.Slides")
    paragraph.getParagraphFormat().getBullet().setType(BulletType.Picture)
    paragraph.getParagraphFormat().getBullet().getPicture().setImage(presentation_image)
    paragraph.getParagraphFormat().getBullet().setHeight(100)
    text_frame.getParagraphs().add(paragraph)

    presentation.save("picture_bullet.pptx", SaveFormat.Pptx)
    presentation.save("picture_bullet.ppt", SaveFormat.Ppt)
finally:
    presentation.dispose()

创建多级列表

使用 ParagraphFormat.setDepth 将段落放置在列表的不同层级。顶级的深度为 0。

此 Python 示例为四个段落分别赋予 0 到 3 的 ParagraphFormat.setDepth 值,以在同一文本框中创建层次结构。每个段落使用符号项目符号,且通过 BulletFormat.setChar 在圆形项目符号和短横之间交替,以区分相邻层级:

import jpype
import asposeslides

if not jpype.isJVMStarted():
    jpype.startJVM()

from asposeslides.api import BulletType, FillType, Paragraph, Presentation, SaveFormat, ShapeType
from java.awt import Color

presentation = Presentation()
try:
    slide = presentation.getSlides().get_Item(0)

    shape = slide.getShapes().addAutoShape(ShapeType.Rectangle, 200, 200, 400, 200)
    text_frame = shape.getTextFrame()
    text_frame.getParagraphs().clear()

    first_paragraph = Paragraph()
    first_paragraph.setText("Content")
    first_paragraph.getParagraphFormat().getBullet().setType(BulletType.Symbol)
    first_paragraph.getParagraphFormat().getBullet().setChar("•")
    first_paragraph.getParagraphFormat().getDefaultPortionFormat().getFillFormat().setFillType(FillType.Solid)
    first_paragraph.getParagraphFormat().getDefaultPortionFormat().getFillFormat().getSolidFillColor().setColor(Color.BLACK)
    first_paragraph.getParagraphFormat().setDepth(0)

    second_paragraph = Paragraph()
    second_paragraph.setText("Second level")
    second_paragraph.getParagraphFormat().getBullet().setType(BulletType.Symbol)
    second_paragraph.getParagraphFormat().getBullet().setChar('-')
    second_paragraph.getParagraphFormat().getDefaultPortionFormat().getFillFormat().setFillType(FillType.Solid)
    second_paragraph.getParagraphFormat().getDefaultPortionFormat().getFillFormat().getSolidFillColor().setColor(Color.BLACK)
    second_paragraph.getParagraphFormat().setDepth(1)

    third_paragraph = Paragraph()
    third_paragraph.setText("Third level")
    third_paragraph.getParagraphFormat().getBullet().setType(BulletType.Symbol)
    third_paragraph.getParagraphFormat().getBullet().setChar("•")
    third_paragraph.getParagraphFormat().getDefaultPortionFormat().getFillFormat().setFillType(FillType.Solid)
    third_paragraph.getParagraphFormat().getDefaultPortionFormat().getFillFormat().getSolidFillColor().setColor(Color.BLACK)
    third_paragraph.getParagraphFormat().setDepth(2)

    fourth_paragraph = Paragraph()
    fourth_paragraph.setText("Fourth level")
    fourth_paragraph.getParagraphFormat().getBullet().setType(BulletType.Symbol)
    fourth_paragraph.getParagraphFormat().getBullet().setChar('-')
    fourth_paragraph.getParagraphFormat().getDefaultPortionFormat().getFillFormat().setFillType(FillType.Solid)
    fourth_paragraph.getParagraphFormat().getDefaultPortionFormat().getFillFormat().getSolidFillColor().setColor(Color.BLACK)
    fourth_paragraph.getParagraphFormat().setDepth(3)

    text_frame.getParagraphs().add(first_paragraph)
    text_frame.getParagraphs().add(second_paragraph)
    text_frame.getParagraphs().add(third_paragraph)
    text_frame.getParagraphs().add(fourth_paragraph)

    presentation.save("multilevel_list.pptx", SaveFormat.Pptx)
finally:
    presentation.dispose()

以自定义值启动编号列表项

使用 BulletFormat.setNumberedBulletStartWith 设置编号段落的起始数字。

此 Python 示例将 BulletFormat.setType 设置为编号,并为三个段落分别赋予 2、3、7 的 BulletFormat.setNumberedBulletStartWith 值。每个段落的起始值单独配置,使显示的数字可以跳过:

import jpype
import asposeslides

if not jpype.isJVMStarted():
    jpype.startJVM()

from asposeslides.api import BulletType, Paragraph, Presentation, SaveFormat, ShapeType

presentation = Presentation()
try:
    slide = presentation.getSlides().get_Item(0)

    shape = slide.getShapes().addAutoShape(ShapeType.Rectangle, 200, 200, 400, 200)
    text_frame = shape.getTextFrame()
    text_frame.getParagraphs().clear()

    first_paragraph = Paragraph()
    first_paragraph.setText("Start at 2")
    first_paragraph.getParagraphFormat().getBullet().setType(BulletType.Numbered)
    first_paragraph.getParagraphFormat().getBullet().setNumberedBulletStartWith(2)

    text_frame.getParagraphs().add(first_paragraph)

    second_paragraph = Paragraph()
    second_paragraph.setText("Start at 3")
    second_paragraph.getParagraphFormat().getBullet().setType(BulletType.Numbered)
    second_paragraph.getParagraphFormat().getBullet().setNumberedBulletStartWith(3)
    text_frame.getParagraphs().add(second_paragraph)

    third_paragraph = Paragraph()
    third_paragraph.setText("Start at 7")
    third_paragraph.getParagraphFormat().getBullet().setType(BulletType.Numbered)
    third_paragraph.getParagraphFormat().getBullet().setNumberedBulletStartWith(7)
    text_frame.getParagraphs().add(third_paragraph)

    presentation.save("custom_numbered_list.pptx", SaveFormat.Pptx)
finally:
    presentation.dispose()

控制段落布局和结尾属性

调整段落的边距和缩进以控制首行和换行行的位置。您还可以单独格式化段落结束标记,而不影响可见文本部分。

设置首行缩进

使用 ParagraphFormat.setIndent 方法控制段落的首行缩进。此设置仅移动首行相对于段落左边距的距离。正值将首行向右移动,而其余行保持与段落正文对齐。

需要整体移动段落时使用 ParagraphFormat.setMarginLeft;仅需移动首行时使用 ParagraphFormat.setIndent。

以下示例为三个段落设置相同的 ParagraphFormat.setMarginLeft 为 20 磅,并将 ParagraphFormat.setIndent 分别设为 0、20、40 磅。首行以递增的偏移开始,而换行行保持相同的左边距:

import jpype
import asposeslides

if not jpype.isJVMStarted():
    jpype.startJVM()

from asposeslides.api import FillType, Paragraph, Presentation, SaveFormat, ShapeType, TextAutofitType
from java.awt import Color

presentation = Presentation()
try:
    slide = presentation.getSlides().get_Item(0)

    shape = slide.getShapes().addAutoShape(ShapeType.Rectangle, 50, 50, 420, 220)
    shape.getFillFormat().setFillType(FillType.NoFill)
    shape.getLineFormat().getFillFormat().setFillType(FillType.Solid)
    shape.getLineFormat().getFillFormat().getSolidFillColor().setColor(Color.GRAY)

    text_frame = shape.getTextFrame()
    text_frame.getTextFrameFormat().setAutofitType(TextAutofitType.Shape)
    text_frame.getParagraphs().clear()

    first_paragraph = Paragraph()
    first_paragraph.setText("No first-line indent. Wrapped lines start at the same position as the first line.")
    first_paragraph.getParagraphFormat().getDefaultPortionFormat().getFillFormat().setFillType(FillType.Solid)
    first_paragraph.getParagraphFormat().getDefaultPortionFormat().getFillFormat().getSolidFillColor().setColor(Color.BLACK)
    first_paragraph.getParagraphFormat().setMarginLeft(20.0)
    first_paragraph.getParagraphFormat().setIndent(0.0)

    second_paragraph = Paragraph()
    second_paragraph.setText("First-line indent of 20 points. The first line moves to the right, while wrapped lines remain aligned to the paragraph body.")
    second_paragraph.getParagraphFormat().getDefaultPortionFormat().getFillFormat().setFillType(FillType.Solid)
    second_paragraph.getParagraphFormat().getDefaultPortionFormat().getFillFormat().getSolidFillColor().setColor(Color.BLACK)
    second_paragraph.getParagraphFormat().setMarginLeft(20.0)
    second_paragraph.getParagraphFormat().setIndent(20.0)

    third_paragraph = Paragraph()
    third_paragraph.setText("First-line indent of 40 points. This paragraph shows a larger first-line offset to make the effect easier to see.")
    third_paragraph.getParagraphFormat().getDefaultPortionFormat().getFillFormat().setFillType(FillType.Solid)
    third_paragraph.getParagraphFormat().getDefaultPortionFormat().getFillFormat().getSolidFillColor().setColor(Color.BLACK)
    third_paragraph.getParagraphFormat().setMarginLeft(20.0)
    third_paragraph.getParagraphFormat().setIndent(40.0)

    text_frame.getParagraphs().add(first_paragraph)
    text_frame.getParagraphs().add(second_paragraph)
    text_frame.getParagraphs().add(third_paragraph)

    presentation.save("paragraph_indent.pptx", SaveFormat.Pptx)
finally:
    presentation.dispose()

结果:

段落的首行缩进

设置悬挂缩进

悬挂缩进是一种段落布局,首行位于其余行的左侧。在 Aspose.Slides 中,可通过 ParagraphFormat.setIndent 属性实现。将 Indent 设置为负值即可使首行相对于段落正文向左移动。

实际使用时,ParagraphFormat.setMarginLeft 定义段落正文的左侧位置,而 ParagraphFormat.setIndent 定义首行相对于该边距的位置。要创建悬挂缩进,需将正的 MarginLeft 与负的 Indent 组合使用。

此类格式常用于参考文献、注释、词汇表条目等,需要换行行在段落正文下对齐而非首行字符下方的段落。

以下 Python 示例将 ParagraphFormat.setMarginLeft 分别设为 40 和 60 磅,并将 ParagraphFormat.setIndent 设为 -20 和 -30 磅。每个段落的首行均位于换行行左侧;第二个段落的悬挂缩进更深:

import jpype
import asposeslides

if not jpype.isJVMStarted():
    jpype.startJVM()

from asposeslides.api import FillType, Paragraph, Presentation, SaveFormat, ShapeType, TextAutofitType
from java.awt import Color

presentation = Presentation()
try:
    slide = presentation.getSlides().get_Item(0)

    shape = slide.getShapes().addAutoShape(ShapeType.Rectangle, 50, 50, 420, 220)
    shape.getFillFormat().setFillType(FillType.NoFill)
    shape.getLineFormat().getFillFormat().setFillType(FillType.Solid)
    shape.getLineFormat().getFillFormat().getSolidFillColor().setColor(Color.GRAY)

    text_frame = shape.getTextFrame()
    text_frame.getTextFrameFormat().setAutofitType(TextAutofitType.Shape)
    text_frame.getParagraphs().clear()

    first_paragraph = Paragraph()
    first_paragraph.setText("A hanging indent is created by combining a positive left margin with a negative indent. The first line starts to the left, while wrapped lines align with the paragraph body.")
    first_paragraph.getParagraphFormat().getDefaultPortionFormat().getFillFormat().setFillType(FillType.Solid)
    first_paragraph.getParagraphFormat().getDefaultPortionFormat().getFillFormat().getSolidFillColor().setColor(Color.BLACK)
    first_paragraph.getParagraphFormat().setMarginLeft(40.0)
    first_paragraph.getParagraphFormat().setIndent(-20.0)

    second_paragraph = Paragraph()
    second_paragraph.setText("This second example uses a deeper hanging indent so the difference between the first line and the wrapped lines is easier to compare.")
    second_paragraph.getParagraphFormat().getDefaultPortionFormat().getFillFormat().setFillType(FillType.Solid)
    second_paragraph.getParagraphFormat().getDefaultPortionFormat().getFillFormat().getSolidFillColor().setColor(Color.BLACK)
    second_paragraph.getParagraphFormat().setMarginLeft(60.0)
    second_paragraph.getParagraphFormat().setIndent(-30.0)

    text_frame.getParagraphs().add(first_paragraph)
    text_frame.getParagraphs().add(second_paragraph)

    presentation.save("hanging_indent.pptx", SaveFormat.Pptx)
finally:
    presentation.dispose()

结果:

段落的悬挂缩进

设置段落结束运行属性

Paragraph.setEndParagraphPortionFormat 方法控制段落结束标记的格式。下面示例创建了一个 PortionFormat ,其中 BasePortionFormat.setFontHeight 为 48 磅,BasePortionFormat.setLatinFont 为 Times New Roman。它将此格式分配给第二段落的结束标记,而可见的文本部分保持不变:

import jpype
import asposeslides

if not jpype.isJVMStarted():
    jpype.startJVM()

from asposeslides.api import FontData, Paragraph, Portion, PortionFormat, Presentation, SaveFormat, ShapeType

presentation = Presentation("Test.pptx")
try:
    slide = presentation.getSlides().get_Item(0)

    shape = slide.getShapes().addAutoShape(ShapeType.Rectangle, 10, 10, 200, 250)
    text_frame = shape.getTextFrame()
    text_frame.getParagraphs().clear()

    first_paragraph = Paragraph()
    first_portion = Portion("Sample text")
    first_paragraph.getPortions().add(first_portion)

    second_paragraph = Paragraph()
    second_portion = Portion("Sample text 2")
    second_paragraph.getPortions().add(second_portion)

    end_paragraph_format = PortionFormat()
    end_paragraph_format.setFontHeight(48)
    latin_font = FontData("Times New Roman")
    end_paragraph_format.setLatinFont(latin_font)
    second_paragraph.setEndParagraphPortionFormat(end_paragraph_format)

    text_frame.getParagraphs().add(first_paragraph)
    text_frame.getParagraphs().add(second_paragraph)

    presentation.save("end_paragraph_format.pptx", SaveFormat.Pptx)
finally:
    presentation.dispose()

统计渲染行数

有关影响自动换行和行尾标点的段落规则,请参阅 Control Line Breaking 和 Control Hanging Punctuation。

使用 Paragraph.getLinesCount 可统计段落在文本布局后占用的行数,包括自动换行。这在检查演示文稿模板中的文本长度和布局时非常有用。

段落是 TextFrame.getParagraphs 中的一个项目,并且可以占据多行渲染。段落内部的显式换行会强制换行但不创建新段落。自动换行根据可用宽度创建行,而不会在文本中插入显式换行符。因此,仅统计段落或换行符字符并不能得到渲染行数。

以下示例创建一个文本形状,统计其行数,随后缩窄形状,再将文本替换为更短的字符串。示例通过 TextFrameFormat.setWrapText 启用换行,并通过 TextFrameFormat.setAutofitType 禁用自动适配,以便形状宽度控制换行而不自动缩小文本或调整形状尺寸。每次测量均使用 Paragraph.getLinesCount。形状尺寸使用磅为单位。最后,示例添加另一个段落并汇总文本框中的行数。

import jpype
import asposeslides

if not jpype.isJVMStarted():
    jpype.startJVM()

from asposeslides.api import NullableBool, Paragraph, Presentation, ShapeType, TextAutofitType

presentation = Presentation()
try:
    slide = presentation.getSlides().get_Item(0)

    shape = slide.getShapes().addAutoShape(ShapeType.Rectangle, 50, 50, 400, 200)
    text_frame = shape.getTextFrame()
    text_frame.getTextFrameFormat().setWrapText(NullableBool.True_)
    text_frame.getTextFrameFormat().setAutofitType(TextAutofitType.None_)

    paragraph = text_frame.getParagraphs().get_Item(0)
    paragraph.getParagraphFormat().getDefaultPortionFormat().setFontHeight(20)
    paragraph.setText("This text demonstrates how automatic wrapping changes the number of rendered lines.")
    print("Original width:", paragraph.getLinesCount())

    shape.setWidth(150)
    print("Narrower shape:", paragraph.getLinesCount())

    paragraph.setText("Short text.")
    print("Shorter text:", paragraph.getLinesCount())

    second_paragraph = Paragraph()
    second_paragraph.setText("Another paragraph.")
    second_paragraph.getParagraphFormat().getDefaultPortionFormat().setFontHeight(20)
    text_frame.getParagraphs().add(second_paragraph)

    total_line_count = 0
    for current_paragraph in text_frame.getParagraphs():
        total_line_count += current_paragraph.getLinesCount()
    print("Total lines in the text frame:", total_line_count)
finally:
    presentation.dispose()

在此文本和这些尺寸下,缩窄形状会增加行数,而将文本替换为短字符串会减少行数。精确计数可能随字体可用性及替换、字体大小、边距、缩进、换行和自动适配设置而变化。检查模板时请使用目标环境的字体和布局设置。

仅行数并不能决定文本是否溢出容器。可用高度、行高、段落和行间距以及自动适配行为也会影响;即使是一行文本,在关闭换行时也可能超过可用宽度。

导入和导出段落内容

使用 HTML 将文本导入演示文稿,或将现有段落导出供外部使用。本节还展示如何将单个段落渲染为图像,包括表格单元格中的段落。

将 HTML 文本导入段落

使用 ParagraphCollection.addFromHtml 将 HTML 标记转换为文本框中的段落和部分。

此 Python 示例从文件读取 HTML 并将标记传递给 ParagraphCollection.addFromHtml。它清除文本框的默认段落,使框仅包含导入的内容。矩形形状在幻灯片每侧留有 10 磅的边距:

import jpype
import asposeslides

if not jpype.isJVMStarted():
    jpype.startJVM()

from asposeslides.api import FillType, Presentation, SaveFormat, ShapeType
from pathlib import Path

presentation = Presentation()
try:
    slide = presentation.getSlides().get_Item(0)

    shape_width = presentation.getSlideSize().getSize().getWidth() - 20
    shape_height = presentation.getSlideSize().getSize().getHeight() - 20

    shape = slide.getShapes().addAutoShape(ShapeType.Rectangle, 10, 10, shape_width, shape_height)
    shape.getFillFormat().setFillType(FillType.NoFill)
    shape.getTextFrame().getParagraphs().clear()

    try:
        html = Path("file.html").read_text(encoding="utf-8")
        shape.getTextFrame().getParagraphs().addFromHtml(html)

        presentation.save("html_text.pptx", SaveFormat.Pptx)
    except OSError as exception:
        print("The HTML file could not be read: " + str(exception))
finally:
    presentation.dispose()

将段落文本导出为 HTML

使用 ParagraphCollection.exportToHtml 将选定范围的段落导出为 HTML。将演示文稿文本重新用于网站时,您可能希望保留本地强调而不携带演示文稿的字体、大小或文本框样式。通过设置 TextToHtmlConversionOptions.setTextInheritanceLimit 可以控制导出器遵循格式继承的深度。

下载 示例演示文稿 并将其放置在应用程序工作目录中。其第一张幻灯片包含一个带有文本 “Inherited text; explicit red 18pt” 的文本形状。输入特意使用了多个格式层级:

  • 演示文稿的默认文本样式提供 Calibri 字体,大小为 28 磅。
  • 文本框的一级文本样式提供蓝色文本和斜体。
  • 段落显式设置为粗体。
  • 第二个部分 “explicit red 18pt” 显式设置为红色文本,大小为 18 磅。

以下完整示例分别三次导出相同的段落。它将 TextToHtmlConversionOptions 传递给导出方法,并将每个结果写入单独的 UTF-8 HTML 文件:

import jpype
import asposeslides
from pathlib import Path

if not jpype.isJVMStarted():
    jpype.startJVM()

from asposeslides.api import AutoShape, Presentation, TextInheritanceLimit, TextToHtmlConversionOptions

presentation = Presentation("text-inheritance.pptx")
try:
    shape = presentation.getSlides().get_Item(0).getShapes().get_Item(0)

    if isinstance(shape, AutoShape):
        text_frame = shape.getTextFrame()
        if text_frame is not None:
            paragraphs = text_frame.getParagraphs()
            
            modes = [TextInheritanceLimit.All, TextInheritanceLimit.TextBox, TextInheritanceLimit.ParagraphOnly]
            file_names = ["All.html", "TextBox.html", "ParagraphOnly.html"]

            for mode, file_name in zip(modes, file_names):
                options = TextToHtmlConversionOptions()
                options.setTextInheritanceLimit(mode)

                html = paragraphs.exportToHtml(0, paragraphs.getCount(), options)
                try:
                    Path(file_name).write_text(str(html), encoding="utf-8")
                except OSError as exception:
                    print("The HTML file could not be written: " + str(exception))
        else:
            print("The first shape does not contain a text frame.")
    else:
        print("The first shape is not a text shape.")
finally:
    presentation.dispose()

生成的 HTML 对第一个部分 “Inherited text; ” 包含如下 CSS。表格列出相关声明,其他生成的属性为简洁起见被省略。

输出 第一个部分的相关 CSS 外观
All.html font-family:'Calibri'; font-size:28pt; color:#0000ff; font-style:italic; font-weight:bold 蓝色、粗体、斜体文本,28 pt,使用 Calibri(如果该字体可用)。
TextBox.html color:#0000ff; font-style:italic; font-weight:bold 蓝色、粗体、斜体文本;字体族和大小由页面或浏览器提供。
ParagraphOnly.html font-weight:bold 粗体文本;字体族、大小、颜色和斜体由页面或浏览器提供。

第二个部分在所有三个输出中均保留 color:#ff0000、font-size:18pt 和 font-weight:bold。在 All 与 TextBox 中保留斜体,而 ParagraphOnly 中不保留。限制继承并不会移除显式分配给段落或部分的格式。

在同一浏览器中打开这些文件进行比较。在两种受限模式下,省略的 CSS 属性由目标页面的样式或浏览器默认值解析,因此最终外观取决于 HTML 的使用位置。

生成 HTML 剪贴板片段

使用 TextToHtmlConversionOptions.setAddClipboardFragmentHeader 选择 ParagraphCollection.exportToHtml 的输出格式。设为 False 时,方法返回普通 HTML;设为 True 时,会在前面添加 Windows 剪贴板头。StartHTML 与 EndHTML 字段提供 HTML 的 UTF-8 字节偏移,StartFragment 与 EndFragment 字段标记要粘贴的内容范围。

此示例将两个格式化段落分别导出为普通 HTML (html) 和 HTML 剪贴板片段 (clipboard_html)。应用程序随后可以将片段写入系统剪贴板。如果剪贴板 API 期望原始字节,请使用 clipboard_html.encode("utf-8") 对片段进行编码,且不带字节顺序标记 (BOM)。

import jpype
import asposeslides

if not jpype.isJVMStarted():
    jpype.startJVM()

from asposeslides.api import Presentation, ShapeType, TextToHtmlConversionOptions

presentation = Presentation()
try:
    slide = presentation.getSlides().get_Item(0)
    
    shape = slide.getShapes().addAutoShape(ShapeType.Rectangle, 0, 0, 400, 100)
    paragraphs = shape.getTextFrame().getParagraphs()
    paragraphs.clear()
    paragraphs.addFromHtml("<p>Status: <b>Ready</b></p><p><i>Next steps</i></p>")

    options = TextToHtmlConversionOptions()
    options.setAddClipboardFragmentHeader(False)
    html = str(paragraphs.exportToHtml(0, paragraphs.getCount(), options))

    options.setAddClipboardFragmentHeader(True)
    clipboard_html = str(paragraphs.exportToHtml(0, paragraphs.getCount(), options))
finally:
    presentation.dispose()

将段落渲染为图像

Paragraph.getImage 直接渲染单个段落并返回图像对象。使用其 save 方法将结果保存到文件或流中。无需渲染包含的形状或手动裁剪位图。

如果段落在父集合中未找到、没有有效的渲染边界,或无法渲染,Paragraph.getImage 可能返回 None。在保存之前检查返回值,并在使用后释放返回的图像。

按默认比例渲染段落

示例使用一个包含三段落的文本框的演示文稿。

包含三段落的文本框

以下示例在索引为 1 的位置选择第二段落,并在不传入比例参数的情况下调用 Paragraph.getImage。它检查形状是否包含所需段落,并在渲染返回图像后调用其 save 方法以 PNG 格式保存。finally 块在使用后释放图像。

import jpype
import asposeslides

if not jpype.isJVMStarted():
    jpype.startJVM()

from asposeslides.api import AutoShape, ImageFormat, Presentation

presentation = Presentation("sample.pptx")
try:
    shape = presentation.getSlides().get_Item(0).getShapes().get_Item(0)

    if isinstance(shape, AutoShape):
        text_shape = shape
        text_frame = text_shape.getTextFrame()
        if text_frame is not None and text_frame.getParagraphs().getCount() > 1:
            paragraph = text_frame.getParagraphs().get_Item(1)
            paragraph_image = paragraph.getImage()

            if paragraph_image is not None:
                try:
                    paragraph_image.save("paragraph.png", ImageFormat.Png)
                finally:
                    paragraph_image.dispose()
            else:
                print("The paragraph could not be rendered.")
        else:
            print("The expected paragraph was not found.")
    else:
        print("The first shape is not a text shape.")
finally:
    presentation.dispose()

结果:

段落图像

在表格单元格中按比例渲染段落

使用接受 scale_x 和 scale_y 参数的 Paragraph.getImage 重载来设置水平和垂直比例因子。以下示例创建一个表格,在其第一个单元格中以两倍默认宽高渲染段落,并将结果保存为 PNG 图像。

import jpype
import asposeslides

if not jpype.isJVMStarted():
    jpype.startJVM()

from asposeslides.api import ImageFormat, Presentation

scale_x = 2.0
scale_y = 2.0
presentation = Presentation()
try:
    slide = presentation.getSlides().get_Item(0)

    table = slide.getShapes().addTable(50, 50, [300.0], [80.0])

    paragraph = table.get_Item(0, 0).getTextFrame().getParagraphs().get_Item(0)
    paragraph.setText("Text in a table cell")

    paragraph_image = paragraph.getImage(scale_x, scale_y)

    if paragraph_image is not None:
        try:
            paragraph_image.save("table_paragraph.png", ImageFormat.Png)
        finally:
            paragraph_image.dispose()
    else:
        print("The paragraph could not be rendered.")
finally:
    presentation.dispose()

比例因子为 1 时保持该轴的默认像素大小。例如,两个因子均为 2 时,生成的图像宽高约为默认尺寸的两倍,像素数约为四倍。较大因子通常可为缩放或高分辨率输出提供更清晰的文本,但也会增加内存使用和文件大小。小于 1 的因子会生成更小且细节更少的图像。使用相等的因子可保持段落的纵横比;水平和垂直因子不同会分别拉伸输出。

在需要包括形状填充、边框或其他视觉上下文的情况下,使用 Shape.getImage 渲染整个形状仍然有用。仅需段落图像时,请使用 Paragraph.getImage。

常见问题

我可以完全禁用文本框内的换行吗?

可以。将 TextFrameFormat.setWrapText 设置为关闭换行,使行不会在文本框边缘断开。

如何获取特定段落在幻灯片上的精确边界?

使用 Paragraph.getRect 获取段落的外接矩形。Portion.getRect 提供单个部分的边界。

段落对齐(左、右、居中或两端对齐)在哪里控制?

ParagraphFormat.setAlignment 是段落级设置,适用于整个段落,而不受各部分单独格式的影响。

要在每行内纵向对齐不同字体大小的部分,请参阅 Align Fonts Within a Line。

我可以为段落的部分设置校对语言吗?

可以。为各部分设置 BasePortionFormat.setLanguageId,即可在同一段落中包含多语言文本。