Executar mala direta em um documento do Word e inserir imagens ou HTML

Mala Direta é um recurso do Microsoft Word para criar documentos como cartas, etiquetas e envelopes de forma rápida e fácil. O Aspose.Words Cloud pega a mala direta padrão e a avança muitos passos à frente, transformando-a em uma solução de relatórios completa que permite gerar documentos ainda mais complexos, como relatórios, catálogos, inventários e faturas. As vantagens da solução de relatórios Aspose.Words Cloud são:

Crie relatórios no Microsoft Word usando campos de mala direta padrão
Defina regiões no documento que crescem, como linhas de detalhes de um pedido
Inserir imagens durante mala direta
Inserir HTML durante mala direta

Passos básicos

As etapas para executar uma mala direta são bem fáceis. Primeiro, você usa o Microsoft Word para criar e projetar um documento do Word, normalmente chamado de modelo. Observe que o documento não precisa ser um modelo do Microsoft Word (.dot), ele pode ser um documento .doc normal. Você insere alguns campos especiais chamados campos de mesclagem no modelo em locais onde deseja que os dados da sua fonte de dados sejam inseridos posteriormente. Então, com a API REST do Aspose.Words, você executa uma operação de mala direta. A operação de mala direta pegará dados da sua fonte de dados e os mesclará no documento.

Você também pode designar regiões de mesclagem repetíveis no documento ou inserir campos de mesclagem especiais que permitem inserir outro conteúdo, como imagens. Dependendo de como você configura campos de mesclagem de e-mail e regiões repetíveis dentro do documento, o documento crescerá para acomodar vários registros em sua fonte de dados. Se você não usar regiões de mesclagem de e-mail, a mesclagem de e-mail será semelhante à mesclagem de e-mail do Microsoft Word e todo o conteúdo do documento será repetido para cada registro na fonte de dados. Usando regiões de mesclagem de e-mail repetíveis, você pode designar partes dentro de um documento que serão repetidas para cada registro na fonte de dados. Por exemplo, se você marcar uma linha de tabela como uma região repetível, essa linha de tabela será repetida, fazendo com que a tabela cresça dinamicamente para acomodar todos os seus dados.

Preparar um documento

Antes de executar uma mala direta, você precisa preparar o modelo do documento. Você deve inserir campos de mesclagem que serão substituídos por valores da sua fonte de dados.

Inserindo campos de mesclagem em um documento

Para inserir campos de mesclagem em um documento:

Abra seu documento no Microsoft Word.
No documento, clique onde deseja colocar um campo de mesclagem.
Abra o menu Inserir e selecione Campo para abrir a caixa de diálogo Campo.
Na lista Nomes de campos, selecione MergeField.
Na caixa de texto Nome do campo, insira um nome para o campo de mesclagem e pressione OK.

Como um campo de mesclagem é um campo regular do Microsoft Word, você pode alternar entre exibir códigos de campo e resultados no seu documento no Microsoft Word usando o atalho de teclado Alt+F9. Os códigos de campo aparecem entre chaves.

Mala direta simples

Para preparar seu modelo para executar uma mala direta simples (sem regiões, semelhante à mala direta clássica disponível no Microsoft Word), você deve apenas inserir um ou mais campos de mesclagem nos locais que deseja preencher com dados da fonte de dados.

Vamos dar uma olhada na demonstração do convite para jantar. Ele cria uma carta para uma lista de clientes definida na fonte de dados. O modelo contém vários campos de mesclagem que são preenchidos a partir de duas fontes de dados; em outras palavras, duas mesclagens de e-mail são realizadas uma após a outra. Primeiro, os dados da primeira fonte de dados são mesclados no modelo. Esta fonte de dados contém apenas uma linha porque são informações sobre o convidante, então todo o conteúdo do documento não é repetido e apenas os campos apropriados são preenchidos com dados. Então, a segunda operação de mesclagem de e-mail é executada. A fonte de dados que ele usa contém informações sobre os clientes. O modelo inteiro é repetido para cada linha de dados, e cada cópia repetida é preenchida com os dados do cliente correspondente.

Como resultado, temos um documento que consiste em cinco cartas-convite preenchidas, completas e personalizadas (um fragmento da primeira delas é mostrado abaixo):

