Gestisci i segnaposti della presentazione in PHP

Panoramica

Un segnaposto è una forma che riserva una posizione per un particolare tipo di contenuto in un modello di presentazione. Esempi comuni sono segnaposto per titolo, corpo, immagine, grafico e segnaposti di contenuto generico. A differenza di una forma normale, un segnaposto può ereditare la sua posizione, dimensione, formattazione e altre impostazioni da una diapositiva layout o da una diapositiva master.

Aspose.Slides espone le informazioni sui segnaposti tramite il metodo Shape::getPlaceholder. Il metodo restituisce un oggetto Placeholder o null per una forma normale. Usa Placeholder::getType per determinare cosa il segnaposto è destinato a contenere.

La classe della forma è ancora importante dopo aver conosciuto il tipo di segnaposto:

  • Un segnaposto vuoto di testo, immagine, grafico o contenuto è comunemente rappresentato da un AutoShape.
  • Un segnaposto immagine popolato può essere rappresentato da un PictureFrame.
  • Un segnaposto grafico popolato può essere rappresentato da un Chart.
  • Un segnaposto di contenuto può contenere diversi tipi di contenuto. Controlla sia Placeholder::getType sia la classe della forma al runtime invece di presumere che ogni segnaposto sia un AutoShape.

Comprendere l’ereditarietà dei segnaposti

I segnaposti formano una gerarchia:

  1. Una diapositiva master definisce stili riutilizzabili e, in alcuni casi, segnaposti a livello master.
  2. Una diapositiva layout definisce la disposizione usata da una o più diapositive normali e può ereditare dal master.
  3. Una diapositiva normale contiene i segnaposti per quella diapositiva e può ereditare dal suo layout.

Chiama Shape::getBasePlaceholder per salire di un livello in questa gerarchia. Un segnaposto diapositiva restituisce normalmente il suo segnaposto layout; un segnaposto layout può restituire il suo segnaposto master. Il metodo restituisce null quando la forma non ha un segnaposto base.

Il seguente esempio elenca i segnaposti sulla prima diapositiva e riporta i loro segnaposti base:

use aspose\slides\Presentation;

$presentation = new Presentation("template.pptx");
try {
    $slide = $presentation->getSlides()->get_Item(0);
    $shapes = $slide->getShapes();
    $shapeCountValue = $shapes->size();
    $shapeCount = java_values($shapeCountValue);

    for ($shapeIndex = 0; $shapeIndex < $shapeCount; $shapeIndex++) {
        $shape = $shapes->get_Item($shapeIndex);
        $placeholder = $shape->getPlaceholder();
        if (java_is_null($placeholder)) {
            continue;
        }

        $placeholderTypeValue = $placeholder->getType();
        $placeholderType = java_values($placeholderTypeValue);
        $shapeClass = $shape->getClass();
        $shapeClassNameValue = $shapeClass->getSimpleName();
        $shapeClassName = java_values($shapeClassNameValue);
        echo "Slide placeholder: " . $placeholderType . "; shape class: " . $shapeClassName . PHP_EOL;

        $layoutPlaceholder = $shape->getBasePlaceholder();
        if (!java_is_null($layoutPlaceholder)) {
            $layoutPlaceholderInfo = $layoutPlaceholder->getPlaceholder();
            if (!java_is_null($layoutPlaceholderInfo)) {
                $layoutPlaceholderTypeValue = $layoutPlaceholderInfo->getType();
                $layoutPlaceholderType = java_values($layoutPlaceholderTypeValue);
                echo "  Layout placeholder: " . $layoutPlaceholderType . PHP_EOL;
            }

            $masterPlaceholder = $layoutPlaceholder->getBasePlaceholder();
            if (!java_is_null($masterPlaceholder)) {
                $masterPlaceholderInfo = $masterPlaceholder->getPlaceholder();
                if (!java_is_null($masterPlaceholderInfo)) {
                    $masterPlaceholderTypeValue = $masterPlaceholderInfo->getType();
                    $masterPlaceholderType = java_values($masterPlaceholderTypeValue);
                    echo "  Master placeholder: " . $masterPlaceholderType . PHP_EOL;
                }
            }
        }
    }
} finally {
    $presentation->dispose();
}

