Trabalhando com Tags de Documento Estruturado (Controles de Conteúdo)

Trabalhando com Tags de Documento Estruturado (Controles de Conteúdo)

Uma tag de documento estruturado (SDT), conhecida na interface do Word como controle de conteúdo, envolve uma parte do conteúdo do documento com comportamento de edição tipado e restrito – uma caixa de seleção, um seletor de data, uma lista suspensa ou um espaço reservado de texto simples ou rico. Aspose.Words FOSS para .NET modela esses através do Aspose.Words.Markup namespace, liderada por o StructuredDocumentTag classe. Esta página aborda a inserção de controles de conteúdo, a configuração de cada tipo, a localização e remoção deles, e a vinculação a dados personalizados XML.

O Modelo de Objeto da Tag de Documento Estruturado

StructuredDocumentTag é um CompositeNode que também implementa IMarkupNode, ITrackableNode e IStructuredDocumentTag. SdtType identifica qual tipo de controle ele é. Tag e Title armazenam as strings de identificação que os autores definem no Word; Placeholder (um BuildingBlock) e PlaceholderName fornecem o texto de sugestão exibido quando o controle está vazio, relatado via IsShowingPlaceholderText. LockContentControl impede que o controle seja excluído, e LockContents impede que seu conteúdo seja editado, de forma independente um do outro.

Inserindo Controles de Conteúdo

DocumentBuilder.InsertStructuredDocumentTag(SdtType) insere um novo controle no cursor, mas apenas para sete dos valores SdtType: PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture e Date. RepeatingSection e RepeatingSectionItem não podem ser inseridos em um cursor de texto dessa forma — eles envolvem parágrafos inteiros ou linhas de tabela. Os valores restantes SdtType que aparecem em arquivos do 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 suportados por este método de inserção.

Conteúdo Específico por Tipo

O estado de um controle de caixa de seleção é StructuredDocumentTag.Checked; SetCheckedSymbol() e SetUncheckedSymbol() definem os glifos mostrados para cada estado. Um controle de data armazena seu valor em FullDate, com DateDisplayFormat e DateDisplayLocale controlando como ele é renderizado, DateStorageFormat (um SdtDateStorageFormat) controlando como ele é armazenado quando vinculado a dados XML, e CalendarType (um SdtCalendarType) selecionando o sistema de calendário. Uma lista suspensa ou caixa de combinação expõe suas opções através de ListItems, um SdtListItemCollection de SdtListItem (DisplayText, Value) com um SelectedValue. A propriedade Multiline de um controle de texto simples permite ou impede quebras de linha dentro dele.

Aparência e Bloqueio

Appearance (SdtAppearance) controla como o controle é visualmente delimitado no Word. Color define sua cor de realce, e ContentsFont / EndCharacterFont controlam a fonte aplicada ao seu conteúdo e ao caractere final de terminação. LockContentControl e LockContents são interruptores independentes – o primeiro impede a exclusão do próprio controle, o segundo impede a edição do que está dentro dele.

Localizando e Removendo Controles de Conteúdo

Range.StructuredDocumentTags devolve um StructuredDocumentTagCollection limitado a esse intervalo, com GetById(), GetByTag() e GetByTitle() para pesquisa direcionada juntamente com Remove() e RemoveAt(). Em um StructuredDocumentTag individual, Remove() exclui o controle e seu conteúdo juntos, RemoveSelfOnly() exclui apenas o invólucro e mantém seu conteúdo no documento, e Clear() esvazia o conteúdo do controle mantendo o próprio controle.

XML Vinculação de Dados

StructuredDocumentTag.XmlMapping é uma instância XmlMapping que descreve uma vinculação a uma parte XML personalizada no documento: CustomXmlPart, XPath, PrefixMappings, StoreItemId e IsMapped. SetMapping() estabelece a vinculação a uma parte XML personalizada existente e Delete() a remove.

Controles de Conteúdo Multi-Seção (Com Intervalo)

Um controle de conteúdo que abrange mais de uma seção – relatado por IsMultiSection – é representado não por um único nó StructuredDocumentTag, mas por um par de nós StructuredDocumentTagRangeStart e StructuredDocumentTagRangeEnd, conectados através de StructuredDocumentTagRangeStart.RangeEnd. Ambas as formas de nó único e de intervalo implementam a interface comum IStructuredDocumentTag, de modo que o código que precisa apenas de Tag, Title, SdtType, Placeholder e propriedades de identificação semelhantes pode trabalhar com qualquer das formas uniformemente.

Dicas e Melhores Práticas

• Verifique a lista de tipos suportados de DocumentBuilder.InsertStructuredDocumentTag() antes de confiar nele – somente PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture e Date podem ser inseridos no cursor; outros tipos lançam uma exceção.
• Use RemoveSelfOnly() em vez de Remove() quando você deseja “flatten” um controle de conteúdo – mantenha seu conteúdo no documento, mas remova o invólucro de controle.
• Preencha ListItems antes de esperar que um controle DropDownList ou ComboBox apresente opções, e defina SelectedValue para escolher o ativo.
• Programe contra IStructuredDocumentTag em vez de StructuredDocumentTag diretamente se seu código precisar lidar com controles de conteúdo normais e de múltiplas seções (intervalados) da mesma maneira.
• XmlMapping.SetMapping() vincula-se a uma parte personalizada XML que já deve existir no armazenamento de dados personalizado XML do documento – adicione ou carregue os dados XML antes de mapear um controle para ele.

Problemas Comuns

FAQ

Quais tipos de controle de conteúdo posso inserir diretamente com DocumentBuilder?

PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture e Date. Outros valores de SdtType não são suportados por InsertStructuredDocumentTag().

Como encontro todos os controles de conteúdo com uma tag específica?

Use Range.StructuredDocumentTags.GetByTag(), ou GetByTitle() / GetById() se você estiver correspondendo a eles em vez disso.

Como removo um controle de conteúdo mas mantenho seu conteúdo?

Chame StructuredDocumentTag.RemoveSelfOnly() em vez de Remove().

Como vinculo um controle de conteúdo a dados personalizados de XML?

Chame XmlMapping.SetMapping() no controle, apontando-o para uma parte XML personalizada existente e uma expressão XPath dentro dela.

Qual é a diferença entre um StructuredDocumentTag simples e um com intervalo?

Um controle de conteúdo que abrange mais de uma seção do documento é representado como um par StructuredDocumentTagRangeStart / StructuredDocumentTagRangeEnd em vez de um único nó; ambas as formas implementam IStructuredDocumentTag.

API Reference Resumo

Ver também

• Aspose.Words for .NET — Enterprise Documentation