在 Python 中管理演示文稿占位符

本页内容简介

了解如何使用 Aspose.Slides for Python via .NET 检查和编辑文本、图片、图表和内容占位符，并理解占位符继承。

概述

占位符是一种形状，用于在演示文稿模板中为特定类型的内容保留位置。常见示例包括标题、正文、图片、图表以及通用内容占位符。与普通形状不同，占位符可以从布局幻灯片或母版幻灯片继承其位置、大小、格式以及其他设置。

Aspose.Slides 通过 Shape.placeholder 属性公开占位符信息。该属性返回一个 Placeholder 对象，普通形状则返回 None。使用 Placeholder.type 可以确定占位符意在包含何种内容。

了解占位符类型后，形状类仍然很重要：

空的文本、图片、图表或内容占位符通常由 AutoShape 表示。
已填充的图片占位符可以由 PictureFrame 表示。
已填充的图表占位符可以由 Chart 表示。
内容占位符可以包含多种内容。请同时检查 Placeholder.type 与运行时的形状类，而不要假设每个占位符都是 AutoShape。

Warning

Placeholder.type 描述了占位符的角色；它并不能保证形状的运行时类。在访问文本、图片、图表、表格或媒体特定成员之前，请始终进行类型检查。

了解占位符继承

占位符形成层次结构：

母版幻灯片定义可复用的样式，并在某些情况下提供母版级别的占位符。
布局幻灯片定义供一个或多个普通幻灯片使用的布局，并可以从母版继承。
普通幻灯片包含该幻灯片的占位符，并可以从其布局继承。

调用 Shape.get_base_placeholder 可向上移动一层层次。幻灯片占位符通常返回其布局占位符；布局占位符可以返回其母版占位符。当形状没有基础占位符时，该方法返回 None。

下面的示例列出第一张幻灯片上的占位符并报告它们的基础占位符：

import aspose.slides as slides

with slides.Presentation("template.pptx") as presentation:
    slide = presentation.slides[0]

    for shape in slide.shapes:
        if shape.placeholder is None:
            continue

        placeholder_type = shape.placeholder.type
        type_name = type(shape).__name__
        print(f"Slide placeholder: {placeholder_type}; shape class: {type_name}")

        layout_placeholder = shape.get_base_placeholder()
        if layout_placeholder is not None:
            layout_placeholder_type = layout_placeholder.placeholder.type if layout_placeholder.placeholder is not None else None
            print(f"  Layout placeholder: {layout_placeholder_type}")

            master_placeholder = layout_placeholder.get_base_placeholder()
            if master_placeholder is not None:
                master_placeholder_type = master_placeholder.placeholder.type if master_placeholder.placeholder is not None else None
                print(f"  Master placeholder: {master_placeholder_type}")

在普通幻灯片上编辑占位符会为该幻灯片创建或更改本地覆盖。编辑相关的布局或母版可能会影响仍然继承该设置的所有幻灯片。本地普通形状没有基础占位符，仅因占据相同坐标而不会开始继承。

在占位符中更改文本

标题、居中标题、副标题、正文以及文本占位符通常支持文本。在使用其 text_frame 属性之前，请先检查是否为 AutoShape。

以下示例更新第一张幻灯片上的第一个标题占位符并保存结果：

import aspose.slides as slides

with slides.Presentation("template.pptx") as presentation:
    slide = presentation.slides[0]
    title_shape = None

    for shape in slide.shapes:
        if not isinstance(shape, slides.AutoShape) or shape.placeholder is None:
            continue

        placeholder_type = shape.placeholder.type
        if placeholder_type in (slides.PlaceholderType.TITLE, slides.PlaceholderType.CENTERED_TITLE):
            title_shape = shape
            break

    if title_shape is None:
        raise RuntimeError("The first slide does not contain a title placeholder.")

    title_shape.text_frame.text = "Quarterly Business Review"
    presentation.save("title-placeholder-updated.pptx", slides.export.SaveFormat.PPTX)

此模式避免将图片、图表、表格或媒体占位符误当作 AutoShape 对象处理。它还通过占位符的用途来识别，而不是依赖脆弱的形状索引。

