Partilhar via

Controles de conteúdo

Os controles de conteúdo fornecem uma maneira de criar documentos e modelos com estes recursos:

Sobre os controles de conteúdo

Os controlos de conteúdo oferecem uma interface otimizada para entrada e impressão. Quando você adiciona um controle de conteúdo a um documento, o controle é identificado por uma borda, um título e um texto temporário que podem fornecer instruções ao usuário. A borda e o título do controle não aparecem nas versões impressas do documento.

Por exemplo, se desejar que o usuário insira uma data em uma seção do documento, você poderá adicionar um controle de conteúdo do seletor de data ao documento. Quando os usuários clicam no controle, a interface do usuário do seletor de data padrão é exibida. Você também pode definir propriedades do controle para definir o calendário regional que é exibido e para especificar o formato de data. Depois que o usuário escolhe uma data, a interface do usuário do controle fica oculta e somente a data aparece se o usuário imprimir o documento.

Os controles de conteúdo também ajudam você a fazer o seguinte:

  • Impedir que os utilizadores editem ou eliminem partes de um documento. Isso é útil se você tiver informações em um documento ou modelo que os usuários devem ser capazes de ler, mas não editar, ou se você quiser que os usuários possam editar controles de conteúdo, mas não excluí-los.

  • Vincular partes de um documento ou modelo aos dados. Você pode vincular controles de conteúdo a campos de banco de dados, objetos gerenciados no .NET Framework, elementos XML armazenados no documento e outras fontes de dados.

    Em projetos de nível de documento, você pode adicionar controles de conteúdo ao seu documento em tempo de design ou em tempo de execução. Em projetos de complemento VSTO, pode-se adicionar controlos de conteúdo a qualquer documento aberto em tempo de execução. Para obter mais informações, consulte Como adicionar controles de conteúdo a documentos do Word.

Observação

Você pode usar controles de conteúdo somente em documentos salvos no formato Open XML. Não é possível usar controles de conteúdo em documentos que são salvos no formato de documento (.doc) do Word 97-2003.

Tipos de controles de conteúdo

Há nove tipos diferentes de controles de conteúdo que você pode adicionar aos documentos. A maioria dos controles de conteúdo tem um tipo correspondente no Microsoft.Office.Tools.Word namespace. Você também pode usar um genérico ContentControl, que pode representar qualquer um dos controles de conteúdo disponíveis. Para obter uma explicação passo a passo que demonstra como usar cada um dos controles de conteúdo disponíveis, consulte Passo a passo: Criar um modelo usando controles de conteúdo.

Uma galeria de blocos de construção permite que os usuários selecionem a partir de uma lista de blocos de construção de documentos para inserir em um documento. Um bloco de construção de documento é uma parte do conteúdo que foi criada para ser usada várias vezes, como uma folha de rosto comum, uma tabela formatada ou um cabeçalho. Para obter mais informações, consulte o tipo BuildingBlockGalleryContentControl. Para obter mais informações sobre blocos de construção, consulte Novidades para desenvolvedores no Word 2007.

Caixa de verificação

Uma caixa de seleção fornece uma interface do usuário que representa um estado binário: selecionado ou desmarcado.

Ao contrário dos outros tipos de controles de conteúdo, o Visual Studio Tools for Office runtime não fornece um tipo específico que representa um controle de conteúdo de caixa de seleção. Ou seja, não há CheckBoxContentControl tipo. No entanto, você ainda pode criar um controle de conteúdo de caixa de seleção adicionando um genérico ContentControl a um documento programaticamente. Para obter mais informações, consulte Controles de conteúdo de caixa de seleção em projetos do Word.

Caixa de combinação

Uma caixa de combinação exibe uma lista de itens que os usuários podem selecionar. Ao contrário de uma lista suspensa, a caixa de combinação permite que os usuários adicionem seus próprios itens. Para obter mais informações, consulte o tipo ComboBoxContentControl.

Seletor de data

Um seletor de data fornece uma interface de calendário do utilizador para selecionar uma data. O calendário aparece quando o utilizador final clica na seta suspensa no controlo. Você pode usar calendários regionais e diferentes formatos de data. Para obter mais informações, consulte o tipo DatePickerContentControl.

Uma lista suspensa exibe uma lista de itens que os utilizadores podem selecionar. Ao contrário de uma caixa de combinação, a lista suspensa não permite que os usuários adicionem ou editem itens. Para obter mais informações, consulte o tipo DropDownListContentControl.

Grupo

