Demonstra Passo a passo: Vincular controles de conteúdo a partes XML personalizadas

Artigo
10/10/2023

Esta explicação passo a passo demonstra como vincular controles de conteúdo em uma personalização em nível de documento para o Word para dados XML armazenados no documento.

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

O Word permite que você armazene dados XML, denominados partes XML personalizadas, em um documento. Você pode controlar a exibição desses dados vinculando controles de conteúdo a elementos em uma parte XML personalizada. O documento de exemplo neste passo a passo exibe informações do funcionário que são armazenadas em uma parte XML personalizada. Quando você abre o documento, os controles de conteúdo exibem os valores dos elementos XML. Todas as alterações feitas no texto nos controles de conteúdo são salvas na parte XML personalizada.

Este passo a passo ilustra as seguintes tarefas:

Adicionando controles de conteúdo ao documento do Word em um projeto de nível de documento em tempo de design.
Criando um arquivo de dados XML e um esquema XML que define os elementos a serem vinculados aos controles de conteúdo.
Anexar o esquema XML ao documento em tempo de design.
Adicionando o conteúdo do arquivo XML a uma parte XML personalizada no documento em tempo de execução.
Vinculação dos controles de conteúdo a elementos na parte XML personalizada.
Vinculação a DropDownListContentControl a um conjunto de valores definidos no esquema XML.

Observação

Seu computador pode mostrar diferentes nomes ou locais para alguns dos elementos de interface do usuário do Visual Studio nas instruções a seguir. A edição do Visual Studio que você possui e as configurações que você usa determinam esses elementos. Para obter mais informações, confira Personalizar o IDE.

Pré-requisitos

Você precisará dos seguintes componentes para concluir este passo a passo:

Uma edição do Visual Studio que inclui o Microsoft Office Developer Tools. Para obter mais informações, consulte Configurar um computador para desenvolver soluções do Office.
Microsoft Word.

Criar um novo projeto de documento do Word

Crie um documento do Word que você usará na explicação passo a passo.

Para criar um novo projeto de documento do Word

Crie um projeto de documento do Word com o nome EmployeeControls. Crie um novo documento para a solução. Para obter mais informações, consulte Como: Criar projetos do Office no Visual Studio.

O Visual Studio abre o novo documento do Word no designer e adiciona o projeto EmployeeControls ao Gerenciador de Soluções.

Adicionar controles de conteúdo ao documento

Crie uma tabela que contenha três tipos diferentes de controles de conteúdo onde o usuário pode exibir ou editar informações sobre um funcionário.

Para adicionar controles de conteúdo ao documento

No documento do Word hospedado no designer do Visual Studio, na Faixa de Opções, escolha a guia Inserir .
No grupo Tabelas, escolha Tabela e insira uma tabela com 2 colunas e 3 linhas.
Digite o texto na primeira coluna para que ele se assemelhe à seguinte coluna:

Nome do Funcionário

Data de Contratação

Título
Na segunda coluna da tabela, escolha a primeira linha (ao lado de Nome do funcionário).
Na Faixa de Opções, escolha a guia Desenvolvedor .

Observação

Se a guia Desenvolvedor não estiver visível, você deverá mostrá-la primeiro. Para obter mais informações, consulte Como mostrar a guia do desenvolvedor na faixa de opções.
No grupo Controles, escolha o botão Texto para adicionar um PlainTextContentControl à primeira célula.
Na segunda coluna da tabela, escolha a segunda linha (ao lado de Data de contratação).
No grupo Controles, escolha o botão Seletor de Data para adicionar um DatePickerContentControl à segunda célula.
Na segunda coluna da tabela, escolha a terceira linha (ao lado de Título).
No grupo Controles, escolha o botão Lista suspensa para adicionar um DropDownListContentControl à última célula.

Essa é toda a interface do usuário para este projeto. Se você executar o projeto agora, poderá digitar texto na primeira linha e selecionar uma data na segunda linha. A próxima etapa é anexar os dados que você deseja exibir ao documento em um arquivo XML.


Nome do Funcionário
Data de Contratação
Título

Criar o arquivo de dados XML