Modificare un segnaposto su una diapositiva normale crea o cambia una sovrascrittura locale per quella diapositiva. Modificare il layout o il master correlato può influenzare tutte le diapositive che ereditano ancora quella impostazione. Una forma ordinaria locale non ha un segnaposto base e non inizia a ereditare solo perché occupa le stesse coordinate.

Rimuovere lo Stato del Segnaposto

Durante l’adattamento di un modello, usa Shape::removePlaceholder per mantenere un oggetto esistente come una forma ordinaria. Il suo metodo getPlaceholder restituisce null, ma la forma rimane nella collezione della diapositiva. Al contrario, ShapeCollection::remove elimina la forma da quella collezione.

Il seguente esempio richiede template.pptx con almeno una diapositiva e un segnaposto di testo non vuoto sulla prima diapositiva. Usa un segnaposto con formattazione ereditata dal suo layout o master per vedere l’effetto della rimozione di quella relazione. L’esempio verifica che la stessa forma rimanga, chiama di nuovo il metodo sulla forma ora ordinaria e salva il risultato.

use aspose\slides\Presentation;
use aspose\slides\SaveFormat;

$presentation = new Presentation("template.pptx");
try {
    $slide = $presentation->getSlides()->get_Item(0);
    $shapeCount = java_values($slide->getShapes()->size());
    $autoShapeClass = new JavaClass("com.aspose.slides.AutoShape");
    $found = false;

    for ($shapeIndex = 0; $shapeIndex < $shapeCount; $shapeIndex++) {
        $shape = $slide->getShapes()->get_Item($shapeIndex);
        if (!java_instanceof($shape, $autoShapeClass)) {
            continue;
        }

        $placeholder = $shape->getPlaceholder();
        $textFrame = $shape->getTextFrame();
        if (java_is_null($placeholder) || java_is_null($textFrame)) {
            continue;
        }

        $textValue = $textFrame->getText();
        if (java_is_null($textValue)) {
            continue;
        }
        $text = java_values($textValue);
        if ($text === "") {
            continue;
        }

        $shape->removePlaceholder();

        $placeholder = $shape->getPlaceholder();
        $retainedShape = $slide->getShapes()->get_Item($shapeIndex);
        $sameShapeValue = $shape->equals($retainedShape);
        $sameShape = java_values($sameShapeValue);
        $remainingCountValue = $slide->getShapes()->size();
        $remainingCount = java_values($remainingCountValue);
        echo "Placeholder removed: " . (java_is_null($placeholder) ? "true" : "false") . PHP_EOL;
        echo "Same shape retained: " . ($sameShape ? "true" : "false") . PHP_EOL;
        echo "Shape count unchanged: " . ($remainingCount === $shapeCount ? "true" : "false") . PHP_EOL;

        // Chiamare il metodo su una forma ordinaria non ha effetto.
        $shape->removePlaceholder();
        $found = true;
        break;
    }

    if ($found) {
        $presentation->save("placeholder-status-removed.pptx", SaveFormat::Pptx);
    } else {
        echo "No nonempty text placeholder was found on the first slide." . PHP_EOL;
    }
} finally {
    $presentation->dispose();
}

Per un segnaposto corrispondente, tutti e tre i controlli stampano true. Il testo rimane, ma la posizione, dimensione, rotazione, font, allineamento del paragrafo, margini del text-frame, ancoraggio verticale, riempimento e impostazioni di linea ereditate possono cambiare quando la relazione del segnaposto viene rimossa. Ad esempio, la formattazione del titolo ereditata può tornare alla formattazione del testo ordinario. Vedi Slide Layout per ulteriori informazioni sui layout.

