Gerenciar Formas de Apresentação em PHP

Visão geral

Este artigo explica como trabalhar com formas em apresentações usando Aspose.Slides. Ele mostra como encontrar uma forma em um slide, cloná‑la, removê‑la, ocultá‑la, alterar sua ordem, obter seu ID de forma Interop e definir texto alternativo para identificação e processamento posterior.

Também aborda como acessar formatos de layout para formas, renderizar uma forma como SVG, alinhar formas em um slide e usar propriedades de espelhamento horizontal e vertical. Além disso, o artigo inclui um FAQ curto sobre combinação de formas, ordem de empilhamento e bloqueio de forma.

Encontrar uma forma em um slide

Este tópico descreve uma técnica simples para facilitar a localização de uma forma específica em um slide sem usar seu Id interno. É importante saber que arquivos de apresentação do PowerPoint não possuem nenhum modo de identificar formas em um slide, exceto por um Id interno exclusivo. Parece ser difícil para os desenvolvedores encontrar uma forma usando esse Id interno exclusivo. Todas as formas adicionadas aos slides têm algum Texto Alternativo. Sugerimos que os desenvolvedores usem texto alternativo para encontrar uma forma específica. Você pode usar o MS PowerPoint para definir o texto alternativo para objetos que pretende alterar no futuro.

Depois de definir o texto alternativo de qualquer forma desejada, você pode abrir a apresentação usando Aspose.Slides for PHP via Java e iterar por todas as formas adicionadas a um slide. Em cada iteração, você pode verificar o texto alternativo da forma e a forma com o texto correspondente será a forma requerida por você. Para demonstrar essa técnica de forma mais clara, criamos o método findShape que faz a busca de uma forma específica em um slide e devolve simplesmente essa forma.

  # Instanciar a classe Presentation que representa o arquivo da apresentação
  $pres = new Presentation("FindingShapeInSlide.pptx");
  try {
    $slide = $pres->getSlides()->get_Item(0);
    # Texto alternativo da forma a ser encontrada
    $shape = findShape($slide, "Shape1");
    if (!java_is_null($shape)) {
      echo("Shape Name: " . $shape->getName());
    }
  } finally {
    if (!java_is_null($pres)) {
      $pres->dispose();
    }
  }

Clonar uma forma

Para clonar uma forma para um slide usando Aspose.Slides for PHP via Java:

  1. Crie uma instância da classe Presentation.
  2. Obtenha a referência de um slide usando seu índice.
  3. Acesse a coleção de formas do slide de origem.
  4. Adicione um novo slide à apresentação.
  5. Clone as formas da coleção de formas do slide de origem para o novo slide.
  6. Salve a apresentação modificada como um arquivo PPTX.

O exemplo abaixo adiciona uma forma de grupo a um slide.

  # Instanciar a classe Presentation
  $pres = new Presentation("Source Frame.pptx");
  try {
    $sourceShapes = $pres->getSlides()->get_Item(0)->getShapes();
    $blankLayout = $pres->getMasters()->get_Item(0)->getLayoutSlides()->getByType(SlideLayoutType::Blank);
    $destSlide = $pres->getSlides()->addEmptySlide($blankLayout);
    $destShapes = $destSlide->getShapes();
    $destShapes->addClone($sourceShapes->get_Item(1), 50, 150 + $sourceShapes->get_Item(0)->getHeight());
    $destShapes->addClone($sourceShapes->get_Item(2));
    $destShapes->insertClone(0, $sourceShapes->get_Item(0), 50, 150);
    # Gravar o arquivo PPTX no disco
    $pres->save("CloneShape_out.pptx", SaveFormat::Pptx);
  } finally {
    if (!java_is_null($pres)) {
      $pres->dispose();
    }
  }

Remover uma forma

