Zarządzanie placeholderami prezentacji w Pythonie

O czym jest ta strona

Dowiedz się, jak przeglądać i edytować placeholdery tekstu, obrazu, wykresu i treści oraz zrozumieć dziedziczenie placeholderów przy użyciu Aspose.Slides dla Pythona poprzez Java.

Przegląd

Placeholder to kształt, który rezerwuje pozycję dla określonego rodzaju treści w szablonie prezentacji. Typowymi przykładami są tytuł, ciało, obraz, wykres i ogólne placeholdery treści. W przeciwieństwie do zwykłego kształtu, placeholder może dziedziczyć swoją pozycję, rozmiar, formatowanie i inne ustawienia z slajdu układu lub slajdu master.

Aspose.Slides udostępnia informacje o placeholderach poprzez metodę Shape.getPlaceholder. Metoda zwraca obiekt Placeholder lub None dla zwykłego kształtu. Użyj Placeholder.getType, aby określić, co placeholder ma zawierać.

Typ kształtu nadal ma znaczenie po poznaniu typu placeholdera:

Pusty placeholder tekstu, obrazu, wykresu lub treści jest zwykle reprezentowany przez AutoShape.
Wypełniony placeholder obrazu może być reprezentowany przez PictureFrame.
Wypełniony placeholder wykresu może być reprezentowany przez Chart.
Placeholder treści może zawierać różne rodzaje treści. Sprawdzaj zarówno Placeholder.getType, jak i typ kształtu w czasie wykonywania, zamiast zakładać, że każdy placeholder jest AutoShape.

Ostrzeżenie

Placeholder.getType opisuje rolę placeholdera; nie gwarantuje on typu kształtu w czasie wykonywania. Zawsze sprawdzaj typ przed dostępem do elementów specyficznych dla tekstu, obrazu, wykresu, tabeli lub multimediów.

Zrozumienie dziedziczenia placeholderów

Placeholdery tworzą hierarchię:

Slajd master definiuje style wielokrotnego użytku i, w niektórych przypadkach, placeholdery na poziomie master.
Slajd układu definiuje rozmieszczenie używane przez jeden lub więcej zwykłych slajdów i może dziedziczyć po masterze.
Zwykły slajd zawiera placeholdery dla tego slajdu i może dziedziczyć po swoim układzie.

Wywołaj Shape.getBasePlaceholder, aby przejść jeden poziom wyżej w tej hierarchii. Placeholder slajdu zazwyczaj zwraca placeholder układu; placeholder układu może zwrócić placeholder master. Metoda zwraca None, gdy kształt nie ma podstawowego placeholdera.

Poniższy przykład wyświetla placeholdery na pierwszym slajdzie i raportuje ich podstawowe placeholdery:

import jpype
import asposeslides

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

from asposeslides.api import Presentation

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

    for shape in slide.getShapes():
        placeholder = shape.getPlaceholder()
        if placeholder is None:
            continue

        placeholder_type = placeholder.getType()
        type_name = shape.getClass().getSimpleName()
        print(f"Slide placeholder: {placeholder_type}; shape type: {type_name}")

        layout_placeholder = shape.getBasePlaceholder()
        if layout_placeholder is not None:
            layout_placeholder_info = layout_placeholder.getPlaceholder()
            layout_placeholder_type = None if layout_placeholder_info is None else layout_placeholder_info.getType()
            print(f"  Layout placeholder: {layout_placeholder_type}")

            master_placeholder = layout_placeholder.getBasePlaceholder()
            if master_placeholder is not None:
                master_placeholder_info = master_placeholder.getPlaceholder()
                master_placeholder_type = None if master_placeholder_info is None else master_placeholder_info.getType()
                print(f"  Master placeholder: {master_placeholder_type}")
finally:
    presentation.dispose()

Edycja placeholdera na zwykłym slajdzie tworzy lub zmienia lokalne nadpisanie dla tego slajdu. Edycja powiązanego układu lub mastera może wpływać na wszystkie slajdy, które nadal dziedziczą to ustawienie. Zwykły lokalny kształt nie ma podstawowego placeholdera i nie zaczyna dziedziczyć tylko dlatego, że zajmuje te same współrzędne.