在布局上设置提示文本

提示文本是空占位符中显示的设计时指令，例如 单击以添加标题。请在布局占位符上设置自定义提示文本，而不是通过普通幻灯片的形状集合去获取。通过 Slide.layout_slide 访问布局，并遍历 LayoutSlide.shapes。

下面的示例更改第一张幻灯片所使用布局的标题和副标题提示：

import aspose.slides as slides

with slides.Presentation("template.pptx") as presentation:
    layout_slide = presentation.slides[0].layout_slide

    for shape in layout_slide.shapes:
        if not isinstance(shape, slides.AutoShape) or shape.placeholder is None:
            continue

        placeholder_type = shape.placeholder.type

        if placeholder_type in (slides.PlaceholderType.TITLE, slides.PlaceholderType.CENTERED_TITLE):
            shape.text_frame.text = "Enter a concise slide title"
        elif placeholder_type == slides.PlaceholderType.SUBTITLE:
            shape.text_frame.text = "Enter a subtitle or reporting period"

    presentation.save("custom-placeholder-prompts.pptx", slides.export.SaveFormat.PPTX)

提示文本并非普通幻灯片内容。它旨在供 PowerPoint 等编辑应用在空占位符中显示。一旦用户或程序提供了真实内容，提示将不再显示。更改提示也不会替换使用该布局的幻灯片上已有的文本。

更新图片占位符

需要处理两种情况：

如果图片占位符已经填充并由 PictureFrame 表示，请通过 PictureFillFormat.picture 和 Picture.image 替换图像。
如果仍是空占位符，请使用 ShapeCollection.add_picture_frame 在占位符坐标处添加图片框，并删除空占位符。

下面的示例同时支持这两种情况并保存演示文稿：

import aspose.slides as slides

with slides.Presentation("picture-template.pptx") as presentation:
    slide = presentation.slides[0]
    picture_placeholder = None

    for shape in slide.shapes:
        if shape.placeholder is not None and shape.placeholder.type == slides.PlaceholderType.PICTURE:
            picture_placeholder = shape
            break

    if picture_placeholder is None:
        raise RuntimeError("The first slide does not contain a picture placeholder.")

    with open("replacement.png", "rb") as image_stream:
        image_bytes = image_stream.read()

    image = presentation.images.add_image(image_bytes)

    if isinstance(picture_placeholder, slides.PictureFrame):
        picture_placeholder.picture_format.picture.image = image
    else:
        slide.shapes.add_picture_frame(slides.ShapeType.RECTANGLE, picture_placeholder.x, picture_placeholder.y, picture_placeholder.width, picture_placeholder.height, image)
        slide.shapes.remove(picture_placeholder)

    presentation.save("picture-placeholder-updated.pptx", slides.export.SaveFormat.PPTX)

为一个空占位符创建的替代对象是本地图片框，而不是新占位符，因为 Shape.placeholder 为只读属性。它保留了预留位置，但不再继承占位符特有的行为。如果必须保留占位符关系，请先在 PowerPoint 中准备并填充占位符，然后使用 Aspose.Slides 更新生成的 PictureFrame。

有关图像透明度、裁剪和其他图片特定效果，请参阅管理图片框。这些操作属于图片框或图片填充，而非占位符元数据。

处理图表和内容占位符

已填充的图表占位符可以由 Chart 表示。以下示例通过占位符类型和运行时类同时查找此类图表，修改其标题并保存文件：

import aspose.slides as slides
import aspose.slides.charts as charts

with slides.Presentation("chart-template.pptx") as presentation:
    slide = presentation.slides[0]
    placeholder_chart = None

    for shape in slide.shapes:
        if isinstance(shape, charts.Chart) and shape.placeholder is not None and shape.placeholder.type == slides.PlaceholderType.CHART:
            placeholder_chart = shape
            break

    if placeholder_chart is None:
        raise RuntimeError("The first slide does not contain a populated chart placeholder.")

    placeholder_chart.has_title = True
    placeholder_chart.chart_title.add_text_frame_for_overriding("Quarterly Revenue")
    presentation.save("chart-placeholder-updated.pptx", slides.export.SaveFormat.PPTX)

