Mail samenvoegen

Mail-samenvoeging

Deze gids toont hoe je kunt werken met mail-merge veldcodes en mail-merge configuratiegegevens in Aspose.Words FOSS voor .NET, en waar de grens met merge-uitvoering ligt. Aspose.Words FOSS voor .NET herkent en werkt de Word mail-merge veldcodes bij — ADDRESSBLOCK, DATABASE, GREETINGLINE, MERGEFIELD, NEXTIF, en SKIPIF — als onderdeel van zijn veld-evaluatie-engine, en kan de mail-merge configuratiegegevens (MailMergeSettings) bewaard binnen een document. Het uitvoeren van een daadwerkelijke merge tegen een externe gegevensbron om ingevulde uitvoerdocumenten te genereren — de MailMerge.Execute() workflow die bekend is van het commerciële product — is not geïmplementeerd in deze editie; geen MailMerge uitvoeringsklasse bestaat in het huidige API oppervlak.

MERGEFIELD — Lezen en wijzigen van merge-plaatsvervangers

FieldMergeField implementeert het MERGEFIELD-veld. FieldName en FieldNameNoPrefix geven de onderliggende kolomnaam van de gegevensbron terug waaraan het veld is gekoppeld, TextBefore/TextAfter bevatten letterlijke tekst die om de samengevoegde waarde wordt geplaatst, en IsMapped/IsVerticalFormatting rapporteren de merge-veld-mapping en lay-out-vlaggen. Zoals elk veldtype ondersteunt het GetFieldCode(), Update(), Unlink() en Remove().

ADDRESSBLOCK en GREETINGLINE

FieldAddressBlock implementeert het ADDRESSBLOCK-veld, met FormatAddressOnCountryOrRegion, IncludeCountryOrRegionName, ExcludedCountryOrRegionName, NameAndAddressFormat en LanguageId die bepalen hoe het adres van de ontvanger wordt opgemaakt. FieldGreetingLine implementeert GREETINGLINE, met AlternateText, NameFormat en LanguageId die de aanheftekst bepalen.

DATABASE-veld

FieldDatabase implementeert het DATABASE veld, waarbij de in het veld opgeslagen verbindingsdetails worden blootgesteld: Connection, FileName, Query, TableFormat, InsertHeadings, InsertOnceOnMailMerge, FirstRecord en LastRecord. Om queryresultaten te leveren wanneer dit veld wordt bijgewerkt, implementeer IFieldDatabaseProvider en de GetQueryResult(fileName, connection, query, field) methode, wijs het vervolgens toe aan Document.FieldOptions.FieldDatabaseProvider voordat Update() wordt aangeroepen. De eigenschap Connection moet worden ingesteld — zonder deze heeft Update() geen gegevensbron om te bevragen.

Conditionele samenvoegvelden — NEXTIF en SKIPIF

FieldNextIf en FieldSkipIf implementeren de NEXTIF en SKIPIF velden, die elk LeftExpression, ComparisonOperator en RightExpression blootstellen voor de conditionele test. Document.FieldOptions.ComparisonExpressionEvaluator (een IComparisonExpressionEvaluator) kan overschrijven hoe deze conditionele uitdrukkingen worden geëvalueerd.

Picture Merge Field-afmetingen

MergeFieldImageDimension vertegenwoordigt een breedte of hoogte voor een afbeelding die via een picture merge field wordt ingevoegd, geconstrueerd als new MergeFieldImageDimension(value) (in punten) of new MergeFieldImageDimension(value, unit) met een expliciete MergeFieldImageDimensionUnit (Point of Percent). Zijn Value en Unit eigenschappen zijn beide schrijfbaar.

Wat binnen de scope valt, en wat niet

Document.MailMergeSettings keert een MailMergeSettings object dat de mail-merge configuratie modelleert, OOXML blijft behouden binnen een document — DataSource, ConnectString, Query, MainDocumentType, DataType, Destination, CheckErrors, en de Office Data Source Object (ODSO) instellingen via OdsoFieldMapData/OdsoRecipientData collecties. Dit is configuratie data die het document draagt, geen live verbinding: lezen en schrijven MailMergeSettings maakt geen verbinding met een database, spreadsheet of adreslijst, en deze editie heeft geen MailMerge uitvoeringsklasse om een samenvoeging uit te voeren en gevulde outputdocumenten te produceren. Wat deze editie wel ondersteunt is de veld-niveau laag erboven: het herkennen, lezen, bijwerken en wijzigen van de samenvoegingsveld-codes zelf binnen één document via de veld-evaluatie-engine.

Tips en best practices

• Behandel MailMergeSettings als documentmetadata die u kunt lezen en round-tripten, niet als een API voor het verbinden met externe gegevens — er zit geen uitvoeringsengine achter in deze editie.
• Stel FieldDatabase.Connection altijd in voordat u Update() aanroept op een DATABASE-veld, anders heeft de update niets om te queryen.
• Implementeer IFieldDatabaseProvider één keer en wijs het toe via Document.FieldOptions.FieldDatabaseProvider om te centraliseren hoe alle DATABASE-velden in een document hun gegevens oplossen.
• Gebruik FieldMergeField.FieldName om te lezen aan welke data-source-kolom een MERGEFIELD is gekoppeld voordat u beslist hoe u deze programmatisch verwerkt.

Veelvoorkomende problemen

FAQ

Kan ik in deze editie een mail-merge uitvoeren op een CSV of database?

Nee. Deze editie implementeert de mail-merge veldcodes en het MailMergeSettings configuratiemodel, maar er is geen MailMerge uitvoeringsklasse om verbinding te maken met een externe gegevensbron en ingevulde documenten te genereren.

Wat kan ik eigenlijk doen met MERGEFIELD-velden, dan?

Je kunt ze direct lezen en aanpassen — FieldMergeField.FieldName voor de gekoppelde kolomnaam, TextBefore/TextAfter voor omringende letterlijke tekst, en Update()/Unlink()/Remove() zoals elk ander veld — binnen het huidige document.

Is MailMergeSettings nutteloos zonder merge-uitvoering?

Nee — het is nog steeds nuttig voor het lezen of round-tripping van de opgeslagen mail-merge-configuratie van een document, zoals DataSource, Query of MainDocumentType, ook al voert deze editie die configuratie niet uit om een merge te starten.

Hoe lever ik data voor een DATABASE-veld?

Implementeer IFieldDatabaseProvider.GetQueryResult(fileName, connection, query, field) en wijs je implementatie toe aan Document.FieldOptions.FieldDatabaseProvider voordat je Update() aanroept.

Hoe regel ik de grootte van een afbeelding die door een picture-merge-veld wordt ingevoegd?

Gebruik MergeFieldImageDimension, opgebouwd met een puntwaarde of een waarde plus een expliciete MergeFieldImageDimensionUnit (Point of Percent).

API Reference Samenvatting

Zie ook

• Aspose.Words for .NET — Enterprise Documentation