Compartilhar via

Controles de conteúdo

  • Artigo

Os controles de conteúdo fornecem uma maneira de criar documentos e modelos que têm estes recursos:

Sobre controles de conteúdo

Os controles de conteúdo fornecem uma interface do usuário otimizada para entrada e impressão do usuário. 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 aparece. 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 usuários editem ou excluam 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 a 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 documento em tempo de design ou em tempo de execução. Em projetos de suplemento VSTO, você pode adicionar controles 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. Você não pode 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 a 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 Demonstra Passo a passo: criar um modelo usando controles de conteúdo.

Uma galeria de blocos de construção permite que os usuários selecionem de uma lista de blocos de construção de documento 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 BuildingBlockGalleryContentControl tipo. Para obter mais informações sobre blocos de construção, consulte Novidades para desenvolvedores no Word 2007.

Caixa de seleçã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 CheckBoxContentControl há 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 ComboBoxContentControl tipo.

Seletor de data

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

Uma lista suspensa exibe uma lista de itens que os usuários 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 DropDownListContentControl tipo.

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, elementos gráficos e outros controles de conteúdo. Para obter mais informações, consulte o GroupContentControl tipo.

Picture

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 PictureContentControl tipo.

Rich text

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 RichTextContentControl tipo.

Texto sem formatação

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á itálico. Para obter mais informações, consulte o PlainTextContentControl tipo.

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 objeto para se comportar como um ContentControl tipo diferente de controle de conteúdo usando a Type propriedade. Por exemplo, se você criar um objeto que representa um ContentControl 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 isto
Obtenha ou defina o texto que é exibido no controle. Use a propriedade Text . Nota: Os PictureContentControl tipos e ContentControl 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. Use a propriedade PlaceholderText . Nota: 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. Use 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 Temporary .
Execute 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 código quando o usuário clicar fora do controle de conteúdo ou quando o cursor for movido para fora do controle de conteúdo programaticamente. Manipule o Exiting evento do controle.
Execute o código depois que o controle de conteúdo for adicionado ao documento como resultado de uma operação de refazer ou desfazer. Manipule o Added evento do controle.
Execute o código antes que o controle de conteúdo seja excluído do documento. Manipule o Deleting evento do controle.

Proteger 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 você deseja proteger não estiver dentro de um controle de conteúdo, ou se você quiser proteger uma área que contém controles de conteúdo e outros tipos de conteúdo, você pode colocar toda a área em um GroupContentControlarquivo . Ao contrário de outros controles de conteúdo, um não fornece nenhuma GroupContentControl interface do usuário 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 que contenha controles de conteúdo incorporados, os controles de GroupContentControl conteúdo incorporados não serão protegidos automaticamente. Você deve usar a propriedade LockContents de cada controle incorporado para impedir que os usuários editem seu conteúdo.

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 vinculaçã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 vinculação de dados simples que o Windows Forms usa. A vinculaçã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 vinculados 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

Matriz Byte		 PictureContentControl Nenhum

Em projetos de suplemento VSTO e nível de documento, você pode vincular um controle de conteúdo a uma fonte de dados programaticamente usando o Add DataBindings método da 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 à associaçã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 à associação de dados complexos. Se você vincular uma ou ComboBoxContentControl a uma DropDownListContentControl 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 desejar vincular esses controles a um conjunto de valores de dados que os usuários podem escolher, você poderá 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 PlainTextContentControl ao elemento sob o Product nó em uma parte XML personalizada que já foi adicionada ao Price documento.

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

Para obter um passo a passo que demonstra como vincular controles de conteúdo a partes XML personalizadas com mais detalhes, consulte Demonstra 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 editar texto no controle, os elementos XML correspondentes serã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 vinculaçã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 se 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 Evento
Execute o código 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 antes de o Word atualizar automaticamente os dados em uma parte XML personalizada vinculada a um controle de conteúdo (ou seja, depois que o texto no controle de conteúdo for 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

Ao usar controles de conteúdo em seus projetos do Office, esteja ciente das limitações a seguir.

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 design. Quando você cria a interface do usuário de uma solução de nível de documento no Visual Studio, certifique-se de modificar 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 maneira 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ê reparar o documento, o Word remove todo o conteúdo sem suporte e formatação do controle.

Por exemplo, o Word não impede que você adicione uma tabela a um PlainTextContentControl em tempo 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 do evento

Os controles de conteúdo não fornecem um evento que é gerado quando o usuário altera o texto ou outros itens no controle. Por exemplo, não há nenhum evento 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 Demonstra 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 método para criar um objeto e passe o valor para o AddContentControl wdContentControlCheckBox método para especificar um ContentControl 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