Per preservare l’aspetto previsto, cattura la posizione, dimensione e rotazione risolte prima della chiamata e copia i valori di formattazione efficace richiesti in variabili separate. Recupera tali valori tramite PortionFormat::getEffective, ParagraphFormat::getEffective, TextFrameFormat::getEffective, FillFormat::getEffective, e LineFormat::getEffective. Non fare affidamento solo sugli oggetti di formattazione efficace, perché i loro valori di formattazione del testo possono cambiare dopo la rimozione della relazione. Applica esplicitamente i valori catturati alla forma ordinaria successivamente, includendo famiglia di font, dimensione, stile, colore, impostazioni del paragrafo, impostazioni del text-frame, riempimento e linea utilizzati dal tuo modello.

La geometria della forma ereditata può anche dover essere assegnata esplicitamente tramite GeometryShape::setShapeType. Per un segnaposto di testo rettangolare, ciò significa assegnare ShapeType::Rectangle; ripristinare solo il riempimento e la linea potrebbe non ripristinare il rettangolo visibile. I modelli con effetti aggiuntivi o formattazioni più complesse richiedono la gestione di tali impostazioni.

Modificare il Testo in un Segnaposto

I segnaposti per titolo, titolo centrato, sottotitolo, corpo e testo normalmente supportano il testo. Controlla la presenza di un AutoShape prima di usare il suo metodo getTextFrame.

Questo esempio aggiorna il primo segnaposto titolo sulla prima diapositiva e salva il risultato:

use aspose\slides\PlaceholderType;
use aspose\slides\Presentation;
use aspose\slides\SaveFormat;

$presentation = new Presentation("template.pptx");
try {
    $slide = $presentation->getSlides()->get_Item(0);
    $shapes = $slide->getShapes();
    $shapeCountValue = $shapes->size();
    $shapeCount = java_values($shapeCountValue);
    $autoShapeClass = new JavaClass("com.aspose.slides.AutoShape");
    $titleShape = null;

    for ($shapeIndex = 0; $shapeIndex < $shapeCount; $shapeIndex++) {
        $shape = $shapes->get_Item($shapeIndex);
        if (!java_instanceof($shape, $autoShapeClass)) {
            continue;
        }

        $placeholder = $shape->getPlaceholder();
        if (java_is_null($placeholder)) {
            continue;
        }

        $placeholderTypeValue = $placeholder->getType();
        $placeholderType = java_values($placeholderTypeValue);
        if ($placeholderType === PlaceholderType::Title || $placeholderType === PlaceholderType::CenteredTitle) {
            $titleShape = $shape;
            break;
        }
    }

    if ($titleShape === null) {
        throw new RuntimeException("The first slide does not contain a title placeholder.");
    }

    $titleShape->getTextFrame()->setText("Quarterly Business Review");
    $presentation->save("title-placeholder-updated.pptx", SaveFormat::Pptx);
} finally {
    $presentation->dispose();
}

Questo modello evita di trattare segnaposti immagine, grafico, tabella o media come oggetti AutoShape. Identifica inoltre il segnaposto per scopo invece di fare affidamento su un indice di forma fragile.

Impostare il Testo di Prompt su un Layout

Il testo di prompt è l’istruzione di progettazione visualizzata in un segnaposto vuoto, ad esempio Fare clic per aggiungere il titolo. Imposta un testo di prompt personalizzato sul segnaposto layout anziché cercarlo nella collezione di forme di una diapositiva normale. Accedi al layout tramite Slide::getLayoutSlide e itera sulla collezione restituita da BaseSlide::getShapes.

Il seguente esempio modifica i prompt di titolo e sottotitolo sul layout usato dalla prima diapositiva:

use aspose\slides\PlaceholderType;
use aspose\slides\Presentation;
use aspose\slides\SaveFormat;