Normalmente, você obterá dados XML para armazenar em uma parte XML personalizada de uma fonte externa, como um arquivo ou um banco de dados. Nesta explicação passo a passo, você cria um arquivo XML que contém os dados do funcionário, marcados por elementos que serão vinculados aos controles de conteúdo no documento. Para disponibilizar os dados em tempo de execução, incorpore o arquivo XML como um recurso no assembly de personalização.

Para criar o arquivo de dados

No menu Projeto, escolha Adicionar Novo Item.

A caixa de diálogo Adicionar Novo Item aparecerá.
No painel Modelos, selecione Arquivo XML.
Nomeie os funcionários do arquivo .xml e escolha o botão Adicionar .

O arquivo .xml funcionários é aberto no Editor de Códigos.

Substitua o conteúdo do arquivo .xml funcionários pelo texto a seguir.

<?xml version="1.0" encoding="utf-8" ?>
<employees xmlns="http://schemas.microsoft.com/vsto/samples">
  <employee>
    <name>Karina Leal</name>
    <hireDate>1999-04-01</hireDate>
    <title>Manager</title>
  </employee>
</employees>

No Gerenciador de Soluções, escolha o arquivo .xml funcionários.
Na janela Propriedades, selecione a propriedade Ação de Criação e altere o valor para Recurso Incorporado.

Esta etapa incorpora o arquivo XML como um recurso no assembly quando você cria o projeto. Isso permite que você acesse o conteúdo do arquivo XML em tempo de execução.

Criar um Esquema XML

Se você deseja vincular um controle de conteúdo a um único elemento em uma parte XML personalizada, não é necessário usar um esquema XML. No entanto, para vincular o a um conjunto de valores, você deve criar um esquema XML que valida o DropDownListContentControl arquivo de dados XML que você criou anteriormente. O esquema XML define os valores possíveis para o title elemento. Você vinculará o a esse elemento mais adiante nesta explicação passo a DropDownListContentControl passo.

Para criar um esquema XML

No menu Projeto, escolha Adicionar Novo Item.

A caixa de diálogo Adicionar Novo Item aparecerá.
No painel Modelos, selecione Esquema XML.
Nomeie o esquema employees.xsd e escolha o botão Adicionar .

O designer de esquema é aberto.
No Gerenciador de Soluções, abra o menu de atalho para employees.xsd e escolha Exibir Código.

Substitua o conteúdo do arquivo employees.xsd pelo esquema a seguir.

<?xml version="1.0" encoding="utf-8" ?>
<xs:schema xmlns="http://schemas.microsoft.com/vsto/samples"
    targetNamespace="http://schemas.microsoft.com/vsto/samples"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    elementFormDefault="qualified">
  <xs:element name="employees" type="EmployeesType"></xs:element>
  <xs:complexType name="EmployeesType">
    <xs:all>
      <xs:element name="employee" type="EmployeeType"/>
    </xs:all>
  </xs:complexType>
  <xs:complexType name="EmployeeType">
    <xs:sequence>
      <xs:element name="name" type="xs:string" minOccurs="1" maxOccurs="1"/>
      <xs:element name="hireDate" type="xs:date" minOccurs="1" maxOccurs="1"/>
      <xs:element name="title" type="TitleType" minOccurs="1" maxOccurs="1"/>
    </xs:sequence>
  </xs:complexType>
  <xs:simpleType name="TitleType">
    <xs:restriction base="xs:string">
      <xs:enumeration value ="Engineer"/>
      <xs:enumeration value ="Designer"/>
      <xs:enumeration value ="Manager"/>
    </xs:restriction>
  </xs:simpleType>
</xs:schema>

No menu Arquivo, clique em Salvar Tudo para salvar suas alterações nos arquivos employees.xml e employees.xsd.

Anexar o esquema XML ao documento

Você deve anexar o esquema XML ao documento para vincular o DropDownListContentControl aos valores válidos do title elemento.

Para anexar o esquema XML ao documento ( Word 2013 )

Ative EmployeeControls.docx no designer.
Na Faixa de Opções, escolha a guia Desenvolvedor e escolha o botão Suplementos .
Na caixa de diálogo Modelos e Suplementos, escolha a guia Esquema XML e escolha o botão Adicionar Esquema.
Navegue até o esquema employees.xsd criado anteriormente, localizado no diretório do projeto, e escolha o botão Abrir.
Escolha o botão OK na caixa de diálogo Configurações do esquema.
Escolha o botão OK para fechar a caixa de diálogo Modelos e Suplementos .