Um controle de grupo define uma região protegida de um documento que os usuários não podem editar ou excluir. Um controle de grupo pode conter qualquer item de documento, como texto, tabelas, gráficos e outros controles de conteúdo. Para obter mais informações, consulte o tipo GroupContentControl.

Imagem

Um controle de imagem exibe uma imagem. Você pode especificar a imagem em tempo de design ou tempo de execução, ou os usuários podem clicar nesse controle para selecionar uma imagem a ser inserida no documento. Para obter mais informações, consulte o tipo PictureContentControl.

Texto formatado

Um controle rich text contém texto ou outros itens, como tabelas, imagens ou outros controles de conteúdo. Para obter mais informações, consulte o tipo RichTextContentControl.

Texto simples

Um controle de texto sem formatação contém texto. Um controle de texto sem formatação não pode conter outros itens, como tabelas, imagens ou outros controles de conteúdo. Além disso, todo o texto em um controle de texto sem formatação tem a mesma formatação. Por exemplo, se você colocar em itálico uma palavra de uma frase que está em um controle de texto sem formatação, todo o texto dentro do controle será colocado em itálico. Para obter mais informações, consulte o tipo PlainTextContentControl.

Controle de conteúdo genérico

Um controle de conteúdo genérico é um objeto que pode representar qualquer um ContentControl dos tipos disponíveis de controles de conteúdo. Você pode alterar um ContentControl objeto para se comportar como um tipo diferente de controle de conteúdo usando a Type propriedade. Por exemplo, se você criar um ContentControl objeto que representa um controle de texto sem formatação, poderá alterá-lo em tempo de execução para que ele se comporte como uma caixa de combinação.

Você pode criar ContentControl objetos somente em tempo de execução, não em tempo de design. Para obter mais informações, consulte Como adicionar controles de conteúdo a documentos do Word.

Recursos comuns dos controles de conteúdo

A maioria dos controles de conteúdo compartilha um conjunto de membros que você pode usar para executar tarefas comuns. A tabela a seguir descreve algumas das tarefas que você pode executar usando esses membros.

Para esta tarefa: Faça o seguinte:
Obtenha ou defina o texto que é exibido no controle. Utilize a propriedade Text. Observação: Os PictureContentControl e ContentControl tipos não têm essa propriedade.
Obtenha ou defina o texto temporário que é exibido no controle até que um usuário edite o controle, o controle seja preenchido com dados de uma fonte de dados ou o conteúdo do controle seja excluído. Utilize a propriedade PlaceholderText. Observação: O PictureContentControl tipo não tem essa propriedade.
Obtenha ou defina o título que é exibido na borda do controle de conteúdo quando o usuário clica nele. Utilize a propriedade Title.
Remova o controle do documento automaticamente depois que o usuário edita o controle. (O texto no controle permanece no documento.) Use a propriedade Temporário.
Execute o código quando o usuário clica no controle de conteúdo ou quando o cursor é movido para o controle de conteúdo programaticamente. Manipule o Entering evento do controle.
Execute o código quando o usuário clica fora do controle de conteúdo ou quando o cursor é movido para fora do controle de conteúdo programaticamente. Manuseie o Exiting evento do controlo.
Execute o código depois que o controle de conteúdo é adicionado ao documento como resultado de uma operação de refazer ou desfazer. Manipule o Added evento do controle.
Execute o código imediatamente antes de o controle de conteúdo ser excluído do documento. Manipule o Deleting evento do controle.

Proteja partes de documentos usando controles de conteúdo

Ao proteger uma parte de um documento, você impede que os usuários alterem ou excluam o conteúdo dessa parte do documento. Há várias maneiras de proteger partes de um documento usando controles de conteúdo.

Se a área que você deseja proteger estiver dentro de um controle de conteúdo, você poderá usar as propriedades do controle de conteúdo para impedir que os usuários editem ou excluam o controle:

  • A propriedade LockContents impede que os usuários editem o conteúdo.

  • A propriedade LockContentControl impede que os usuários excluam o controle.

    Se a área que deseja proteger não estiver dentro de um controlo de conteúdo, ou se pretende proteger uma área que contém controlos de conteúdo e outros tipos de conteúdo, pode colocar toda a área dentro de um GroupContentControl. Ao contrário de outros controles de conteúdo, um GroupContentControl não fornece nenhuma interface do usuário que é visível para o usuário. Seu único objetivo é definir uma região que os usuários não podem editar.

Observação

Se você criar um GroupContentControl que contém controles de conteúdo incorporado, os controles de conteúdo incorporado não serão protegidos automaticamente. Você deve usar a propriedade LockContents de cada controle incorporado para impedir que os usuários editem seus conteúdos.