Aspose.Slides for PHP via Java permite que os desenvolvedores removam qualquer forma. Para remover a forma de um slide, siga as etapas abaixo:

  1. Crie uma instância da classe Presentation.
  2. Acesse o primeiro slide.
  3. Encontre a forma com o TextoAlternativo específico.
  4. Remova a forma.
  5. Salve o arquivo no disco.
  # Criar objeto Presentation
  $pres = new Presentation();
  try {
    # Obter o primeiro slide
    $sld = $pres->getSlides()->get_Item(0);
    # Adicionar autoshape do tipo retângulo
    $sld->getShapes()->addAutoShape(ShapeType::Rectangle, 50, 40, 150, 50);
    $sld->getShapes()->addAutoShape(ShapeType::Moon, 160, 40, 150, 50);
    $altText = "User Defined";
    $iCount = $sld->getShapes()->size();
    for($i = 0; $i < java_values($iCount) ; $i++) {
      $ashp = $sld->getShapes()->get_Item(0);
      if ($alttext->equals($ashp->getAlternativeText())) {
        $sld->getShapes()->remove($ashp);
      }
    }
    # Salvar a apresentação no disco
    $pres->save("RemoveShape_out.pptx", SaveFormat::Pptx);
  } finally {
    if (!java_is_null($pres)) {
      $pres->dispose();
    }
  }

Ocultar uma forma

Aspose.Slides for PHP via Java permite que os desenvolvedores ocultem qualquer forma. Para ocultar a forma de um slide, siga as etapas abaixo:

  1. Crie uma instância da classe Presentation.
  2. Acesse o primeiro slide.
  3. Encontre a forma com o TextoAlternativo específico.
  4. Oculte a forma.
  5. Salve o arquivo no disco.
  # Instanciar a classe Presentation que representa o PPTX
  $pres = new Presentation();
  try {
    # Obter o primeiro slide
    $sld = $pres->getSlides()->get_Item(0);
    # Adicionar autoshape do tipo retângulo
    $sld->getShapes()->addAutoShape(ShapeType::Rectangle, 50, 40, 150, 50);
    $sld->getShapes()->addAutoShape(ShapeType::Moon, 160, 40, 150, 50);
    $alttext = "User Defined";
    $iCount = $sld->getShapes()->size();
    for($i = 0; $i < java_values($iCount) ; $i++) {
      $ashp = $sld->getShapes()->get_Item($i);
      if ($alttext->equals($ashp->getAlternativeText())) {
        $ashp->setHidden(true);
      }
    }
    # Salvar a apresentação no disco
    $pres->save("Hiding_Shapes_out.pptx", SaveFormat::Pptx);
  } finally {
    if (!java_is_null($pres)) {
      $pres->dispose();
    }
  }

Alterar a ordem da forma

Aspose.Slides for PHP via Java permite que os desenvolvedores reordenem as formas. Reordenar a forma especifica qual forma fica na frente ou qual forma fica atrás. Para reordenar a forma de um slide, siga as etapas abaixo:

  1. Crie uma instância da classe Presentation.
  2. Acesse o primeiro slide.
  3. Adicione uma forma.
  4. Adicione algum texto na caixa de texto da forma.
  5. Adicione outra forma com as mesmas coordenadas.
  6. Reordene as formas.
  7. Salve o arquivo no disco.
  $pres = new Presentation("ChangeShapeOrder.pptx");
  try {
    $slide = $pres->getSlides()->get_Item(0);
    $shp3 = $slide->getShapes()->addAutoShape(ShapeType::Rectangle, 200, 365, 400, 150);
    $shp3->getFillFormat()->setFillType(FillType::NoFill);
    $shp3->addTextFrame(" ");
    $para = $shp3->getTextFrame()->getParagraphs()->get_Item(0);
    $portion = $para->getPortions()->get_Item(0);
    $portion->setText("Watermark Text Watermark Text Watermark Text");
    $shp3 = $slide->getShapes()->addAutoShape(ShapeType::Triangle, 200, 365, 400, 150);
    $slide->getShapes()->reorder(2, $shp3);
    $pres->save("Reshape_out.pptx", SaveFormat::Pptx);
  } finally {
    if (!java_is_null($pres)) {
      $pres->dispose();
    }
  }

Obter o ID da forma Interop

Aspose.Slides for PHP via Java permite que os desenvolvedores obtenham um identificador único de forma no escopo do slide, em contraste com o método getUniqueId, que permite obter um identificador único no escopo da apresentação. O método getOfficeInteropShapeId foi adicionado à classe Shape respectivamente. O valor retornado por getOfficeInteropShapeId corresponde ao valor do Id do objeto Microsoft.Office.Interop.PowerPoint.Shape. Abaixo é apresentado um exemplo de código.

  $pres = new Presentation("Presentation.pptx");
  try {
    # Obtendo identificador de forma exclusivo no escopo do slide
    $officeInteropShapeId = $pres->getSlides()->get_Item(0)->getShapes()->get_Item(0)->getOfficeInteropShapeId();
  } finally {
    if (!java_is_null($pres)) {
      $pres->dispose();
    }
  }