Para anexar o esquema XML ao documento (Word 2010)

Ative EmployeeControls.docx no designer.
Na Faixa de Opções, escolha a guia Desenvolvedor .
No grupo XML, escolha o botão Esquema.
Na caixa de diálogo Modelos e Suplementos, escolha a guia Esquema XML e escolha o botão Adicionar Esquema.
Navegue até o esquema employees.xsd que você criou anteriormente, que está localizado no diretório do projeto, e escolha o botão Abrir.
Escolha o botão OK na caixa de diálogo Configurações do esquema.
Escolha o botão OK para fechar a caixa de diálogo Modelos e Suplementos .

O painel de tarefas Estrutura XML é aberto.
Feche o painel de tarefas Estrutura XML .

Adicionar uma parte XML personalizada ao documento

Antes de vincular os controles de conteúdo aos elementos no arquivo XML, você deve adicionar o conteúdo do arquivo XML a uma nova parte XML personalizada no documento.

Para adicionar uma parte XML personalizada ao documento

No Gerenciador de Soluções, abra o menu de atalho para ThisDocument.cs ou ThisDocument.vb e escolha Exibir código.

Adicione as seguintes declarações à ThisDocument classe. Esse código declara vários objetos que você usará para adicionar uma parte XML personalizada ao documento.

[CachedAttribute()]
public string employeeXMLPartID = string.Empty;
private Office.CustomXMLPart employeeXMLPart;
private const string prefix = "xmlns:ns='http://schemas.microsoft.com/vsto/samples'";

<Cached()> _
Public employeeXMLPartID As String = String.Empty
Private employeeXMLPart As Office.CustomXMLPart
Private Const prefix As String = "xmlns:ns='http://schemas.microsoft.com/vsto/samples'"

Adicione o método a seguir à classe ThisDocument. Esse método obtém o conteúdo do arquivo de dados XML que é incorporado como um recurso no assembly e retorna o conteúdo como uma cadeia de caracteres XML.

private string GetXmlFromResource()
{
    System.Reflection.Assembly asm =
        System.Reflection.Assembly.GetExecutingAssembly();
    System.IO.Stream stream1 = asm.GetManifestResourceStream(
        "EmployeeControls.employees.xml");

    using (System.IO.StreamReader resourceReader =
            new System.IO.StreamReader(stream1))
    {
        if (resourceReader != null)
        {
            return resourceReader.ReadToEnd();
        }
    }

    return null;
}

Private Function GetXmlFromResource() As String
    Dim asm As System.Reflection.Assembly = _
        System.Reflection.Assembly.GetExecutingAssembly()
    Dim stream1 As System.IO.Stream = asm.GetManifestResourceStream( _
            "EmployeeControls.employees.xml")

    Using resourceReader As System.IO.StreamReader = _
        New System.IO.StreamReader(stream1)
        If resourceReader IsNot Nothing Then
            Return resourceReader.ReadToEnd()
        End If
    End Using

    Return Nothing
End Function

Adicione o método a seguir à classe ThisDocument. O AddCustomXmlPart método cria uma nova parte XML personalizada que contém uma cadeia de caracteres XML que é passada para o método.

Para garantir que a parte XML personalizada seja criada apenas uma vez, o método cria a parte XML personalizada somente se uma parte XML personalizada com um GUID correspondente ainda não existir no documento. Na primeira vez que esse método é chamado, ele salva o valor da propriedade na employeeXMLPartID cadeia de Id caracteres. O valor da cadeia de employeeXMLPartID caracteres é persistido no documento porque foi declarado usando o CachedAttribute atributo.

private void AddCustomXmlPart(string xmlData)
{
    if (xmlData != null)
    {
        employeeXMLPart = this.CustomXMLParts.SelectByID(employeeXMLPartID);
        if (employeeXMLPart == null)
        {
            employeeXMLPart = this.CustomXMLParts.Add(xmlData);
            employeeXMLPart.NamespaceManager.AddNamespace("ns", 
                @"http://schemas.microsoft.com/vsto/samples");
            employeeXMLPartID = employeeXMLPart.Id;
        }
    }
}

