Mala Direta

Mala Direta

Este guia mostra como trabalhar com códigos de mesclagem e dados de configuração de mesclagem em Aspose.Words FOSS para .NET, e onde está o limite com a execução da mesclagem. Aspose.Words FOSS para .NET reconhece e atualiza os códigos de mesclagem do Word — ADDRESSBLOCK, DATABASE, GREETINGLINE, MERGEFIELD, NEXTIF, e SKIPIF — como parte de seu motor de avaliação de campos, e pode ler os dados de configuração de mesclagem (MailMergeSettings) persistidos dentro de um documento. Executar uma mesclagem real contra uma fonte de dados externa para gerar documentos de saída preenchidos — o MailMerge.Execute() fluxo de trabalho familiar do produto comercial — está not implementado nesta edição; nenhum MailMerge classe de execução existe na superfície atual de API.

MERGEFIELD — Leitura e Modificação de Marcadores de Mesclagem

FieldMergeField implementa o campo MERGEFIELD. FieldName e FieldNameNoPrefix retornam o nome da coluna da fonte de dados subjacente ao qual o campo está vinculado, TextBefore/TextAfter contêm texto literal que envolve o valor mesclado, e IsMapped/IsVerticalFormatting fornecem o mapeamento de campo de mesclagem e indicadores de layout. Como todo tipo de campo, ele oferece suporte a GetFieldCode(), Update(), Unlink() e Remove().

ADDRESSBLOCK e GREETINGLINE

FieldAddressBlock implementa o campo ADDRESSBLOCK, com FormatAddressOnCountryOrRegion, IncludeCountryOrRegionName, ExcludedCountryOrRegionName, NameAndAddressFormat e LanguageId controlando como o endereço do destinatário é formatado. FieldGreetingLine implementa GREETINGLINE, com AlternateText, NameFormat e LanguageId controlando o texto da saudação.

Campo DATABASE

FieldDatabase implementa o campo DATABASE, expondo os detalhes de conexão armazenados no campo: Connection, FileName, Query, TableFormat, InsertHeadings, InsertOnceOnMailMerge, FirstRecord e LastRecord. Para fornecer resultados de consulta quando esse campo for atualizado, implemente IFieldDatabaseProvider e seu método GetQueryResult(fileName, connection, query, field), atribua-o a Document.FieldOptions.FieldDatabaseProvider antes de chamar Update(). A propriedade Connection deve ser definida — sem ela, Update() não tem fonte de dados para consultar.

Campos de Mesclagem Condicionais — NEXTIF e SKIPIF

FieldNextIf e FieldSkipIf implementam os campos NEXTIF e SKIPIF, expondo LeftExpression, ComparisonOperator e RightExpression para o teste condicional. Document.FieldOptions.ComparisonExpressionEvaluator (um IComparisonExpressionEvaluator) pode substituir a forma como essas expressões condicionais são avaliadas.

Dimensionamento de Campo de Mesclagem de Imagem

MergeFieldImageDimension representa uma largura ou altura para uma imagem inserida por meio de um campo de mesclagem de imagem, construída como new MergeFieldImageDimension(value) (em pontos) ou new MergeFieldImageDimension(value, unit) com um MergeFieldImageDimensionUnit explícito (Point ou Percent). Suas propriedades Value e Unit são graváveis.

O que está no escopo e o que não está

Document.MailMergeSettings retorna um MailMergeSettings objeto que modela a configuração de mala direta OOXML persiste dentro de um documento — DataSource, ConnectString, Query, MainDocumentType, DataType, Destination, CheckErrors, e as configurações do Office Data Source Object (ODSO) via OdsoFieldMapData/OdsoRecipientData coleções. Esta é a configuração data o documento contém, não uma conexão ao vivo: leitura e gravação MailMergeSettings não se conecta a um banco de dados, planilha ou lista de endereços, e esta edição não possui MailMerge classe de execução para executar uma mesclagem e gerar documentos de saída preenchidos a partir dela. O que esta edição oferece é a camada de nível de campo acima: reconhecer, ler, atualizar e modificar os próprios códigos de campo de mesclagem dentro de um único documento por meio do motor de avaliação de campos.

Dicas e Melhores Práticas

• Trate MailMergeSettings como metadados de documento que podem ser lidos e devolvidos, não como um API para conectar a dados externos — não há motor de execução por trás dele nesta edição.
• Sempre defina FieldDatabase.Connection antes de chamar Update() em um campo DATABASE, caso contrário a atualização não terá nada para consultar.
• Implemente IFieldDatabaseProvider uma única vez e atribua-o através de Document.FieldOptions.FieldDatabaseProvider para centralizar como todos os campos DATABASE de um documento resolvem seus dados.
• Use FieldMergeField.FieldName para ler a qual coluna da fonte de dados um MERGEFIELD está vinculado antes de decidir como processá-lo programaticamente.

Problemas comuns

FAQ

Posso executar uma mesclagem de correspondência em um CSV ou banco de dados nesta edição?

Não. Esta edição implementa os códigos de campo de mesclagem de correspondência e o modelo de dados de configuração MailMergeSettings, mas não há classe de execução MailMerge para conectar a uma fonte de dados externa e gerar documentos preenchidos.

O que eu realmente posso fazer com campos MERGEFIELD, então?

Você pode lê-los e modificá-los diretamente — FieldMergeField.FieldName para o nome da coluna vinculada, TextBefore/TextAfter para o texto literal ao redor, e Update()/Unlink()/Remove() como qualquer outro campo — dentro do documento atual.

O MailMergeSettings é inútil sem a execução da mesclagem?

Não — ele ainda é útil para ler ou percorrer a configuração de mala direta armazenada em um documento, como DataSource, Query ou MainDocumentType, embora esta edição não utilize essa configuração para executar uma mesclagem.

Como forneço dados para um campo DATABASE?

Implemente IFieldDatabaseProvider.GetQueryResult(fileName, connection, query, field) e atribua sua implementação a Document.FieldOptions.FieldDatabaseProvider antes de chamar Update().

Como controlo o tamanho de uma imagem inserida por um campo de mesclagem de imagem?

Use MergeFieldImageDimension, construído com um valor em pontos ou um valor mais um MergeFieldImageDimensionUnit explícito (Point ou Percent).

API Reference Resumo

Ver também

• Aspose.Words for .NET — Enterprise Documentation