ادغام نامه

ادغام نامه

این راهنما نشان می‌دهد که چگونه با کدهای فیلد ادغام‌نامه و داده‌های پیکربندی ادغام‌نامه در Aspose.Words FOSS برای .NET کار کنیم و مرز اجرای ادغام کجاست. Aspose.Words FOSS برای .NET کدهای فیلد ادغام‌نامه ورد را شناسایی و به‌روز می‌کند — ADDRESSBLOCK, DATABASE, GREETINGLINE, MERGEFIELD, NEXTIF, و SKIPIF — به عنوان بخشی از موتور ارزیابی فیلد آن، و می‌تواند داده‌های پیکربندی ادغام‌نامه را بخواند (MailMergeSettings) که در یک سند ذخیره شده‌اند. اجرای یک ادغام واقعی در مقابل منبع داده خارجی برای تولید اسناد خروجی پر شده — MailMerge.Execute() جریان کاری شناخته‌شده از محصول تجاری — است not در این نسخه پیاده‌سازی شده است؛ هیچ MailMerge کلاس اجرایی در سطح فعلی API وجود ندارد.

MERGEFIELD — خواندن و اصلاح متغیرهای ادغام

FieldMergeField فیلد MERGEFIELD را پیاده‌سازی می‌کند. FieldName و FieldNameNoPrefix نام ستون منبع داده‌ای که فیلد به آن متصل است را برمی‌گردانند، TextBefore/TextAfter متن ثابت دور مقدار ادغام‌شده را نگه می‌دارند، و IsMapped/IsVerticalFormatting نگاشت فیلد ادغام و پرچم‌های چیدمان را گزارش می‌دهند. مانند هر نوع فیلد، از GetFieldCode()، Update()، Unlink() و Remove() پشتیبانی می‌کند.

ADDRESSBLOCK و GREETINGLINE

FieldAddressBlock فیلد ADDRESSBLOCK را پیاده‌سازی می‌کند، به‌طوری که FormatAddressOnCountryOrRegion، IncludeCountryOrRegionName، ExcludedCountryOrRegionName، NameAndAddressFormat و LanguageId قالب‌بندی نشانی گیرنده را کنترل می‌کنند. FieldGreetingLine GREETINGLINE را پیاده‌سازی می‌کند، به‌طوری که AlternateText، NameFormat و LanguageId متن سلام را تنظیم می‌کنند.

فیلد DATABASE

FieldDatabase فیلد DATABASE را پیاده‌سازی می‌کند و جزئیات اتصال ذخیره‌شده در فیلد: Connection، FileName، Query، TableFormat، InsertHeadings، InsertOnceOnMailMerge، FirstRecord و LastRecord را در دسترس می‌گذارد. برای تأمین نتایج کوئری هنگام به‌روزرسانی این فیلد، IFieldDatabaseProvider و متد GetQueryResult(fileName, connection, query, field) آن را پیاده‌سازی کنید، سپس قبل از فراخوانی Update()، آن را به Document.FieldOptions.FieldDatabaseProvider اختصاص دهید. ویژگی Connection باید تنظیم شود — بدون آن، Update() منبع داده‌ای برای کوئری ندارد.

فیلدهای ترکیبی شرطی — NEXTIF و SKIPIF

FieldNextIf و FieldSkipIf فیلدهای NEXTIF و SKIPIF را پیاده‌سازی می‌کنند، که هر کدام LeftExpression، ComparisonOperator و RightExpression را برای آزمون شرطی در دسترس می‌گذارند. Document.FieldOptions.ComparisonExpressionEvaluator (یک IComparisonExpressionEvaluator) می‌تواند نحوه ارزیابی این عبارات شرطی را بازنویسی کند.

اندازه‌گذاری فیلد ترکیبی تصویر

MergeFieldImageDimension نمایانگر عرض یا ارتفاع یک تصویر که از طریق فیلد ترکیبی تصویر وارد می‌شود، به صورت new MergeFieldImageDimension(value) (به نقطه) یا new MergeFieldImageDimension(value, unit) با یک MergeFieldImageDimensionUnit صریح (Point یا Percent) ساخته می‌شود. ویژگی‌های Value و Unit آن هر دو قابل نوشتن هستند.

چه چیزهایی در حوزهٔ کار هستند و چه چیزهایی نیستند