Zmiana tekstu w placeholderze

Placeholdery typu tytuł, tytuł‑środkowy, podtytuł, ciało i tekst zazwyczaj obsługują tekst. Sprawdź, czy kształt jest AutoShape, zanim użyjesz jego metody getTextFrame.

Ten przykład aktualizuje pierwszy placeholder tytułu na pierwszym slajdzie i zapisuje wynik:

import jpype
import asposeslides

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

from asposeslides.api import Presentation, AutoShape, PlaceholderType, SaveFormat

presentation = Presentation("template.pptx")
try:
    slide = presentation.getSlides().get_Item(0)
    title_shape = None

    for shape in slide.getShapes():
        if not isinstance(shape, AutoShape):
            continue

        placeholder = shape.getPlaceholder()
        if placeholder is None:
            continue

        placeholder_type = placeholder.getType()
        if placeholder_type in (PlaceholderType.Title, PlaceholderType.CenteredTitle):
            title_shape = shape
            break

    if title_shape is None:
        print("The first slide does not contain a title placeholder.")
    else:
        title_shape.getTextFrame().setText("Quarterly Business Review")
        presentation.save("title-placeholder-updated.pptx", SaveFormat.Pptx)
finally:
    presentation.dispose()

Ten wzorzec unika traktowania placeholderów obrazu, wykresu, tabeli lub multimediów jako AutoShape. Identifikuje także placeholder po przeznaczeniu, zamiast polegać na kruchym indeksie kształtu.

Ustawienie tekstu podpowiedzi w układzie

Tekst podpowiedzi to instrukcja wyświetlana w pustym placeholderze w czasie projektowania, np. Kliknij, aby dodać tytuł. Ustaw niestandardowy tekst podpowiedzi w placeholderze układu, zamiast próbować dotrzeć do niego przez kolekcję kształtów zwykłego slajdu. Uzyskaj dostęp do układu przez Slide.getLayoutSlide i iteruj po kolekcji zwróconej przez BaseSlide.getShapes.

Poniższy przykład zmienia podpowiedzi tytułu i podtytułu w układzie używanym przez pierwszy slajd:

import jpype
import asposeslides

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

from asposeslides.api import Presentation, AutoShape, PlaceholderType, SaveFormat

presentation = Presentation("template.pptx")
try:
    layout_slide = presentation.getSlides().get_Item(0).getLayoutSlide()

    for shape in layout_slide.getShapes():
        if not isinstance(shape, AutoShape):
            continue

        placeholder = shape.getPlaceholder()
        if placeholder is None:
            continue

        placeholder_type = placeholder.getType()
        if placeholder_type in (PlaceholderType.Title, PlaceholderType.CenteredTitle):
            shape.getTextFrame().setText("Enter a concise slide title")
        elif placeholder_type == PlaceholderType.Subtitle:
            shape.getTextFrame().setText("Enter a subtitle or reporting period")

    presentation.save("custom-placeholder-prompts.pptx", SaveFormat.Pptx)
finally:
    presentation.dispose()

Tekst podpowiedzi nie jest normalną treścią slajdu. Jest przeznaczony dla pustych placeholderów w aplikacjach edycyjnych, takich jak PowerPoint. Po tym, jak użytkownik lub program dostarczy rzeczywistą treść, podpowiedź przestaje być wyświetlana. Zmiana podpowiedzi nie zastępuje istniejącego tekstu na slajdach, które używają tego układu.

Aktualizacja placeholdera obrazu

Obsługiwane są dwa przypadki:

Jeśli placeholder obrazu jest już wypełniony i reprezentowany przez PictureFrame, zamień obraz przy użyciu PictureFillFormat.getPicture i Picture.setImage.
Jeśli jest nadal pustym placeholderem, dodaj ramkę obrazu w współrzędnych placeholdera przy użyciu ShapeCollection.addPictureFrame i usuń pusty placeholder.

Kolejny przykład obsługuje oba przypadki i zapisuje prezentację:

from pathlib import Path

import jpype
import asposeslides

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

from asposeslides.api import Presentation, PictureFrame, PlaceholderType, ShapeType, SaveFormat

