Mail Merge

Penggabungan Surat

Panduan ini menunjukkan cara bekerja dengan kode bidang mail-merge dan data konfigurasi mail-merge di Aspose.Words FOSS untuk .NET, serta di mana batas dengan eksekusi merge berada. Aspose.Words FOSS untuk .NET mengenali dan memperbarui kode bidang Word mail-merge — ADDRESSBLOCK, DATABASE, GREETINGLINE, MERGEFIELD, NEXTIF, dan SKIPIF — sebagai bagian dari mesin evaluasi bidangnya, dan dapat membaca data konfigurasi mail-merge (MailMergeSettings) yang dipertahankan di dalam dokumen. Menjalankan merge aktual terhadap sumber data eksternal untuk menghasilkan dokumen output yang terisi — proses MailMerge.Execute() alur kerja yang dikenal dari produk komersial — adalah not diimplementasikan dalam edisi ini; tidak ada MailMerge kelas eksekusi yang ada di permukaan API saat ini.

MERGEFIELD — Membaca dan Memodifikasi Placeholder Merge

FieldMergeField mengimplementasikan bidang MERGEFIELD. FieldName dan FieldNameNoPrefix mengembalikan nama kolom sumber data yang menjadi dasar bidang tersebut, TextBefore/TextAfter menyimpan teks literal yang membungkus nilai yang digabung, dan IsMapped/IsVerticalFormatting melaporkan pemetaan bidang merge dan flag tata letak. Seperti setiap tipe bidang, ia mendukung GetFieldCode(), Update(), Unlink(), dan Remove().

ADDRESSBLOCK dan GREETINGLINE

FieldAddressBlock mengimplementasikan bidang ADDRESSBLOCK, dengan FormatAddressOnCountryOrRegion, IncludeCountryOrRegionName, ExcludedCountryOrRegionName, NameAndAddressFormat, dan LanguageId mengendalikan cara format alamat penerima. FieldGreetingLine mengimplementasikan GREETINGLINE, dengan AlternateText, NameFormat, dan LanguageId mengendalikan teks salam.

Field DATABASE

FieldDatabase mengimplementasikan field DATABASE, mengekspos detail koneksi yang disimpan dalam field: Connection, FileName, Query, TableFormat, InsertHeadings, InsertOnceOnMailMerge, FirstRecord, dan LastRecord. Untuk menyediakan hasil kueri saat field ini diperbarui, implementasikan IFieldDatabaseProvider dan metode GetQueryResult(fileName, connection, query, field)-nya, lalu tetapkan ke Document.FieldOptions.FieldDatabaseProvider sebelum memanggil Update(). Properti Connection harus disetel — tanpa itu, Update() tidak memiliki sumber data untuk kueri.

Bidang Gabungan Bersyarat — NEXTIF dan SKIPIF

FieldNextIf dan FieldSkipIf mengimplementasikan field NEXTIF dan SKIPIF, masing-masing mengekspos LeftExpression, ComparisonOperator, dan RightExpression untuk tes bersyarat. Document.FieldOptions.ComparisonExpressionEvaluator (sebuah IComparisonExpressionEvaluator) dapat mengganti cara ekspresi bersyarat ini dievaluasi.

Pengukuran Bidang Gabungan Gambar

MergeFieldImageDimension mewakili lebar atau tinggi untuk gambar yang disisipkan melalui bidang gabungan gambar, dibangun sebagai new MergeFieldImageDimension(value) (dalam point) atau new MergeFieldImageDimension(value, unit) dengan MergeFieldImageDimensionUnit eksplisit (Point atau Percent). Properti Value dan Unit dapat ditulis.

Apa yang Termasuk dalam Lingkup, dan Apa yang Tidak

Document.MailMergeSettings mengembalikan sebuah MailMergeSettings objek yang memodelkan konfigurasi mail-merge OOXML tetap berada di dalam dokumen — DataSource, ConnectString, Query, MainDocumentType, DataType, Destination, CheckErrors, dan pengaturan Office Data Source Object (ODSO) melalui OdsoFieldMapData/OdsoRecipientData koleksi. Ini adalah konfigurasi data yang dibawa dokumen, bukan koneksi langsung: membaca dan menulis MailMergeSettings tidak terhubung ke basis data, lembar kerja, atau daftar alamat, dan edisi ini tidak memiliki MailMerge kelas eksekusi untuk menjalankan merge dan menghasilkan dokumen output yang terisi darinya. Apa yang didukung oleh edisi ini adalah lapisan tingkat bidang di atasnya: mengenali, membaca, memperbarui, dan memodifikasi kode bidang merge itu sendiri dalam satu dokumen melalui mesin evaluasi bidang.

Tips dan Praktik Terbaik

• Anggap MailMergeSettings sebagai metadata dokumen yang dapat Anda baca dan lakukan round-trip, bukan sebagai API untuk menghubungkan ke data eksternal — tidak ada mesin eksekusi di belakangnya dalam edisi ini.
• Selalu setel FieldDatabase.Connection sebelum memanggil Update() pada bidang DATABASE, atau pembaruan tidak memiliki apa pun untuk kueri.
• Terapkan IFieldDatabaseProvider sekali dan tetapkan melalui Document.FieldOptions.FieldDatabaseProvider untuk memusatkan cara semua bidang DATABASE dalam dokumen menyelesaikan data mereka.
• Gunakan FieldMergeField.FieldName untuk membaca kolom sumber data mana yang terikat pada MERGEFIELD sebelum memutuskan cara memprosesnya secara programatis.

Masalah Umum

FAQ

Apakah saya dapat menjalankan mail merge terhadap CSV atau basis data dalam edisi ini?

Tidak. Edisi ini mengimplementasikan kode bidang mail-merge dan model data konfigurasi MailMergeSettings, tetapi tidak ada kelas eksekusi MailMerge untuk menghubungkan ke sumber data eksternal dan menghasilkan dokumen yang terisi.

Apa yang sebenarnya bisa saya lakukan dengan field MERGEFIELD, lalu?

Anda dapat membaca dan memodifikasinya secara langsung — FieldMergeField.FieldName untuk nama kolom yang terikat, TextBefore/TextAfter untuk teks literal di sekelilingnya, dan Update()/Unlink()/Remove() seperti field lainnya — dalam dokumen saat ini.

Apakah MailMergeSettings tidak berguna tanpa eksekusi merge?

Tidak — tetap berguna untuk membaca atau melakukan round-tripping pada konfigurasi mail-merge yang disimpan dalam dokumen, seperti DataSource, Query, atau MainDocumentType, meskipun edisi ini tidak menggunakan konfigurasi tersebut untuk menjalankan merge.

Bagaimana cara saya menyediakan data untuk field DATABASE?

Implementasikan IFieldDatabaseProvider.GetQueryResult(fileName, connection, query, field) dan tetapkan implementasi Anda ke Document.FieldOptions.FieldDatabaseProvider sebelum memanggil Update().

Bagaimana saya mengontrol ukuran gambar yang disisipkan oleh field picture merge?

Gunakan MergeFieldImageDimension, yang dibangun dengan nilai poin atau nilai ditambah MergeFieldImageDimensionUnit eksplisit (Point atau Percent).

API Reference Ringkasan

Lihat Juga

• Aspose.Words for .NET — Enterprise Documentation