Private Sub AddCustomXmlPart(ByVal xmlData As String)
    If xmlData IsNot Nothing Then

        employeeXMLPart = Me.CustomXMLParts.SelectByID(employeeXMLPartID)
        If (employeeXMLPart Is Nothing) Then
            employeeXMLPart = Me.CustomXMLParts.Add(xmlData)
            employeeXMLPart.NamespaceManager.AddNamespace("ns", _
                "http://schemas.microsoft.com/vsto/samples")
            employeeXMLPartID = employeeXMLPart.Id
        End If
    End If
End Sub

Vincular os controles de conteúdo a elementos na parte XML personalizada

Vincule cada controle de conteúdo a um elemento na parte XML personalizada usando a propriedade XMLMapping de cada controle de conteúdo.

Para vincular os controles de conteúdo a elementos na parte XML personalizada

Adicione o método a seguir à classe ThisDocument. Esse método vincula cada controle de conteúdo a um elemento na parte XML personalizada e define o formato de exibição de data do DatePickerContentControl.

private void BindControlsToCustomXmlPart()
{
    string xPathName = "ns:employees/ns:employee/ns:name";
    this.plainTextContentControl1.XMLMapping.SetMapping(xPathName,
        prefix, employeeXMLPart);

    string xPathDate = "ns:employees/ns:employee/ns:hireDate";
    this.datePickerContentControl1.DateDisplayFormat = "MMMM d, yyyy";
    this.datePickerContentControl1.XMLMapping.SetMapping(xPathDate,
        prefix, employeeXMLPart);

    string xPathTitle = "ns:employees/ns:employee/ns:title";
    this.dropDownListContentControl1.XMLMapping.SetMapping(xPathTitle,
        prefix, employeeXMLPart);
}

Private Sub BindControlsToCustomXmlPart()
    Dim xPathName As String = "ns:employees/ns:employee/ns:name"
    Me.PlainTextContentControl1.XMLMapping.SetMapping(xPathName, _
        prefix, employeeXMLPart)

    Dim xPathDate As String = "ns:employees/ns:employee/ns:hireDate"
    Me.DatePickerContentControl1.DateDisplayFormat = "MMMM d, yyyy"
    Me.DatePickerContentControl1.XMLMapping.SetMapping(xPathDate, _
        prefix, employeeXMLPart)

    Dim xPathTitle As String = "ns:employees/ns:employee/ns:title"
    Me.DropDownListContentControl1.XMLMapping.SetMapping(xPathTitle, _
        prefix, employeeXMLPart)
End Sub

Execute o código quando o documento for aberto

Crie a parte XML personalizada e vincule os controles personalizados aos dados quando o documento for aberto.

Para executar o código quando o documento é aberto

Adicione o seguinte código ao ThisDocument_Startup método da ThisDocument classe. Esse código obtém a cadeia de caracteres XML do arquivo .xml funcionários, adiciona a cadeia de caracteres XML a uma nova parte XML personalizada no documento e vincula os controles de conteúdo a elementos na parte XML personalizada.
- C#
- VB
```
string xmlData = GetXmlFromResource();

if (xmlData != null)
{
    AddCustomXmlPart(xmlData);
    BindControlsToCustomXmlPart();
}
```
```
Dim xmlData As String = GetXmlFromResource()
If xmlData IsNot Nothing Then
    AddCustomXmlPart(xmlData)
    BindControlsToCustomXmlPart()
End If
```

Testar o projeto

Quando você abre o documento, os controles de conteúdo exibem dados dos elementos na parte XML personalizada. Você pode clicar no DropDownListContentControl para selecionar um dos três valores válidos para o title elemento, que são definidos no arquivo employees.xsd . Se você editar os dados em qualquer um dos controles de conteúdo, os novos valores serão salvos na parte XML personalizada no documento.

Para testar os controles de conteúdo

Pressione F5 para executar o projeto.
Verifique se a tabela no documento é semelhante à tabela a seguir. Cada uma das cadeias de caracteres na segunda coluna é obtida de um elemento na parte XML personalizada no documento.