普通内容占位符通常具有 PlaceholderType.OBJECT。在 PowerPoint 中，它充当多种内容类型的启动器，包括图表、表格、图示、图片和媒体。填充后，请检查实际形状类以了解其包含的内容。特定布局还可能公开 PlaceholderType.CHART、PlaceholderType.TABLE、PlaceholderType.PICTURE、PlaceholderType.MEDIA、PlaceholderType.DIAGRAM。

Aspose.Slides 不会仅通过更改 Placeholder.type（该属性只读）就将空的 AutoShape 占位符转换为 Chart。若要以编程方式填充空的图表或内容区域，请在占位符坐标处添加所需对象，然后删除空占位符。下面的示例为图表执行此操作：

import aspose.slides as slides
import aspose.slides.charts as charts

with slides.Presentation("content-template.pptx") as presentation:
    slide = presentation.slides[0]
    target_placeholder = None

    for shape in slide.shapes:
        if shape.placeholder is None:
            continue

        if shape.placeholder.type in (slides.PlaceholderType.CHART, slides.PlaceholderType.OBJECT):
            target_placeholder = shape
            break

    if target_placeholder is None:
        raise RuntimeError("The first slide does not contain a chart or content placeholder.")

    chart = slide.shapes.add_chart(charts.ChartType.CLUSTERED_COLUMN, target_placeholder.x, target_placeholder.y, target_placeholder.width, target_placeholder.height)
    chart.has_title = True
    chart.chart_title.add_text_frame_for_overriding("Quarterly Revenue")
    slide.shapes.remove(target_placeholder)
    presentation.save("content-placeholder-replaced-with-chart.pptx", slides.export.SaveFormat.PPTX)

添加的图表是普通本地图表。它占据占位符的区域，但不继承布局占位符的属性。需要替换其类别、序列或工作簿数据时，请使用专门的图表管理文章。

完整示例：更新文本或图像内容

下面的端到端示例打开模板，搜索第一张幻灯片上的标题或图片占位符，检查占位符和形状类型，更新相应内容并保存输出。示例刻意避免假设形状索引或将每个占位符视为相同的形状类。

import aspose.slides as slides

with slides.Presentation("template.pptx") as presentation:
    slide = presentation.slides[0]
    updated = False

    for shape in slide.shapes:
        if shape.placeholder is None:
            continue

        placeholder_type = shape.placeholder.type

        if placeholder_type in (slides.PlaceholderType.TITLE, slides.PlaceholderType.CENTERED_TITLE) and isinstance(shape, slides.AutoShape):
            shape.text_frame.text = "Quarterly Business Review"
            updated = True
            break

        if placeholder_type == slides.PlaceholderType.PICTURE:
            with open("replacement.png", "rb") as image_stream:
                image_bytes = image_stream.read()

            image = presentation.images.add_image(image_bytes)

            if isinstance(shape, slides.PictureFrame):
                shape.picture_format.picture.image = image
            else:
                slide.shapes.add_picture_frame(slides.ShapeType.RECTANGLE, shape.x, shape.y, shape.width, shape.height, image)
                slide.shapes.remove(shape)

            updated = True
            break

    if not updated:
        raise RuntimeError("No supported title or picture placeholder was found on the first slide.")

    presentation.save("placeholder-content-updated.pptx", slides.export.SaveFormat.PPTX)

常见问题

什么是基础占位符？

基础占位符是布局或母版上对应的形状，其他占位符从其继承。使用 Shape.get_base_placeholder 可获取它。普通本地形状返回 None，因为它不属于占位符层次结构。

我可以通过编辑布局占位符来更改所有幻灯片的标题吗？

可以通过布局更改继承的格式或提示文本，但现有的标题内容存放在普通幻灯片上。若要在整个演示文稿中替换实际标题文本，需要遍历幻灯片并逐个更新标题占位符。

如何管理日期、页码、页眉和页脚占位符？

请在相应的幻灯片、布局、母版、备注页或讲义范围内使用页眉页脚管理器。完整示例请参阅管理演示文稿页眉和页脚。

使用 Python 管理演示文稿中的文本框