Para obter mais informações sobre como usar controles de conteúdo para proteger partes de documentos, consulte Como proteger partes de documentos usando controles de conteúdo.

Vincular dados a controles de conteúdo

Você pode exibir dados em documentos vinculando um controle de conteúdo a uma fonte de dados. Quando a fonte de dados é atualizada, o controle de conteúdo reflete as alterações. Você também pode salvar as alterações de volta na fonte de dados.

Os controles de conteúdo fornecem as seguintes opções de vinculação de dados:

  • Você pode vincular controles de conteúdo a campos de banco de dados ou objetos gerenciados usando o mesmo modelo de associação de dados do Windows Forms.

  • Você pode vincular controles de conteúdo a elementos em partes de XML (também chamadas de partes XML personalizadas) que são incorporadas no documento.

    Para obter uma visão geral da vinculação de controles de host em soluções do Office a dados, consulte Vincular dados a controles em soluções do Office.

Usar o modelo de vinculação de dados do Windows Forms

A maioria dos controles de conteúdo oferece suporte ao modelo de associação de dados simples que o Windows Forms usa. A associação de dados simples significa que um controle está vinculado a um único elemento de dados, como um valor em uma coluna de uma tabela de dados. Para obter mais informações, consulte Vinculação de dados e Windows Forms.

Em projetos de nível de documento, você pode vincular dados a controles de conteúdo usando a janela Fontes de Dados no Visual Studio. Para obter mais informações sobre como adicionar controles de conteúdo associados a dados a documentos, consulte Como preencher documentos com dados de um banco de dados e Como preencher documentos com dados de objetos.

A tabela a seguir lista os controles de conteúdo que você pode vincular a cada tipo de dados na janela Fontes de Dados .

Tipo de dados Controle de conteúdo padrão Outros controles de conteúdo que podem ser vinculados a esse tipo de dados
Boolean

Byte

Char

Double

Enum

Guid

Int16

Int32

Int64

SByte

Single

String

TimeSpan

UInt16

UInt32

UInt64		 PlainTextContentControl BuildingBlockGalleryContentControl

ComboBoxContentControl

DatePickerContentControl

RichTextContentControl
DateTime DatePickerContentControl BuildingBlockGalleryContentControl

ComboBoxContentControl

PlainTextContentControl

RichTextContentControl
Image

Byte matriz		 PictureContentControl Nenhum

Em projetos de suplemento de nível de documento e VSTO, você pode vincular um controle de conteúdo a uma fonte de dados programaticamente usando o Add método da DataBindings propriedade do controle. Se você fizer isso, passe a cadeia de caracteres Text para o parâmetro propertyName do Add método. A propriedade Text é a propriedade de vinculação de dados padrão dos controles de conteúdo.

Os controles de conteúdo também oferecem suporte à vinculação de dados bidirecional, na qual as alterações no controle são atualizadas para a fonte de dados. Para obter mais informações, consulte Como atualizar uma fonte de dados com dados de um controle de host.

Observação

Os controles de conteúdo não oferecem suporte à vinculação de dados complexa. Se você vincular uma DropDownListContentControl ou ComboBoxContentControl a uma fonte de dados usando o modelo de dados do Windows Forms, os usuários verão apenas um único valor quando clicarem no controle. Se você quiser vincular esses controles a um conjunto de valores de dados que os usuários podem escolher, você pode vincular esses controles a elementos em uma parte XML personalizada.

Vincular controles de conteúdo a partes XML personalizadas

Você pode vincular alguns controles de conteúdo a elementos em partes XML personalizadas que são incorporadas no documento. Para obter mais informações sobre partes XML personalizadas, consulte Visão geral de partes XML personalizadas.

Para vincular um controle de conteúdo a um elemento em uma parte XML personalizada, use a propriedade XMLMapping do controle. O exemplo de código a seguir demonstra como vincular um elemento PlainTextContentControl ao elemento Price sob o nó Product em uma parte personalizada de XML que já foi adicionada ao documento.

plainTextContentControl1.XMLMapping.SetMapping("/Product/Price", String.Empty, null);

Para obter uma explicação passo a passo que demonstra como vincular controles de conteúdo a partes XML personalizadas com mais detalhes, consulte Passo a passo: Vincular controles de conteúdo a partes XML personalizadas.

Quando você vincula um controle de conteúdo a uma parte XML personalizada, a vinculação de dados bidirecional é habilitada automaticamente. Se um usuário edita texto no controle, os elementos XML correspondentes são atualizados automaticamente. Da mesma forma, se os valores de elemento nas partes XML personalizadas forem alterados, os controles de conteúdo vinculados aos elementos XML exibirão os novos dados.