Como você pode ver, é possível, e às vezes útil, executar mais de uma operação de mesclagem com o mesmo modelo para adicionar dados em estágios. Você pode inserir campos NEXT no documento do Word para fazer com que o mecanismo de mala direta selecione o próximo registro da fonte de dados e continue a mesclagem. Quando o mecanismo encontra um campo NEXT, ele apenas seleciona o próximo registro na fonte de dados e continua a mesclagem sem copiar nenhum conteúdo. Isso pode ser usado ao criar documentos como etiquetas de correspondência.

O código para executar a mala direta simples é fornecido abaixo:

// Para exemplos completos e arquivos de dados, acesse https://github.com/aspose-words-cloud/aspose-words-cloud-dotnet

string MyAppKey = ""; // Get AppKey and AppSID from https://dashboard.aspose.cloud/
string MyAppSid = ""; // Get AppKey and AppSID from https://dashboard.aspose.cloud/

WordsApi wordsApi = new WordsApi(MyAppKey, MyAppSid);
StorageApi storageApi = new StorageApi(MyAppKey, MyAppSid);

var fileName = "DinnerInvitation.docx";
var destFileName = "InviterAdded.docx";
var data = File.ReadAllText(@"c:\Data\" + "Inviter.xml");
string folder = null; // File exists at the root of the storage

// Carregar documento de origem para o Cloud Storage
PutCreateRequest request = new PutCreateRequest(fileName, File.OpenRead(@"c:\Data\" + fileName), null, null);
storageApi.PutCreate(request);

// Executar a operação de mala direta pela primeira vez
var executeMailMergeRequest = new PostDocumentExecuteMailMergeRequest(fileName, data, folder, destFileName: destFileName, withRegions: false);
var actual = wordsApi.PostDocumentExecuteMailMerge(executeMailMergeRequest);

// Executar a operação de mala direta pela segunda vez
fileName = destFileName;
destFileName = "FinalDinnerInvitation.docx";
data = File.ReadAllText(@"c:\Data\" + "Clients.xml");

executeMailMergeRequest = new PostDocumentExecuteMailMergeRequest(fileName, data, folder, destFileName: destFileName, withRegions: false);
actual = wordsApi.PostDocumentExecuteMailMerge(executeMailMergeRequest);

Mala direta com regiões

Se você quiser aumentar dinamicamente partes dentro do documento, use mala direta com regiões. Para especificar uma região de mala direta no documento, você precisa inserir dois campos de mala direta para marcar o início e o fim da região de mala direta. Todo o conteúdo do documento que estiver incluído dentro de uma região de mala direta será repetido automaticamente para cada registro na fonte de dados.

Para marcar o início de uma região de mala direta, insira um MERGEFIELD com o nome TableStart:MyTable, onde MyTable corresponde à tag ou chave em XML ou JSON, respectivamente. Para marcar o fim da região de mala direta, insira outro MERGEFIELD com o nome TableEnd:MyTable. Entre esses campos de marcação, coloque campos de mesclagem que correspondem aos campos da sua fonte de dados. Esses campos de mesclagem serão preenchidos com dados da primeira linha da fonte de dados, então a região inteira será repetida, e os novos campos serão preenchidos com dados da segunda linha, e assim por diante.

Siga estas regras simples ao marcar uma região:

Os campos TableStart e TableEnd devem estar dentro da mesma seção no documento
Se usado dentro de uma tabela, TableStart e TableEnd devem estar dentro da mesma linha na tabela
As regiões de mala direta podem ser aninhadas umas dentro das outras
As regiões de mala direta devem ser bem formadas (sempre há um par de TableStart e TableEnd correspondentes com o mesmo nome de tabela)

Como exemplo, dê uma olhada na demonstração do Item Catalog. Aqui está um fragmento de uma região preparada para mala direta:

Note que ambos os campos de marcação TableStart:Item e TableEnd:Item são colocados dentro da mesma linha da tabela do Word. Após executar a mala direta, aqui está o resultado:

O código para executar a mala direta com regiões é fornecido abaixo:

// Para exemplos completos e arquivos de dados, acesse https://github.com/aspose-words-cloud/aspose-words-cloud-dotnet

string MyAppKey = ""; // Get AppKey and AppSID from https://dashboard.aspose.cloud/
string MyAppSid = ""; // Get AppKey and AppSID from https://dashboard.aspose.cloud/

WordsApi wordsApi = new WordsApi(MyAppKey, MyAppSid);
StorageApi storageApi = new StorageApi(MyAppKey, MyAppSid);

var fileName = "Invoice_Template.doc";
var destFileName = "Invoice_Template_out_.doc";
var data = File.ReadAllText(@"c:\Data\" + "CustomerData.xml");
string folder = null; // File exists at the root of the storage

// Carregar documento de entrada para o Cloud Storage
PutCreateRequest request = new PutCreateRequest(fileName, File.OpenRead(@"c:\Data\" + fileName), null, null);
storageApi.PutCreate(request);

var executeMailMergeRequest = new PostDocumentExecuteMailMergeRequest(fileName, data, folder, destFileName: destFileName, withRegions: true);
var actual = wordsApi.PostDocumentExecuteMailMerge(executeMailMergeRequest);

Mala direta usando a sintaxe do modelo ‘Mustache’

Esta sintaxe permite que você crie modelos para uso com mala direta que usam marcadores de texto simples em vez de campos de mesclagem. Esses marcadores têm a seguinte aparência: {{ FieldName }}

Sintaxe Object.Attribute

Você pode facilmente mesclar atributos de campos usando a seguinte sintaxe:

  {{ Address.Street }}

Isso mesclará dados de dados XML que se parecem com isto:

<Order> // <-- Current context is here.  
  <Number>23</Number>  
  <Address>  
    <Street>Nelson Street</Street>  
    <Suburb>Howick</Suburb>  
    <City>Auckland</City>  
  </Address>  
  <PhoneNumber>543 1234</PhoneNumber>  
</Order>

Blocos Foreach

Você pode mesclar dados de vários registros usando a tag foreach. Isso é semelhante a regiões de mala direta com campos de mesclagem convencionais. Você pode aninhar esses blocos.

{{ #foreach Order }}  
  {{ Number }}  
    {{ Address.Street }}  
      {{ #foreach Item }}  
        {{ Description }} {{ Cost}} {{ Total }}  
      {{/foreach Item }}  
{{ /foreach Order }}

Você também pode misturar esses campos e colocá-los dentro de outros campos do Microsoft Word, como campos SE ou Fórmula.

Bloco Condicional

Você pode usar mala direta com a instrução IF usando o Aspose.Words Cloud. O bloco IF é executado somente se a expressão booleana associada a ele for verdadeira. A sintaxe do IF é mostrada abaixo.

{ IF "{{ GENDER }}" = “MALE” “true text” “false text” }

O código para executar mala direta usando o modelo ‘Mustache’ é fornecido abaixo:

// Para exemplos completos e arquivos de dados, acesse https://github.com/aspose-words-cloud/aspose-words-cloud-dotnet

string MyAppKey = ""; // Get AppKey and AppSID from https://dashboard.aspose.cloud/
string MyAppSid = ""; // Get AppKey and AppSID from https://dashboard.aspose.cloud/

WordsApi wordsApi = new WordsApi(MyAppKey, MyAppSid);
StorageApi storageApi = new StorageApi(MyAppKey, MyAppSid);

var fileName = "VendorTemplate.doc";
var destFileName = "VendorTemplate_Out.docx";
string folder = null; // File exists at the root of the storage

var data = File.ReadAllText(@"c:\Data\" + "Vendors.xml");

// Carregar documento de entrada para o Cloud Storage
PutCreateRequest request = new PutCreateRequest(fileName, File.OpenRead(@"c:\Data\" + fileName), null, null);
storageApi.PutCreate(request);

var postExecuteTemplateRequest = new PostExecuteTemplateRequest(fileName, data, folder, destFileName: destFileName);
var actual = wordsApi.PostExecuteTemplate(postExecuteTemplateRequest);

Inserir HTML durante a mala direta

Ambas as APIs executeMailMerge e executeTemplate fornecem suporte para inserir HTML em um campo de mesclagem. Você só precisa ter certeza de escapar caracteres HTML na string de fonte de dados e usar o atributo “format”=“html” conforme mostrado abaixo:

{     
  "dataSourceList": {   
    "contractDS": {  
      "contractDescription": {  
        "format":"html",   
        "htmlText": "<b>Test me 1<br><br><i>Test me 2<br><br><u>Test me 2</u></i></b><br>"         
      }       
    }     
  }   
}

O código a seguir mostra como inserir HTML durante a mala direta:

// Para exemplos completos e arquivos de dados, acesse https://github.com/aspose-words-cloud/aspose-words-cloud-dotnet

using System;
using System.IO;
using Aspose.Words.Cloud.Sdk;
using Aspose.Words.Cloud.Sdk.Model;
using Aspose.Words.Cloud.Sdk.Model.Requests;

namespace Aspose.Words.Cloud.Examples.CSharp
{
	public class PopulateMailMergeTemplateWithHTMLData
	{
		public static void Run()
		{
			WordsApi wordsApi = new WordsApi(Constants.AppKey, Constants.AppSID);

			try
			{
				string fileName = "template.doc";
				string destName = "Out_PostDocumentExecuteMailMergeWithHTMLData.docx";

				// Carregar documento original no Cloud Storage
				wordsApi.UploadFile(new UploadFileRequest(File.Open("..\\..\\..\\Resources\\" + fileName, FileMode.Open), fileName, Constants.MYStorage));

				string data = File.ReadAllText("..\\..\\..\\Resources\\TestPostDocumentExecuteMailMerge.txt", System.Text.Encoding.UTF8);
				ExecuteMailMergeRequest request = new ExecuteMailMergeRequest(fileName, data, null, Constants.MYStorage, null, null, null, null, null, null, destName);
				DocumentResponse result = wordsApi.ExecuteMailMerge(request);

			}
			catch (Exception e)
			{
				Console.WriteLine(e.ToString());
			}
		}
	}
}

Inserir imagens durante a mala direta

Você também pode inserir imagens em um campo de mesclagem. O fator de escala para imagens pode ser definido usando ‘%’, ‘px’ ou ’’ (escala proporcional).O código para inserir imagens durante a Mala Direta é fornecido abaixo:

// Para exemplos completos e arquivos de dados, acesse https://github.com/aspose-words-cloud/aspose-words-cloud-dotnet

string MyAppKey = ""; // Get AppKey and AppSID from https://dashboard.aspose.cloud/
string MyAppSid = ""; // Get AppKey and AppSID from https://dashboard.aspose.cloud/

WordsApi wordsApi = new WordsApi(MyAppKey, MyAppSid);
StorageApi storageApi = new StorageApi(MyAppKey, MyAppSid);

var fileName = "TestMailMergeWithImages.doc";
var destFileName = "TestMailMergeWithImages_Out.docx";
var data = File.ReadAllText(WordsExamples.PathToDataFiles + @"\DocumentActions\MailMerge\" + "MailMergeData.txt");
string folder = null; // File exists at the root of the storage

// Carregar documento de entrada para o Cloud Storage
PutCreateRequest request = new PutCreateRequest(fileName, File.OpenRead(WordsExamples.PathToDataFiles + @"\DocumentActions\MailMerge\" + fileName), null, null);
storageApi.PutCreate(request);

var executeMailMergeRequest = new PostDocumentExecuteMailMergeRequest(fileName, data, folder, destFileName: destFileName, withRegions: false);
var actual = wordsApi.PostDocumentExecuteMailMerge(executeMailMergeRequest);

SDKs de nuvem

Embora o código acima esteja em .NET, Aspose.Words Cloud SDKs estão disponíveis em cinco linguagens diferentes: .NET, Java, Ruby, Python e Node.js. Portanto, você pode chamar convenientemente APIs de mala direta em qualquer uma dessas linguagens.

Passos básicos#

Preparar um documento#

Inserindo campos de mesclagem em um documento#

Mala direta simples#

Mala direta com regiões#

Mala direta usando a sintaxe do modelo ‘Mustache’#

Sintaxe Object.Attribute#

Blocos Foreach#

Bloco Condicional#

Inserir HTML durante a mala direta#

Inserir imagens durante a mala direta#

SDKs de nuvem#

Postagem sugerida:#