$presentation = new Presentation("template.pptx");
try {
    $slide = $presentation->getSlides()->get_Item(0);
    $layoutSlide = $slide->getLayoutSlide();
    $shapes = $layoutSlide->getShapes();
    $shapeCountValue = $shapes->size();
    $shapeCount = java_values($shapeCountValue);
    $autoShapeClass = new JavaClass("com.aspose.slides.AutoShape");

    for ($shapeIndex = 0; $shapeIndex < $shapeCount; $shapeIndex++) {
        $shape = $shapes->get_Item($shapeIndex);
        if (!java_instanceof($shape, $autoShapeClass)) {
            continue;
        }

        $placeholder = $shape->getPlaceholder();
        if (java_is_null($placeholder)) {
            continue;
        }

        $placeholderTypeValue = $placeholder->getType();
        $placeholderType = java_values($placeholderTypeValue);
        if ($placeholderType === PlaceholderType::Title || $placeholderType === PlaceholderType::CenteredTitle) {
            $shape->getTextFrame()->setText("Enter a concise slide title");
        } elseif ($placeholderType === PlaceholderType::Subtitle) {
            $shape->getTextFrame()->setText("Enter a subtitle or reporting period");
        }
    }

    $presentation->save("custom-placeholder-prompts.pptx", SaveFormat::Pptx);
} finally {
    $presentation->dispose();
}

Il testo di prompt non è contenuto normale della diapositiva. È destinato a segnaposti vuoti nelle applicazioni di modifica come PowerPoint. Una volta che un utente o un programma fornisce contenuto reale, il prompt non viene più visualizzato. Modificare un prompt non sostituisce nemmeno il testo esistente sulle diapositive che usano il layout.

Aggiornare un Segnaposto Immagine

Ci sono due casi da gestire:

Il prossimo esempio supporta entrambi i casi e salva la presentazione:

use aspose\slides\PlaceholderType;
use aspose\slides\Presentation;
use aspose\slides\SaveFormat;
use aspose\slides\ShapeType;

$presentation = new Presentation("picture-template.pptx");
try {
    $slide = $presentation->getSlides()->get_Item(0);
    $shapes = $slide->getShapes();
    $shapeCountValue = $shapes->size();
    $shapeCount = java_values($shapeCountValue);
    $pictureFrameClass = new JavaClass("com.aspose.slides.PictureFrame");
    $picturePlaceholder = null;

    for ($shapeIndex = 0; $shapeIndex < $shapeCount; $shapeIndex++) {
        $shape = $shapes->get_Item($shapeIndex);
        $placeholder = $shape->getPlaceholder();
        if (java_is_null($placeholder)) {
            continue;
        }

        $placeholderTypeValue = $placeholder->getType();
        $placeholderType = java_values($placeholderTypeValue);
        if ($placeholderType === PlaceholderType::Picture) {
            $picturePlaceholder = $shape;
            break;
        }
    }

    if ($picturePlaceholder === null) {
        throw new RuntimeException("The first slide does not contain a picture placeholder.");
    }

    $imageData = file_get_contents("replacement.png");
    $image = $presentation->getImages()->addImage($imageData);

    if (java_instanceof($picturePlaceholder, $pictureFrameClass)) {
        $picture = $picturePlaceholder->getPictureFormat()->getPicture();
        $picture->setImage($image);
    } else {
        $x = $picturePlaceholder->getX();
        $y = $picturePlaceholder->getY();
        $width = $picturePlaceholder->getWidth();
        $height = $picturePlaceholder->getHeight();
        $shapes->addPictureFrame(ShapeType::Rectangle, $x, $y, $width, $height, $image);
        $shapes->remove($picturePlaceholder);
    }

    $presentation->save("picture-placeholder-updated.pptx", SaveFormat::Pptx);
} finally {
    $presentation->dispose();
}

La sostituzione creata per un segnaposto vuoto è un picture frame locale, non un nuovo segnaposto, perché Shape::getPlaceholder non fornisce un setter. Mantiene la posizione riservata ma non eredita più il comportamento specifico del segnaposto. Se mantenere la relazione del segnaposto è essenziale, prepara e popola il segnaposto in PowerPoint prima, poi aggiorna il PictureFrame risultante con Aspose.Slides.

Per la trasparenza dell’immagine, il ritaglio e altri effetti specifici dell’immagine, vedi Manage Picture Frames. tali operazioni appartengono al picture frame o al picture fill, non ai metadati del segnaposto.

Lavorare con Segnaposti Grafico e Contenuto

