Como trabalhar com tags de documento estruturado em .NET

Etapa 1: Instalar o pacote

Aspose.Words FOSS for .NET ainda não publica um pacote NuGet – compile a biblioteca a partir do código-fonte. Clone https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git, então compile Aspose.Words.sln na configuração Release com o SDK .NET e referencie o assembly Aspose.Words resultante do seu projeto. A biblioteca tem como alvo .NET Standard 2.0, portanto funciona em .NET Framework 4.6.2+ e .NET 6/8/10.

Etapa 2: Importar as classes necessárias

Adicione uma diretiva using Aspose.Words; para Document e DocumentBuilder, e uma diretiva using Aspose.Words.Markup; para StructuredDocumentTag, SdtType, SdtListItem, SdtListItemCollection, XmlMapping, e as demais classes de controle de conteúdo que este guia aborda.

Etapa 3: Verifique quais tipos de Controle de Conteúdo você pode inserir

Antes de inserir, verifique se o SdtType de destino é um dos sete tipos aceitos por DocumentBuilder.InsertStructuredDocumentTag(SdtType): PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture e Date. RepeatingSection e RepeatingSectionItem não podem ser inseridos em um cursor de texto com este método — eles envolvem parágrafos inteiros ou linhas de tabela. Os valores restantes de SdtType que podem aparecer em um arquivo Word mas não estão presentes na interface do Word como tipos inseríveis — None, Bibliography, Citation, Equation, BuildingBlockGallery, DocPartObj, Group e EntityPicker — não são aceitos por este método de inserção de forma alguma.

Etapa 4: Inserir um Controle de Conteúdo no Cursor

Chame DocumentBuilder.InsertStructuredDocumentTag(SdtType) com um dos sete tipos suportados para inserir um novo controle na posição atual do cursor do construtor; a chamada retorna o novo StructuredDocumentTag. Defina Tag e Title no controle retornado para fornecer as strings de identificação que os autores veem no Word, e defina PlaceholderName (suportado por um Placeholder BuildingBlock) para o texto de sugestão que o Word exibe enquanto o controle está vazio — IsShowingPlaceholderText indica se essa sugestão está sendo exibida no momento.

Etapa 5: Configurar Conteúdo Específico do Tipo

Para um controle de caixa de seleção, leia ou defina StructuredDocumentTag.Checked, e chame SetCheckedSymbol() / SetUncheckedSymbol() para personalizar os glifos mostrados para cada estado. Para um controle de data, defina FullDate, com DateDisplayFormat e DateDisplayLocale controlando como ele é renderizado, DateStorageFormat (SdtDateStorageFormat) controlando como ele é armazenado quando vinculado a dados XML, e CalendarType (SdtCalendarType) selecionando o sistema de calendário. Para uma lista suspensa ou caixa de combinação, preencha ListItems — um SdtListItemCollection de SdtListItem (DisplayText, Value) — antes de definir SelectedValue para escolher a opção ativa. Para um controle de texto simples, Multiline é uma propriedade bool em StructuredDocumentTag que pode ser definida para configurar o controle.

Etapa 6: Aparência do Controle e Bloqueio

Defina Appearance (SdtAppearance) para controlar como o controle é delimitado visualmente no Word, e Color para definir sua cor de realce. ContentsFont e EndCharacterFont controlam a fonte aplicada ao conteúdo do controle e ao seu caractere final de terminação. LockContentControl e LockContents são interruptores independentes — defina LockContentControl para bloquear a exclusão do próprio controle, e LockContents para bloquear a edição do que está dentro dele, sem afetar o outro.

Etapa 7: Encontrar e Remover Controles de Conteúdo

Leia Range.StructuredDocumentTags – um StructuredDocumentTagCollection com escopo para esse intervalo – e chame GetById(), GetByTag() ou GetByTitle() para localizar um controle específico, ou Remove() / RemoveAt() na coleção para remover um por referência ou índice. Em um controle individual, chame Remove() para excluir o controle junto com seu conteúdo, RemoveSelfOnly() para excluir apenas o invólucro mantendo seu conteúdo no documento, ou Clear() para esvaziar seu conteúdo mantendo o próprio controle no lugar.

Etapa 8: Vincular um Controle a Dados Personalizados XML

Leia StructuredDocumentTag.XmlMapping – uma instância XmlMapping – e chame SetMapping(customXmlPart, xPath, prefixMapping) para vincular o controle a uma parte personalizada XML existente já presente no armazenamento de dados personalizado XML do documento, usando uma expressão XPath para selecionar o elemento vinculado. XmlMapping.IsMapped informa se uma vinculação está atualmente ativa, CustomXmlPart e StoreItemId identificam a parte de dados vinculada, e Delete() remove o mapeamento.

Etapa 9: Manipular Controles de Conteúdo que Abrangem Múltiplas Seções

Um controle de conteúdo que se estende por mais de uma seção do documento – relatado por IsMultiSection – não é representado por um único nó StructuredDocumentTag, mas por um par StructuredDocumentTagRangeStart / StructuredDocumentTagRangeEnd, conectado através de StructuredDocumentTagRangeStart.RangeEnd. Programe contra a interface compartilhada IStructuredDocumentTag (Tag, Title, Placeholder, PlaceholderName, Appearance, IsShowingPlaceholderText, RemoveSelfOnly()) quando o código precisar lidar uniformemente com as formas de nó único e de intervalo, em vez de ramificar com base no tipo concreto.