Definir Texto Alternativo para uma Forma

Aspose.Slides for PHP via Java permite que os desenvolvedores definam AlternativeText de qualquer forma. As formas em uma apresentação podem ser distinguidas pelo Texto Alternativo ou pelo método Shape Name. Os métodos setAlternativeText e getAlternativeText podem ser lidos ou definidos usando Aspose.Slides assim como o Microsoft PowerPoint. Usando este método, você pode marcar uma forma e executar diferentes operações, como remover, ocultar ou reordenar formas em um slide. Para definir o AlternativeText de uma forma, siga as etapas abaixo:

  1. Crie uma instância da classe Presentation.
  2. Acesse o primeiro slide.
  3. Adicione qualquer forma ao slide.
  4. Realize algum trabalho com a forma recém‑adicionada.
  5. Percorra as formas para encontrar uma forma.
  6. Defina o AlternativeText.
  7. Salve o arquivo no disco.
  # Instanciar a classe Presentation que representa o PPTX
  $pres = new Presentation();
  try {
    # Obter o primeiro slide
    $sld = $pres->getSlides()->get_Item(0);
    # Adicionar autoshape do tipo retângulo
    $shp1 = $sld->getShapes()->addAutoShape(ShapeType::Rectangle, 50, 40, 150, 50);
    $shp2 = $sld->getShapes()->addAutoShape(ShapeType::Moon, 160, 40, 150, 50);
    $shp2->getFillFormat()->setFillType(FillType::Solid);
    $shp2->getFillFormat()->getSolidFillColor()->setColor(java("java.awt.Color")->GRAY);
    for($i = 0; $i < java_values($sld->getShapes()->size()) ; $i++) {
      $shape = $sld->getShapes()->get_Item($i);
      if (!java_is_null($shape)) {
        $shape->setAlternativeText("User Defined");
      }
    }
    # Salvar a apresentação no disco
    $pres->save("Set_AlternativeText_out.pptx", SaveFormat::Pptx);
  } finally {
    if (!java_is_null($pres)) {
      $pres->dispose();
    }
  }

Acessar Formatos de Layout para uma Forma

Aspose.Slides for PHP via Java fornece uma API simples para acessar formatos de layout para uma forma. Este artigo demonstra como você pode acessar esses formatos.

Abaixo é apresentado um exemplo de código.

  $pres = new Presentation("pres.pptx");
  try {
    foreach($pres->getLayoutSlides() as $layoutSlide) {
      foreach($layoutSlide->getShapes() as $shape) {
        $fillFormats = $shape->getFillFormat();
        $lineFormats = $shape->getLineFormat();
      }
    }
  } finally {
    if (!java_is_null($pres)) {
      $pres->dispose();
    }
  }

Renderizar uma Forma como SVG

Agora o Aspose.Slides for PHP via Java oferece suporte à renderização de uma forma como SVG. O método writeAsSvg (e sua sobrecarga) foi adicionado à classe Shape. Esse método permite salvar o conteúdo da forma como um arquivo SVG. O trecho de código abaixo mostra como exportar a forma de um slide para um arquivo SVG.

  $pres = new Presentation("TestExportShapeToSvg.pptx");
  try {
    $stream = new Java("java.io.FileOutputStream", "SingleShape.svg");
    try {
      $pres->getSlides()->get_Item(0)->getShapes()->get_Item(0)->writeAsSvg($stream);
    } finally {
      if (!java_is_null($stream)) {
        $stream->close();
      }
    }
  } catch (JavaException $e) {
  } finally {
    if (!java_is_null($pres)) {
      $pres->dispose();
    }
  }

Alinhar uma Forma

Aspose.Slides permite alinhar formas tanto em relação às margens do slide quanto em relação umas às outras. Para isso, foi adicionada a sobrecarga do método SlidesUtil::alignShapes. A enumeração ShapesAlignmentType define as opções de alinhamento possíveis.

Exemplo 1

