Compartilhar via

Obter todos os hiperlinks externos de uma apresentação

  • Artigo

Este tópico mostra como utilizar as classes no SDK Open XML para o Office para obter todas as hiperligações externas numa apresentação através de programação.

Obter um Objeto PresentationDocument

No SDK Open XML, a PresentationDocument classe representa um pacote de documento de apresentação. Para trabalhar com um documento de apresentação, crie primeiro uma instância da PresentationDocument classe e, em seguida, trabalhe com essa instância. Para criar a instância de classe a partir do documento, chame o Open método que utiliza um caminho de ficheiro e um valor Booleano como segundo parâmetro para especificar se um documento é editável. Defina este segundo parâmetro para false abrir o ficheiro para acesso só de leitura ou true se quiser abrir o ficheiro para acesso de leitura/escrita. Neste tópico, é melhor abrir o ficheiro para acesso só de leitura para proteger o ficheiro contra escrita acidental. A seguinte using instrução abre o ficheiro para acesso só de leitura. Neste segmento de código, o fileName parâmetro é uma cadeia que representa o caminho para o ficheiro a partir do qual pretende abrir o documento.

// Open the presentation file as read-only.
using (PresentationDocument document = PresentationDocument.Open(fileName, false))

Com a v3.0.0+ o Close() método foi removido a favor de depender da instrução using. Isto garante que o Dispose() método é chamado automaticamente quando a chaveta de fecho é atingida. O bloco que segue a using instrução estabelece um âmbito para o objeto que é criado ou nomeado na using instrução , neste caso document.

Estrutura básica do documento de apresentação

A estrutura de documentos básica de um PresentationML documento consiste em várias partes, entre as quais a main parte que contém a definição da apresentação. O texto seguinte da especificação ISO/IEC 29500 apresenta a forma geral de um PresentationML pacote.

O main parte de um PresentationML pacote começa com um elemento raiz de apresentação. Esse elemento contém uma apresentação que, por sua vez, se refere a uma lista de diapositivos, a uma lista de master de diapositivos, a uma lista de notas master e a um folheto master lista. A lista de diapositivos refere-se a todos os diapositivos na apresentação; A lista de master de diapositivos refere-se a todos os modelos globais de diapositivos utilizados na apresentação; as notas master contêm informações sobre a formatação das páginas de notas; e o master de folheto descreve o aspeto de um folheto.

Um folheto é um conjunto impresso de diapositivos que podem ser fornecidos a uma audiência.

Além de texto e gráficos, cada diapositivo pode conter comentários e notas, pode ter um esquema e pode fazer parte de uma ou mais apresentações personalizadas. Um comentário é uma anotação destinada à pessoa que mantém o conjunto de diapositivos da apresentação. Uma nota é um lembrete ou texto destinado ao apresentador ou à audiência.

Outras funcionalidades que um PresentationML documento pode incluir: animação, áudio, vídeo e transições entre diapositivos.

Um PresentationML documento não é armazenado como um corpo grande numa única parte. Em vez disso, os elementos que implementam determinados agrupamentos de funcionalidades são armazenados em partes separadas. Por exemplo, todos os autores num documento são armazenados numa parte dos autores, enquanto cada diapositivo tem a sua própria parte.

ISO/IEC 29500: 2016

O seguinte exemplo de código XML representa uma apresentação que contém dois diapositivos indicados pelos IDs 267 e 256.

    <p:presentation xmlns:p="…" … > 
       <p:sldMasterIdLst>
          <p:sldMasterId
             xmlns:rel="https://…/relationships" rel:id="rId1"/>
       </p:sldMasterIdLst>
       <p:notesMasterIdLst>
          <p:notesMasterId
             xmlns:rel="https://…/relationships" rel:id="rId4"/>
       </p:notesMasterIdLst>
       <p:handoutMasterIdLst>
          <p:handoutMasterId
             xmlns:rel="https://…/relationships" rel:id="rId5"/>
       </p:handoutMasterIdLst>
       <p:sldIdLst>
          <p:sldId id="267"
             xmlns:rel="https://…/relationships" rel:id="rId2"/>
          <p:sldId id="256"
             xmlns:rel="https://…/relationships" rel:id="rId3"/>
       </p:sldIdLst>
           <p:sldSz cx="9144000" cy="6858000"/>
       <p:notesSz cx="6858000" cy="9144000"/>
    </p:presentation>

Com o SDK Open XML, pode criar a estrutura e o conteúdo do documento com classes com tipos fortes que correspondem a elementos PresentationML. Pode encontrar estas classes no espaço de nomes. A tabela seguinte lista os nomes das classes que correspondem aos sldelementos , sldLayout, sldMastere notesMaster .