Un segnaposto grafico popolato può essere rappresentato da un Chart. Questo esempio trova tale grafico sia per tipo di segnaposto sia per classe al runtime, modifica il titolo e salva il file:

use aspose\slides\PlaceholderType;
use aspose\slides\Presentation;
use aspose\slides\SaveFormat;

$presentation = new Presentation("chart-template.pptx");
try {
    $slide = $presentation->getSlides()->get_Item(0);
    $shapes = $slide->getShapes();
    $shapeCountValue = $shapes->size();
    $shapeCount = java_values($shapeCountValue);
    $chartClass = new JavaClass("com.aspose.slides.Chart");
    $placeholderChart = null;

    for ($shapeIndex = 0; $shapeIndex < $shapeCount; $shapeIndex++) {
        $shape = $shapes->get_Item($shapeIndex);
        if (!java_instanceof($shape, $chartClass)) {
            continue;
        }

        $placeholder = $shape->getPlaceholder();
        if (java_is_null($placeholder)) {
            continue;
        }

        $placeholderTypeValue = $placeholder->getType();
        $placeholderType = java_values($placeholderTypeValue);
        if ($placeholderType === PlaceholderType::Chart) {
            $placeholderChart = $shape;
            break;
        }
    }

    if ($placeholderChart === null) {
        throw new RuntimeException("The first slide does not contain a populated chart placeholder.");
    }

    $placeholderChart->setTitle(true);
    $placeholderChart->getChartTitle()->addTextFrameForOverriding("Quarterly Revenue");
    $presentation->save("chart-placeholder-updated.pptx", SaveFormat::Pptx);
} finally {
    $presentation->dispose();
}

Un segnaposto di contenuto generico di solito ha PlaceholderType::Object. In PowerPoint funge da avviatore per diversi tipi di contenuto, inclusi grafici, tabelle, diagrammi, immagini e media. Dopo che è stato popolato, ispeziona la classe effettiva della forma per capire cosa contiene. I layout specializzati possono anche esporre PlaceholderType::Chart, PlaceholderType::Table, PlaceholderType::Picture, PlaceholderType::Media, o PlaceholderType::Diagram.

Aspose.Slides non converte un segnaposto AutoShape vuoto in un Chart semplicemente cambiando Placeholder::getType; il tipo non può essere modificato tramite la classe. Per riempire programmaticamente un’area grafico o contenuto vuota, aggiungi l’oggetto necessario alle coordinate del segnaposto e poi rimuovi il segnaposto vuoto. Il seguente esempio lo fa per un grafico:

use aspose\slides\ChartType;
use aspose\slides\PlaceholderType;
use aspose\slides\Presentation;
use aspose\slides\SaveFormat;

$presentation = new Presentation("content-template.pptx");
try {
    $slide = $presentation->getSlides()->get_Item(0);
    $shapes = $slide->getShapes();
    $shapeCountValue = $shapes->size();
    $shapeCount = java_values($shapeCountValue);
    $targetPlaceholder = null;

    for ($shapeIndex = 0; $shapeIndex < $shapeCount; $shapeIndex++) {
        $shape = $shapes->get_Item($shapeIndex);
        $placeholder = $shape->getPlaceholder();
        if (java_is_null($placeholder)) {
            continue;
        }

        $placeholderTypeValue = $placeholder->getType();
        $placeholderType = java_values($placeholderTypeValue);
        if ($placeholderType === PlaceholderType::Chart || $placeholderType === PlaceholderType::Object) {
            $targetPlaceholder = $shape;
            break;
        }
    }

    if ($targetPlaceholder === null) {
        throw new RuntimeException("The first slide does not contain a chart or content placeholder.");
    }

    $x = $targetPlaceholder->getX();
    $y = $targetPlaceholder->getY();
    $width = $targetPlaceholder->getWidth();
    $height = $targetPlaceholder->getHeight();
    $chart = $shapes->addChart(ChartType::ClusteredColumn, $x, $y, $width, $height);
    $chart->setTitle(true);
    $chart->getChartTitle()->addTextFrameForOverriding("Quarterly Revenue");
    $shapes->remove($targetPlaceholder);
    $presentation->save("content-placeholder-replaced-with-chart.pptx", SaveFormat::Pptx);
} finally {
    $presentation->dispose();
}