O código fonte abaixo alinha as formas com índices 1, 2 e 4 ao longo da borda superior do slide.

  $pres = new Presentation("example.pptx");
  try {
    $slide = $pres->getSlides()->get_Item(0);
    $shape1 = $slide->getShapes()->get_Item(1);
    $shape2 = $slide->getShapes()->get_Item(2);
    $shape3 = $slide->getShapes()->get_Item(4);
    SlideUtil->alignShapes(ShapesAlignmentType::AlignTop, true, $pres->getSlides()->get_Item(0), array($slide->getShapes()->indexOf($shape1), $slide->getShapes()->indexOf($shape2), $slide->getShapes()->indexOf($shape3) ));
  } finally {
    if (!java_is_null($pres)) {
      $pres->dispose();
    }
  }

Exemplo 2

O exemplo abaixo mostra como alinhar toda a coleção de formas em relação à forma mais inferior da coleção.

  $pres = new Presentation("example.pptx");
  try {
    SlideUtil->alignShapes(ShapesAlignmentType::AlignBottom, false, $pres->getSlides()->get_Item(0));
  } finally {
    if (!java_is_null($pres)) {
      $pres->dispose();
    }
  }

Propriedades de espelhamento

No Aspose.Slides, a classe ShapeFrame fornece controle sobre o espelhamento horizontal e vertical das formas via suas propriedades flipH e flipV. Ambas as propriedades são do tipo NullableBool, permitindo valores True para indicar um espelhamento, False para nenhum espelhamento ou NotDefined para usar o comportamento padrão. Esses valores são acessíveis a partir do Frame de uma forma.

Para modificar as configurações de espelhamento, cria‑se uma nova instância de ShapeFrame com a posição e tamanho atuais da forma, os valores desejados para flipH e flipV, e o ângulo de rotação. Atribuir essa instância ao Frame da forma e salvar a apresentação aplica as transformações de espelhamento e as grava no arquivo de saída.

Suponha que tenhamos um arquivo sample.pptx no qual o primeiro slide contém uma única forma com configurações padrão de espelhamento, como mostrado abaixo.

A forma a ser invertida

O exemplo de código a seguir recupera as propriedades de espelhamento atuais da forma e a inverte horizontal e verticalmente.

$presentation = new Presentation("sample.pptx");
try {
    $slide = $presentation->getSlides()->get_Item(0);
    $shape = $slide->getShapes()->get_Item(0);

    // Recuperar a propriedade de espelhamento horizontal da forma.
    $horizontalFlip = $shape->getFrame()->getFlipH();
    echo "Horizontal flip: ", $horizontalFlip, "\n";

    // Recuperar a propriedade de espelhamento vertical da forma.
    $verticalFlip = $shape->getFrame()->getFlipV();
    echo "Vertical flip: ", $verticalFlip, "\n";

    $x = $shape->getFrame()->getX();
    $y = $shape->getFrame()->getY();
    $width = $shape->getFrame()->getWidth();
    $height = $shape->getFrame()->getHeight();
    $flipH = NullableBool::True; // Espelhar horizontalmente.
    $flipV = NullableBool::True; // Espelhar horizontalmente.
    $rotation = $shape->getFrame()->getRotation();

    $shape->setFrame(new ShapeFrame($x, $y, $width, $height, $flipH, $flipV, $rotation));

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

O resultado:

A forma invertida

Perguntas Frequentes

Posso combinar formas (união/interseção/subtração) em um slide como em um editor de desktop?

Não existe uma API de operação booleana integrada. Você pode aproximar isso construindo o contorno desejado você mesmo — por exemplo, compute a geometria resultante (via GeometryPath) e crie uma nova forma com esse contorno, removendo opcionalmente as originais.

Como posso controlar a ordem de empilhamento (z‑order) para que uma forma permaneça sempre “no topo”?

Altere a ordem de inserção/movimento dentro da coleção de shapes do slide. Para resultados previsíveis, finalize a ordem z‑order após todas as demais modificações do slide.

Posso “bloquear” uma forma para impedir que usuários a editem no PowerPoint?

Sim. Defina bandeiras de proteção ao nível da forma (por exemplo, bloquear seleção, movimentação, redimensionamento, edição de texto). Se necessário, reflita restrições no mestre ou layout. Observe que isso é proteção ao nível da UI, não um recurso de segurança; para proteção mais forte, combine com restrições ao nível do arquivo, como recomendações de somente‑leitura ou senhas (read‑only recommendations or passwords).

Aplicar efeitos de forma em apresentações usando PHP Obter Propriedades Efetivas de Forma de Apresentações em PHP