Document.MailMergeSettings یک مقدار برمی‌گرداند a MailMergeSettings شیئی که پیکربندی ادغام پست را مدل می‌کند، OOXML درون یک سند نگهداری می‌شود — DataSource, ConnectString, Query, MainDocumentType, DataType, Destination, CheckErrors، و تنظیمات شیء منبع دادهٔ Office (ODSO) از طریق OdsoFieldMapData/OdsoRecipientData مجموعه‌ها. این یک پیکربندی است data که سند حمل می‌کند، نه یک اتصال زنده: خواندن و نوشتن MailMergeSettings به پایگاه داده، صفحه‌گسترده یا فهرست آدرس متصل نمی‌شود، و این نسخه هیچ MailMerge کلاس اجرایی برای اجرای ادغام و تولید اسناد خروجی پرشده از آن ندارد. آنچه این نسخه پشتیبانی می‌کند لایهٔ سطح فیلد است: شناسایی، خواندن، به‌روزرسانی و تغییر کدهای فیلد ادغام خودشان در یک سند واحد از طریق موتور ارزیابی فیلد.

نکات و بهترین شیوه‌ها

• به MailMergeSettings به‌عنوان فرادادهٔ سند که می‌توانید بخوانید و round-trip استفاده کنید نگاه کنید، نه به‌عنوان API برای اتصال به داده‌های خارجی — در این نسخه هیچ موتور اجرایی پشت آن وجود ندارد.
• همیشه قبل از فراخوانی Update() بر روی فیلد DATABASE، FieldDatabase.Connection را تنظیم کنید، در غیر این صورت به‌روزرسانی هیچ چیزی برای پرس‌وجو ندارد.
• یک‌بار IFieldDatabaseProvider را پیاده‌سازی کنید و از طریق Document.FieldOptions.FieldDatabaseProvider به آن اختصاص دهید تا نحوهٔ حل داده‌های تمام فیلدهای DATABASE در یک سند متمرکز شود.
• از FieldMergeField.FieldName استفاده کنید تا ستونی از منبع داده‌ای که MERGEFIELD به آن متصل است را بخوانید، پیش از این که تصمیم بگیرید چگونه به‌صورت برنامه‌نویسی پردازش شود.

مشکلات رایج

FAQ

آیا می‌توانم در این نسخه ادغام نامه (mail merge) را نسبت به یک فایل CSV یا پایگاه داده اجرا کنم؟

خیر. این نسخه کدهای فیلد mail-merge و مدل دادهٔ پیکربندی MailMergeSettings را پیاده‌سازی می‌کند، اما هیچ کلاس اجرایی MailMerge برای اتصال به منبع دادهٔ خارجی و تولید اسناد پرشده وجود ندارد.

در واقع با فیلدهای MERGEFIELD چه کاری می‌توانم انجام دهم؟

می‌توانید آن‌ها را به‌صورت مستقیم بخوانید و تغییر دهید — FieldMergeField.FieldName برای نام ستون مرتبط، TextBefore/TextAfter برای متن ثابت اطراف، و Update()/Unlink()/Remove() همانند هر فیلد دیگری — در سند جاری.

آیا MailMergeSettings بدون اجرای ادغام بی‌فایده است؟

نه — همچنان برای خواندن یا عبور دورانی پیکربندی ادغام‌نامه ذخیره شدهٔ سند مفید است، مانند DataSource، Query یا MainDocumentType، حتی اگر این نسخه بر آن پیکربندی برای اجرای ادغام کاری نکند.

چگونه می‌توانم داده‌ها را برای فیلد DATABASE فراهم کنم؟

IFieldDatabaseProvider.GetQueryResult(fileName, connection, query, field) را پیاده‌سازی کنید و پیاده‌سازی خود را به Document.FieldOptions.FieldDatabaseProvider اختصاص دهید قبل از فراخوانی Update().

چگونه می‌توانم اندازهٔ تصویری که توسط فیلد ادغام تصویر درج می‌شود را کنترل کنم؟

از MergeFieldImageDimension استفاده کنید، که با یک مقدار نقطه‌ای یا مقدار به‌همراه یک MergeFieldImageDimensionUnit صریح (Point یا Percent) ساخته می‌شود.

API Reference خلاصه

همچنین ببینید:

• Aspose.Words for .NET — Enterprise Documentation