نحوه کار با فیلدها در .NET
این راهنما نشان می‌دهد چگونه با فیلدهای Word — DATE، IF، REF، DATABASE و ده‌ها مورد دیگر — در Aspose.Words FOSS برای .NET کار کنید: افزودن یک فیلد و خواندن نتیجهٔ آن، به‌روزرسانی فیلدها پس از ویرایش برنامه‌ای، پیکربندی رفتار به‌روزرسانی، ردیابی به‌روزرسانی‌ها با یک کال‌بک، و تبدیل یا حذف یک فیلد. Aspose.Words FOSS برای .NET از طریق NuGet یا با ساخت از منبع در دسترس است.
راهنمای گام به گام
مرحله ۱: دریافت کتابخانه
مخزن را کلون کنید و بسازید Aspose.Words.sln در پیکربندی Release، سپس یک ارجاع پروژه به Aspose.Words.csproj از پروژه .NET خود، همان‌طور که در راهنمای نصب. اضافه کنید using Aspose.Words; and using Aspose.Words.Fields; در بالای هر فایلی که با فیلدها کار می‌کند.
مرحله ۲: افزودن یک فیلد و خواندن نتیجهٔ آن
DocumentBuilder.InsertField() یک فیلد جدید را در مکان‌نمای (کرسر) وارد می‌کند، با overloadهایی که یا نتیجهٔ فیلد را بلافاصله به‌روزرسانی می‌کنند یا برای یک عبور به‌روزرسانی بعدی نگه می‌دارند. هر فیلد یک نمونهٔ Field است که از سه گرهٔ marker — FieldStart، Separator و FieldEnd — تشکیل شده و به صورت Field.Start / Field.Separator / Field.End در دسترس است. Field.Type تعیین می‌کند که کدام FieldType را نمایندگی می‌کند، Field.Result و Field.DisplayResult مقدار محاسبه‌شدهٔ اخیر را نگه می‌دارند، Field.Format هر سوئیچ قالبی پیوست‌شده به کد را نگه می‌دارد، و Field.GetFieldCode() متن خام کد فیلد را برمی‌گرداند.
مرحله ۳: به‌روزرسانی فیلدها پس از ویرایش برنامه‌نویسی‌شده
Aspose.Words FOSS هنگام بارگذاری یا ذخیره‌سازی سند فیلدها را مجدداً محاسبه نمی‌کند. پس از ویرایشی که باید نتیجهٔ یک فیلد را تغییر دهد، Range.UpdateFields() را فراخوانی کنید تا هر فیلد در آن بازه دوباره محاسبه شود — برای کل سند از Document.Range.UpdateFields() استفاده کنید — یا برای یک فیلد واحد از Field.Update() استفاده کنید. Range.UnlinkFields() تمام فیلدهای بازه را در یک فراخوانی به متن ثابت تبدیل می‌کند، و Range.NormalizeFieldTypes() کد نوع ذخیره‌شدهٔ فیلد را پس از ویرایش دستی با کد فیلد واقعی تطبیق می‌دهد.
مرحله ۴: پیکربندی رفتار به‌روزرسانی فیلدها با FieldOptions
Document.FieldOptions (یک نمونهٔ FieldOptions) نحوهٔ رفتار فیلدهای کل سند را هنگام به‌روزرسانی تعیین می‌کند: CurrentUser (یک نمونهٔ UserInformation — Name, Initials, Address) هویت را که فیلدهای مرتبط با نام نویسنده و کاربر از آن می‌خوانند فراهم می‌کند، DefaultDocumentAuthor نتایج مرتبط با نویسنده را بذر می‌گذارد، و LegacyNumberFormat / UseInvariantCultureNumberFormat / PreProcessCulture / FieldUpdateCultureSource قالب‌بندی عدد و تاریخ را کنترل می‌کنند. برای خطوط لولهٔ بدون نظارت، FieldOptions.UserPromptRespondent (یک IFieldUserPromptRespondent) را اختصاص دهید تا فیلدهای مبتنی بر درخواست مانند ASK و FILLIN منتظر ورودی تعاملی مسدود نشوند، و یک IFieldDatabaseProvider سفارشی را به FieldOptions.FieldDatabaseProvider اختصاص دهید تا ردیف‌های فیلد DATABASE را از منبع دادهٔ خودتان به جای اتصال به پایگاه دادهٔ واقعی تأمین کند.
مرحله ۵: ردیابی به‌روزرسانی فیلدها با یک callback
IFieldUpdatingCallback (FieldUpdating و FieldUpdated) را پیاده‌سازی کنید و آن را به FieldOptions اختصاص دهید تا کد را بلافاصله پیش و پس از هر بار محاسبه مجدد فیلد اجرا کند — که برای حسابرسی دقیق اینکه کدام فیلدها در یک کار دسته‌ای تغییر کرده‌اند مفید است. برای گزارش پیشرفت در یک سند بزرگ، IFieldUpdatingProgressCallback (Notify) را پیاده‌سازی کنید، که یک FieldUpdatingProgressArgs دریافت می‌کند که TotalFieldsCount، UpdatedFieldsCount و UpdateCompleted را نمایان می‌سازد.
مرحله ۶: تبدیل یا حذف یک فیلد
Field.Unlink() فیلد را با آخرین نتیجهٔ محاسبه‌شده‌اش به‌عنوان متن ثابت عادی جایگزین می‌کند و کد زیرین فیلد را نادیده می‌گیرد — از آن استفاده کنید وقتی می‌خواهید مقدار به‌صورت دائمی در سند تعبیه شود. Field.Remove() گره‌های FieldStart، Separator و FieldEnd را همراه با کد و نتیجهٔ فیلد حذف می‌کند و فیلد را کاملاً از بین می‌برد. ترجیحاً از این دو روش به‌جای حذف مستقیم گره‌های علامت‌گذاری استفاده کنید، زیرا حذف دستی تنها بخشی از ساختار فیلد می‌تواند درخت سند را ناسازگار باقی بگذارد.
مشکلات رایج و راه‌حل‌ها
نتیجهٔ نمایش داده شدهٔ فیلد پس از ویرایش سند منسوخ می‌شود. Aspose.Words FOSS هنگام بارگذاری یا ذخیره‌سازی فیلدها به‌صورت خودکار به‌روز نمی‌کند. Call Range.UpdateFields() or Field.Update() به‌طور صریح پس از ویرایش.
PAGE, NUMPAGES, یا شماره صفحه فهرست مطالب همیشه نمایش داده می‌شود 0. چیدمان/رندر صفحه بخشی از این نسخه نیست، بنابراین فیلدهایی که نتیجه آن‌ها به صفحه‌بندی بستگی دارد به یک جایگزین ارزیابی می‌شوند 0. این رفتار مورد انتظار در این نسخه است.
به‌نظر می‌رسد به‌روزرسانی دسته‌ای فیلد متوقف شده است. یک فیلد مبتنی بر پرسش (ASK, FILLIN) هیچ IFieldUserPromptRespondent تخصیص داده نشده است. تخصیص بدهید FieldOptions.UserPromptRespondent, یا تنظیم کنید DefaultResponse روی نمونهٔ تک‌تک فیلد.
این DATABASE فیلد ردیفی تولید نمی‌کند. نه IFieldDatabaseProvider به اختصاص داده می‌شود FieldOptions.FieldDatabaseProvider. رابط را پیاده‌سازی کنید و قبل از فراخوانی آن را اختصاص دهید Range.UpdateFields().
سوالات متداول
آیا Aspose.Words FOSS تمام انواع فیلدهای Word را ارزیابی می‌کند؟
مدل شیء Field هر مقدار FieldType را نمایان می‌کند و اکثر آن‌ها را به‌روز می‌سازد، اما فیلدهایی که نتیجه آن‌ها به چیدمان صفحه بستگی دارد — مانند PAGE و NUMPAGES — به یک 0 جایگزین می‌شوند زیرا این نسخه شامل موتور چیدمان/رندرینگ نیست.
چگونه می‌توانم فیلدها را پس از یک ویرایش برنامه‌نویسی مجدداً ارزیابی کنم؟
متد Range.UpdateFields() را بر روی محدوده‌ای که محتوای ویرایش‌شده را شامل می‌شود فراخوانی کنید، یا برای کل سند Document.Range.UpdateFields() را استفاده کنید.
آیا می‌توانم یک فیلد را به متن ساده و ثابت تبدیل کنم؟
بله — Field.Unlink() فیلد را با آخرین نتیجه محاسبه‌شده آن به عنوان متن عادی جایگزین می‌کند.
چگونه می‌توانم یک فیلد را به‌طور کامل حذف کنم، همراه با نتیجه آن؟
متد Field.Remove() را فراخوانی کنید. این متد گره‌های FieldStart، Separator و FieldEnd را به همراه کد فیلد و محتوای نتیجه آن حذف می‌کند.
چگونه می‌توانم داده‌های سفارشی را به فیلد DATABASE ارائه دهم؟
پیاده‌سازی IFieldDatabaseProvider و اختصاص آن به Document.FieldOptions.FieldDatabaseProvider. پیاده‌سازی GetQueryResult() آن یک FieldDatabaseDataTable بر پایهٔ نمونه‌های FieldDatabaseDataRow برمی‌گرداند.