presentation = Presentation("picture-template.pptx")
try:
    slide = presentation.getSlides().get_Item(0)
    picture_placeholder = None

    for shape in slide.getShapes():
        placeholder = shape.getPlaceholder()
        if placeholder is not None and placeholder.getType() == PlaceholderType.Picture:
            picture_placeholder = shape
            break

    if picture_placeholder is None:
        print("The first slide does not contain a picture placeholder.")
    else:
        image_bytes = Path("replacement.png").read_bytes()
        java_image_bytes = jpype.JArray(jpype.JByte)(image_bytes)
        image = presentation.getImages().addImage(java_image_bytes)

        if isinstance(picture_placeholder, PictureFrame):
            picture_placeholder.getPictureFormat().getPicture().setImage(image)
        else:
            slide.getShapes().addPictureFrame(ShapeType.Rectangle, picture_placeholder.getX(), picture_placeholder.getY(), picture_placeholder.getWidth(), picture_placeholder.getHeight(), image)
            slide.getShapes().remove(picture_placeholder)

        presentation.save("picture-placeholder-updated.pptx", SaveFormat.Pptx)
finally:
    presentation.dispose()

Zamiennik utworzony dla pustego placeholdera jest lokalną ramką obrazu, a nie nowym placeholderem, ponieważ Shape.getPlaceholder nie udostępnia setter‑a. Zachowuje zarezerwowaną pozycję, ale nie dziedziczy już zachowań specyficznych dla placeholdera. Jeśli utrzymanie relacji placeholdera jest istotne, przygotuj i wypełnij placeholder w PowerPoint, a następnie zaktualizuj powstały PictureFrame przy użyciu Aspose.Slides.

W celu uzyskania przezroczystości obrazu, przycinania i innych efektów specyficznych dla obrazu, zobacz Manage Picture Frames. Operacje te dotyczą ramki obrazu lub wypełnienia obrazu, a nie metadanych placeholdera.

Praca z placeholderami wykresów i treści

Wypełniony placeholder wykresu może być reprezentowany przez Chart. Ten przykład znajduje taki wykres zarówno po typie placeholdera, jak i typie runtime, zmienia jego tytuł i zapisuje plik:

import jpype
import asposeslides

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

from asposeslides.api import Presentation, Chart, PlaceholderType, SaveFormat

presentation = Presentation("chart-template.pptx")
try:
    slide = presentation.getSlides().get_Item(0)
    placeholder_chart = None

    for shape in slide.getShapes():
        if not isinstance(shape, Chart):
            continue

        placeholder = shape.getPlaceholder()
        if placeholder is not None and placeholder.getType() == PlaceholderType.Chart:
            placeholder_chart = shape
            break

    if placeholder_chart is None:
        print("The first slide does not contain a populated chart placeholder.")
    else:
        placeholder_chart.setTitle(True)
        placeholder_chart.getChartTitle().addTextFrameForOverriding("Quarterly Revenue")
        presentation.save("chart-placeholder-updated.pptx", SaveFormat.Pptx)
finally:
    presentation.dispose()

Ogólny placeholder treści zazwyczaj ma typ PlaceholderType.Object. W PowerPoint działa jako uruchamiacz dla wielu typów treści, w tym wykresów, tabel, diagramów, obrazów i multimediów. Po wypełnieniu, sprawdź rzeczywisty typ kształtu, aby dowiedzieć się, co zawiera. Specjalistyczne układy mogą także eksponować PlaceholderType.Chart, PlaceholderType.Table, PlaceholderType.Picture, PlaceholderType.Media lub PlaceholderType.Diagram.

Aspose.Slides nie konwertuje pustego placeholdera AutoShape na Chart jedynie poprzez zmianę Placeholder.getType; typ nie może być zmieniony przez API. Aby wypełnić pusty obszar wykresu lub treści programowo, dodaj wymagany obiekt w współrzędnych placeholdera, a następnie usuń pusty placeholder. Poniższy przykład robi to dla wykresu:

import jpype
import asposeslides

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

from asposeslides.api import Presentation, PlaceholderType, ChartType, SaveFormat