Elemento PresentationML Abrir Classe SDK XML Descrição
<sld/> Slide Diapositivo de Apresentação. É o elemento raiz de SlidePart.
<sldLayout/> SlideLayout Esquema de Diapositivo. É o elemento raiz de SlideLayoutPart.
<sldMaster/> SlideMaster Modelo Global de Diapositivos. É o elemento raiz de SlideMasterPart.
<notesMaster/> NotesMaster Modelo Global de Notas (ou handoutMaster). É o elemento raiz de NotesMasterPart.

Neste exemplo de código de procedimentos, vai trabalhar com hiperligações externas. Portanto, é melhor familiarizar-se com o elemento de hiperligação. O texto seguinte da especificação ISO/IEC 29500 introduz o id (Destino de Hiperligação).

Especifica o ID da relação cujo destino deve ser utilizado como destino para estahyperlink.

Se este atributo for omitido, não haverá nenhum destino de hiperligação externo para a hiperligação atual - uma localização no documento atual ainda pode ser alvo através do atributo de âncora. Se este atributo existir, substituirá o valor no atributo de âncora.

[Exemplo: considere o seguinte PresentationML fragmento para uma hiperligação:

    <w:hyperlink r:id="rId9">
      <w:r>
        <w:t>https://www.example.com</w:t>
      </w:r>
    </w:hyperlink>

O id valor de atributo de especifica que a relação no item de rId9 parte da relação associada com um valor de atributo de ID correspondente tem de ser navegado para quando esta hiperligação é invocada. Por exemplo, se o seguinte XML estiver presente no item de parte da relação associada:

    <Relationships xmlns="…">
      <Relationship Id="rId9" Mode="External" Target="https://www.example.com" />
    </Relationships>

Por conseguinte, o destino desta hiperligação seria o destino da relação rId9 – neste caso, https://www.example.com. exemplo final]

Os valores possíveis para este atributo são definidos pelo ST_RelationshipId tipo simples(}22.8.2.1).

© ISO/IEC 29500: 2016

Como funciona o código de exemplo

O código de exemplo neste tópico consiste num método que utiliza como parâmetro o caminho completo do ficheiro de apresentação. Itera todos os diapositivos na apresentação e devolve uma lista de cadeias que representam os Identificadores de Recursos Universais (URIs) de todas as hiperligações externas na apresentação.

// Iterate through all the slide parts in the presentation part.
foreach (SlidePart slidePart in document.PresentationPart.SlideParts)
{
    IEnumerable<Drawing.HyperlinkType> links = slidePart.Slide.Descendants<Drawing.HyperlinkType>();

    // Iterate through all the links in the slide part.
    foreach (Drawing.HyperlinkType link in links)
    {
        // Iterate through all the external relationships in the slide part. 
        foreach (HyperlinkRelationship relation in slidePart.HyperlinkRelationships)
        {
            // If the relationship ID matches the link ID…
            if (relation.Id.Equals(link.Id))
            {
                // Add the URI of the external relationship to the list of strings.
                ret.Add(relation.Uri.AbsoluteUri);
            }
        }
    }
}

Código de exemplo

Segue-se o exemplo de código completo que pode utilizar para devolver a lista de todas as ligações externas numa apresentação. Pode utilizar o seguinte ciclo no programa para chamar o GetAllExternalHyperlinksInPresentation método para obter a lista de URIs na sua apresentação.

if (args is [{ } fileName])
{
    foreach (string link in GetAllExternalHyperlinksInPresentation(fileName))
    {
        Console.WriteLine(link);
    }
}

A seguir está o código de exemplo completo em C# e em Visual Basic.

// Returns all the external hyperlinks in the slides of a presentation.
static IEnumerable<String> GetAllExternalHyperlinksInPresentation(string fileName)
{
    // Declare a list of strings.
    List<string> ret = new List<string>();

    // Open the presentation file as read-only.
    using (PresentationDocument document = PresentationDocument.Open(fileName, false))
    {
        // If there is no PresentationPart then there are no hyperlinks
        if (document.PresentationPart is null)
        {
            return ret;
        }

        // Iterate through all the slide parts in the presentation part.
        foreach (SlidePart slidePart in document.PresentationPart.SlideParts)
        {
            IEnumerable<Drawing.HyperlinkType> links = slidePart.Slide.Descendants<Drawing.HyperlinkType>();

            // Iterate through all the links in the slide part.
            foreach (Drawing.HyperlinkType link in links)
            {
                // Iterate through all the external relationships in the slide part. 
                foreach (HyperlinkRelationship relation in slidePart.HyperlinkRelationships)
                {
                    // If the relationship ID matches the link ID…
                    if (relation.Id.Equals(link.Id))
                    {
                        // Add the URI of the external relationship to the list of strings.
                        ret.Add(relation.Uri.AbsoluteUri);
                    }
                }
            }
        }
    }

    // Return the list of strings.
    return ret;
}

Confira também