Il grafico aggiunto è un grafico locale ordinario. Occupia l’area del segnaposto ma non eredita dal segnaposto layout. Usa gli articoli dedicati alla gestione dei grafici chart management articles quando devi sostituire categorie, serie o dati della cartella di lavoro.

Esempio Completo: Aggiornare Testo o Contenuto Immagine

Il seguente esempio end‑to‑end apre un modello, ricerca nella prima diapositiva un segnaposto titolo o immagine, controlla i tipi di segnaposto e di forma, aggiorna il contenuto appropriato e salva il risultato. L’esempio evita deliberatamente di presumere un indice di forma o di trattare ogni segnaposto come la stessa classe.

use aspose\slides\PlaceholderType;
use aspose\slides\Presentation;
use aspose\slides\SaveFormat;
use aspose\slides\ShapeType;

$presentation = new Presentation("template.pptx");
try {
    $slide = $presentation->getSlides()->get_Item(0);
    $shapes = $slide->getShapes();
    $shapeCountValue = $shapes->size();
    $shapeCount = java_values($shapeCountValue);
    $autoShapeClass = new JavaClass("com.aspose.slides.AutoShape");
    $pictureFrameClass = new JavaClass("com.aspose.slides.PictureFrame");
    $updated = false;

    for ($shapeIndex = 0; $shapeIndex < $shapeCount; $shapeIndex++) {
        $shape = $shapes->get_Item($shapeIndex);
        $placeholder = $shape->getPlaceholder();
        if (java_is_null($placeholder)) {
            continue;
        }

        $placeholderTypeValue = $placeholder->getType();
        $placeholderType = java_values($placeholderTypeValue);

        if (($placeholderType === PlaceholderType::Title || $placeholderType === PlaceholderType::CenteredTitle) && java_instanceof($shape, $autoShapeClass)) {
            $shape->getTextFrame()->setText("Quarterly Business Review");
            $updated = true;
            break;
        }

        if ($placeholderType === PlaceholderType::Picture) {
            $imageData = file_get_contents("replacement.png");
            $image = $presentation->getImages()->addImage($imageData);

            if (java_instanceof($shape, $pictureFrameClass)) {
                $picture = $shape->getPictureFormat()->getPicture();
                $picture->setImage($image);
            } else {
                $x = $shape->getX();
                $y = $shape->getY();
                $width = $shape->getWidth();
                $height = $shape->getHeight();
                $shapes->addPictureFrame(ShapeType::Rectangle, $x, $y, $width, $height, $image);
                $shapes->remove($shape);
            }

            $updated = true;
            break;
        }
    }

    if (!$updated) {
        throw new RuntimeException("No supported title or picture placeholder was found on the first slide.");
    }

    $presentation->save("placeholder-content-updated.pptx", SaveFormat::Pptx);
} finally {
    $presentation->dispose();
}

FAQ

Che cos’è un segnaposto base?

Un segnaposto base è la forma corrispondente sul layout o sul master da cui un altro segnaposto eredita. Usa Shape::getBasePlaceholder per recuperarlo. Una forma locale ordinaria restituisce null perché non fa parte della gerarchia dei segnaposti.

Posso modificare tutti i titoli delle diapositive modificando un segnaposto layout?

Puoi modificare la formattazione o il testo di prompt ereditati tramite un layout, ma il contenuto reale del titolo è memorizzato sulle diapositive normali. Per sostituire effettivamente il testo del titolo in tutta la presentazione, itera sulle diapositive e aggiorna ogni segnaposto titolo.

Come gestisco i segnaposti data, numero diapositiva, intestazione e piè di pagina?

Utilizza i gestori di intestazione e piè di pagina nella diapositiva, nel layout, nel master, nelle note o nel handout appropriati. Vedi Manage Presentation Header and Footer per esempi completi.