presentation = Presentation("content-template.pptx")
try:
    slide = presentation.getSlides().get_Item(0)
    target_placeholder = None

    for shape in slide.getShapes():
        placeholder = shape.getPlaceholder()
        if placeholder is None:
            continue

        placeholder_type = placeholder.getType()
        if placeholder_type in (PlaceholderType.Chart, PlaceholderType.Object):
            target_placeholder = shape
            break

    if target_placeholder is None:
        print("The first slide does not contain a chart or content placeholder.")
    else:
        chart = slide.getShapes().addChart(ChartType.ClusteredColumn, target_placeholder.getX(), target_placeholder.getY(), target_placeholder.getWidth(), target_placeholder.getHeight())
        chart.setTitle(True)
        chart.getChartTitle().addTextFrameForOverriding("Quarterly Revenue")
        slide.getShapes().remove(target_placeholder)
        presentation.save("content-placeholder-replaced-with-chart.pptx", SaveFormat.Pptx)
finally:
    presentation.dispose()

Dodany wykres jest zwykłym lokalnym wykresem. Zajmuje obszar placeholdera, ale nie dziedziczy z placeholdera układu. Skorzystaj z dedykowanych artykułów o zarządzaniu wykresami chart management articles, gdy potrzebujesz zastąpić kategorie, serie lub dane skoroszytu.

Pełny przykład: aktualizacja tekstu lub obrazu

Poniższy przykład end‑to‑end otwiera szablon, przeszukuje pierwszy slajd w poszukiwaniu placeholdera tytułu lub obrazu, sprawdza typy placeholdera i kształtu, aktualizuje odpowiednią treść i zapisuje wynik. Przykład świadomie unika zakładania indeksu kształtu lub traktowania każdego placeholdera jako tego samego typu.

from pathlib import Path

import jpype
import asposeslides

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

from asposeslides.api import Presentation, AutoShape, PictureFrame, PlaceholderType, ShapeType, SaveFormat

presentation = Presentation("template.pptx")
try:
    slide = presentation.getSlides().get_Item(0)
    updated = False

    for shape in slide.getShapes():
        placeholder = shape.getPlaceholder()
        if placeholder is None:
            continue

        placeholder_type = placeholder.getType()
        if placeholder_type in (PlaceholderType.Title, PlaceholderType.CenteredTitle) and isinstance(shape, AutoShape):
            shape.getTextFrame().setText("Quarterly Business Review")
            updated = True
            break

        if placeholder_type == PlaceholderType.Picture:
            image_bytes = Path("replacement.png").read_bytes()
            java_image_bytes = jpype.JArray(jpype.JByte)(image_bytes)
            image = presentation.getImages().addImage(java_image_bytes)

            if isinstance(shape, PictureFrame):
                shape.getPictureFormat().getPicture().setImage(image)
            else:
                slide.getShapes().addPictureFrame(ShapeType.Rectangle, shape.getX(), shape.getY(), shape.getWidth(), shape.getHeight(), image)
                slide.getShapes().remove(shape)

            updated = True
            break

    if updated:
        presentation.save("placeholder-content-updated.pptx", SaveFormat.Pptx)
    else:
        print("No supported title or picture placeholder was found on the first slide.")
finally:
    presentation.dispose()

FAQ

Czym jest podstawowy placeholder?

Podstawowy placeholder to odpowiadający mu kształt w układzie lub masterze, z którego inny placeholder dziedziczy. Użyj Shape.getBasePlaceholder, aby go pobrać. Zwykły lokalny kształt zwraca None, ponieważ nie jest częścią hierarchii placeholderów.

Czy mogę zmienić wszystkie tytuły slajdów, edytując placeholder w układzie?

Możesz zmienić dziedziczone formatowanie lub tekst podpowiedzi poprzez układ, ale istniejąca treść tytułu jest przechowywana na normalnych slajdach. Aby zastąpić rzeczywisty tekst tytułu w całej prezentacji, iteruj po slajdach i aktualizuj każdy placeholder tytułu.

Jak zarządzać placeholderami daty, numeru slajdu, nagłówka i stopki?

Użyj menedżerów nagłówka i stopki na odpowiednim poziomie: slajd, układ, master, notatki lub rozdanie. Zobacz Manage Presentation Header and Footer po pełne przykłady.

Zarządzanie polami tekstowymi w prezentacjach przy użyciu Pythona via Java