Controles de conteúdo

Os controles de conteúdo fornecem uma maneira de criar documentos e modelos que tenham esses recursos:

• Uma interface de usuário que tenha entrada controlada, como um formulário.

• Restrições que impedem os usuários de editar seções protegidas do documento ou modelo. Para obter mais informações, consulte Proteger partes de documentos usando controles de conteúdo.

• Associação de dados a uma fonte de dados. Para obter mais informações, consulte Associar dados a controles de conteúdo.

  Aplica-se a: As informações neste tópico se aplicam a projetos de nível de documento e projetos de Suplemento do VSTO para o Word. Para obter mais informações, consulte Os recursos disponíveis pelo aplicativo do Office e pelo tipo de projeto.

  Para uma demonstração de vídeo relacionada, consulte Associar dados a controles de conteúdo do Word 2007 usando Ferramentas do Visual Studio para o sistema Office (3.0).

Sobre controles de conteúdo

Os controles de conteúdo fornecem uma interface do usuário otimizada para entrada de dados 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 em versões impressas do documento.

Por exemplo, se você quiser que o usuário insira uma data em uma seção do documento, poderá adicionar um controle de conteúdo do seletor de data ao documento. Quando usuários clicam no controle, a interface do usuário padrão do seletor de data é exibida. Você também pode definir propriedades do controle para definir o calendário regional exibido e especificar o formato de data. Depois que o usuário escolher uma data, a interface do controle ficará oculta e somente a data será exibida 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.

• Associe partes de um documento ou modelo aos dados. Você pode associar 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 do 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.

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 um 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.

Galeria de blocos de construção

Uma galeria de blocos de construção permite que os usuários selecionem em uma lista de blocos de construção de documentos a serem inseridos em um documento. Um bloco de construção de documento é um conteúdo que foi criado para ser usado várias vezes, como uma página de capa 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 sel.

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

Ao contrário dos outros tipos de controles de conteúdo, o runtime das Ferramentas do Visual Studio para Office não fornece um tipo específico que representa um controle de conteúdo de caixa de seleção. Em outras palavras, não há tipo CheckBoxContentControl . 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 da 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 usuário para selecionar uma data. O calendário é exibido quando o usuário clica na seta para baixo no controle. Você pode usar calendários regionais e formatos de data diferentes. Para obter mais informações, consulte o tipo DatePickerContentControl.

Lista suspensa

Uma lista suspensa exibe 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 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 quaisquer itens de documento, como texto, tabelas, gráficos e outros controles de conteúdo. Para obter mais informações, consulte o tipo GroupContentControl.

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

Texto rico

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 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ê italicizar 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 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á modificá-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 de 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.

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 nessa 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 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 quiser proteger uma área que contenha controles de conteúdo e outros tipos de conteúdo, você poderá colocar toda a área em um GroupContentControl. Ao contrário de outros controles de conteúdo, um GroupContentControl não fornece nenhuma interface visível para o usuário. Sua única finalidade é definir uma região que os usuários não podem editar.

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.

Associar dados a controles de conteúdo

Você pode exibir dados em documentos associando 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 associação de dados:

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

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

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

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

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

Em projetos de nível de documento, você pode associar 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 associar a cada tipo de dados na janela Fontes de Dados .

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 método da Add propriedade DataBindings do controle. Se você fizer isso, passe a cadeia de caracteres Text para o parâmetro propertyName do método Add. A propriedade Text é a propriedade de associação de dados padrão dos controles de conteúdo.

Os controles de conteúdo também dão 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.

Associar controles de conteúdo a partes XML personalizadas

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

Para associar 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 associar PlainTextContentControl ao elemento Price sob o nó Product em uma parte XML personalizada que já foi adicionada ao documento.

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

plainTextContentControl1.XMLMapping.SetMapping("/Product/Price")

Para obter um passo a passo que demonstra como associar controles de conteúdo a partes XML personalizadas com mais detalhes, consulte Passo a passo: Associar controles de conteúdo a partes XML personalizadas.

Quando você associa um controle de conteúdo a uma parte XML personalizada, a associaçã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 associados aos elementos XML exibirão os novos dados.

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

• ComboBoxContentControl

• DatePickerContentControl

• DropDownListContentControl

• PictureContentControl

• PlainTextContentControl

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.

Limitações dos controles de conteúdo

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

Diferenças de comportamento entre tempo de design e runtime

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 no momento do design. Ao projetar a interface do usuário de uma solução em nível de documento no Visual Studio, certifique-se de modificar os controles de conteúdo apenas de maneiras com suporte 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 dá suporte em tempo de execução, o designer do Visual Studio não alertará você sobre as alterações sem suporte. No entanto, quando você depurar ou executar o projeto ou se salvar e 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 não suportados do elemento de controle.

Por exemplo, o Word não impede que você adicione uma tabela a uma 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 no tempo de design. Por exemplo, se você definir a propriedade LockContents de um controle de conteúdo como True em tempo de design, ainda poderá 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 evento

Os controles de conteúdo não fornecem um evento 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 associar o controle a uma parte XML personalizada e manipular o StoreUpdating evento. Esse evento é gerado quando o usuário altera o conteúdo de um controle associado a uma parte XML personalizada. Para obter um passo a passo que demonstra como associar um controle de conteúdo a uma parte XML personalizada, consulte Passo a passo: associar controles de conteúdo a partes XML personalizadas.

Controles de conteúdo da 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 runtime das Ferramentas do Visual Studio para Office 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 do 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;

Me.Paragraphs(1).Range.InsertParagraphBefore()
Me.Paragraphs(1).Range.Select()
Dim checkBoxControl1 As Microsoft.Office.Tools.Word.ContentControl =
    Me.Controls.AddContentControl("checkBoxControl1", Word.WdContentControlType.wdContentControlCheckBox)


checkBoxControl1.Checked = True

Conteúdo relacionado

• Automatizar o Word usando objetos estendidos
• Como adicionar controles de conteúdo a documentos do Word
• Passo a passo: criar um modelo usando controles de conteúdo
• Dados em soluções do Office
• Associar dados a controles em soluções do Office
• Limitações programáticas de itens de host e controles de host