Coluna Valor

Nome do Funcionário Karina Leal

Data de Contratação 1 de abril de 1999

Título Gerente
Escolha a célula à direita da célula Nome do Funcionário e digite um nome diferente.
Escolha a célula à direita da célula Data de contratação e selecione uma data diferente no seletor de datas.
Escolha a célula à direita da célula Título e selecione um novo item na lista suspensa.
Salve e feche o documento.
No Explorador de Arquivos, abra a pasta \bin\Debug no local do projeto.
Abra o menu de atalho para EmployeeControls.docx e escolha Renomear.
Nomeie o arquivo EmployeeControls.docx.zip.

O documento EmployeeControls.docx é salvo no formato Open XML. Ao renomear este documento com a extensão de nome de arquivo .zip , você pode examinar o conteúdo do documento. Para obter mais informações sobre o Open XML, consulte o artigo técnico Apresentando os formatos de arquivo Open XML do Office (2007).
Abra o arquivo EmployeeControls.docx.zip .
Abra a pasta customXml .
Abra o menu de atalho do item2.xml e escolha Abrir.

Esse arquivo contém a parte XML personalizada que você adicionou ao documento.
Verifique se os elementos , hireDatee title contêm os namenovos valores inseridos nos controles de conteúdo no documento.
Feche o arquivo item2.xml .

Coluna	Valor
Nome do Funcionário	Karina Leal
Data de Contratação	1 de abril de 1999
Título	Gerente

Próximas etapas

Você pode saber mais sobre como usar controles de conteúdo nestes tópicos:

Use todos os controles de conteúdo disponíveis para criar um modelo. Para obter mais informações, consulte Demonstra Passo a passo: Criar um modelo usando controles de conteúdo.
Modifique os dados nas partes XML personalizadas enquanto o documento está fechado. Na próxima vez que o usuário abrir o documento, os controles de conteúdo vinculados aos elementos XML exibirão os novos dados.
Use controles de conteúdo para proteger partes de um documento. Para obter mais informações, consulte Como: Proteger partes de documentos usando controles de conteúdo.

Partilhar via

Demonstra Passo a passo: Vincular controles de conteúdo a partes XML personalizadas

Pré-requisitos

Criar um novo projeto de documento do Word

Para criar um novo projeto de documento do Word

Adicionar controles de conteúdo ao documento

Para adicionar controles de conteúdo ao documento

Criar o arquivo de dados XML

Para criar o arquivo de dados

Criar um Esquema XML

Para criar um esquema XML

Anexar o esquema XML ao documento

Para anexar o esquema XML ao documento ( Word 2013 )

Para anexar o esquema XML ao documento (Word 2010)

Adicionar uma parte XML personalizada ao documento

Para adicionar uma parte XML personalizada ao documento

Vincular os controles de conteúdo a elementos na parte XML personalizada

Para vincular os controles de conteúdo a elementos na parte XML personalizada

Execute o código quando o documento for aberto

Para executar o código quando o documento é aberto

Testar o projeto

Para testar os controles de conteúdo

Próximas etapas

Comentários

Recursos adicionais

Partilhar via

Demonstra Passo a passo: Vincular controles de conteúdo a partes XML personalizadas

Pré-requisitos

Criar um novo projeto de documento do Word

Para criar um novo projeto de documento do Word

Adicionar controles de conteúdo ao documento

Para adicionar controles de conteúdo ao documento

Criar o arquivo de dados XML

Para criar o arquivo de dados

Criar um Esquema XML

Para criar um esquema XML

Anexar o esquema XML ao documento

Para anexar o esquema XML ao documento ( Word 2013 )

Para anexar o esquema XML ao documento (Word 2010)

Adicionar uma parte XML personalizada ao documento

Para adicionar uma parte XML personalizada ao documento

Vincular os controles de conteúdo a elementos na parte XML personalizada

Para vincular os controles de conteúdo a elementos na parte XML personalizada

Execute o código quando o documento for aberto

Para executar o código quando o documento é aberto

Testar o projeto

Para testar os controles de conteúdo

Próximas etapas

Conteúdo relacionado

Comentários

Recursos adicionais