Você pode vincular os seguintes tipos de controles de conteúdo a partes XML personalizadas:

Eventos de associação de dados para controles de conteúdo

Todos os controles de conteúdo fornecem um conjunto de eventos que você pode manipular para executar tarefas relacionadas a dados, como validar que o texto em um controle atende a determinados critérios antes que a fonte de dados seja atualizada. A tabela a seguir lista os eventos de controle de conteúdo relacionados à associação de dados.

Tarefa Event
Execute o código imediatamente antes de o Word atualizar automaticamente o texto em um controle de conteúdo vinculado a uma parte XML personalizada. ContentUpdating
Execute o código imediatamente antes de o Word atualizar automaticamente os dados em uma parte XML personalizada que está vinculada a um controle de conteúdo (ou seja, depois que o texto no controle de conteúdo é alterado). StoreUpdating
Execute seu próprio código para validar o conteúdo do controle de acordo com critérios personalizados. Validating
Execute o código depois que o conteúdo do controle tiver sido validado com êxito. Validated

Limitações dos controles de conteúdo

Quando você usa controles de conteúdo em seus projetos do Office, esteja ciente das seguintes limitações.

Diferenças de comportamento entre tempo de design e tempo de execução

Muitas das limitações que o Microsoft Office Word impõe aos controles de conteúdo em tempo de execução não são impostas em tempo de conceção. Quando você cria a interface do usuário de uma solução de nível de documento no Visual Studio, certifique-se de modificar os controles de conteúdo somente de maneiras que são suportadas em tempo de execução.

Se você modificar um controle de conteúdo em tempo de design de uma forma que o controle não oferece suporte em tempo de execução, o designer do Visual Studio não irá alertá-lo sobre as alterações sem suporte. No entanto, quando você depurar ou executar o projeto, ou se você salvar e, em seguida, reabrir o projeto, o Word exibirá uma mensagem de erro e solicitará permissão para reparar o documento. Quando você repara o documento, o Word remove todo o conteúdo e formatação sem suporte do controle.

Por exemplo, o Word não impede que se adicione uma tabela a um PlainTextContentControl no momento de design. No entanto, como PlainTextContentControl os objetos não podem conter tabelas em tempo de execução, o Word exibirá uma mensagem de erro quando o documento for aberto.

Observe também que muitas propriedades que definem o comportamento dos controles de conteúdo não têm efeito em tempo de design. Por exemplo, se você definir a propriedade LockContents de um controle de conteúdo como True em tempo de design, você ainda pode editar texto no controle no designer do Visual Studio. Essa propriedade só impede que os usuários editem o controle em tempo de execução.

Limitações de eventos

Os controles de conteúdo não fornecem um evento que é gerado quando o usuário altera texto ou outros itens no controle. Por exemplo, não há nenhum evento que é gerado quando um usuário seleciona um item diferente em um DropDownListContentControl ou ComboBoxContentControl.

Para determinar quando um usuário edita o conteúdo de um controle de conteúdo, você pode vincular o controle a uma parte XML personalizada e, em seguida, manipular o StoreUpdating evento. Esse evento é gerado quando o usuário altera o conteúdo de um controle que está vinculado a uma parte XML personalizada. Para obter uma explicação passo a passo que demonstra como vincular um controle de conteúdo a uma parte XML personalizada, consulte Passo a passo: Vincular controles de conteúdo a partes XML personalizadas.

Controles de conteúdo de caixa de seleção em projetos do Word

O Word 2010 introduziu um novo tipo de controle de conteúdo que representa uma caixa de seleção. No entanto, o Visual Studio Tools for Office runtime não fornece um tipo CheckBoxContentControl correspondente para você usar em projetos do Office. Para criar um controle de conteúdo de caixa de seleção em um projeto do Word 2013 ou Word 2010, use o AddContentControl método para criar um ContentControl objeto e passe o wdContentControlCheckBox valor para o método para especificar um controle de conteúdo de caixa de seleção. O exemplo de código a seguir demonstra como fazer isso.

this.Paragraphs[1].Range.InsertParagraphBefore();
this.Paragraphs[1].Range.Select();
Microsoft.Office.Tools.Word.ContentControl checkBoxControl1 = 
    this.Controls.AddContentControl("checkBoxControl1", Word.WdContentControlType.wdContentControlCheckBox);

checkBoxControl1.Checked = true;

Conteúdo relacionado

  • Last updated on