کار با فیلدها

بررسی کلی

یک فیلد Word – DATE, IF, DATABASE, REF، و ده‌ها مورد دیگر – در Aspose.Words FOSS برای .NET توسط Field کلاس و زیرکلاس‌های آن، همه در Aspose.Words.Fields فضای نام. این صفحه هسته موتور فیلد را پوشش می‌دهد: Field مدل شیء خود، چگونگی جمع‌آوری و به‌روزرسانی فیلدها، و رابط‌های بازگشتی که به شما امکان می‌دهند داده‌ها و رفتارهای سفارشی را هنگام به‌روزرسانی فیلد وارد کنید. خانواده‌های خاص فیلدها – پیوندهای فراگیر و ارجاعات متقابل، فیلدهای تاریخ/زمان، فیلدهای ادغام پست، فیلدهای فهرست و فهرست مطالب – هر یک صفحه راهنمای توسعه‌دهنده مختص خود را دارند.


مدل شیء فیلد

هر فیلد در یک سند یک نمونه Field است که از سه گره علامت‌گذاری – FieldStart، Separator و FieldEnd – تشکیل شده و به عنوان ویژگی‌های Field.Start، Field.Separator و Field.End در دسترس است. Field.Type تعیین می‌کند که فیلد کدام FieldType را نمایندگی می‌کند، Field.Result و Field.DisplayResult مقدار محاسبه‌شده‌ی آخرین را نشان می‌دهند، و Field.Format هر سوئیچ (مانند رشته‌های قالب عددی یا تاریخ-زمان) پیوست‌شده به کد فیلد را نگه می‌دارد. Field.IsLocked و Field.IsDirty وضعیت قفل‌شده و منقضی فیلد را گزارش می‌کنند. برای خواندن متن خام کد فیلد، Field.GetFieldCode() را فراخوانی کنید، برای محاسبه مجدد نتیجه، Field.Update() را، برای جایگزینی فیلد با متن ثابت، Field.Unlink() را و برای حذف کامل آن، Field.Remove() را اجرا کنید.


دسترسی و به‌روزرسانی فیلدها در یک سند

Document.Range.Fields یک FieldCollection را برمی‌گرداند – فیلدهای موجود در آن بازه، با Count، Remove()، RemoveAt() و Clear() برای حذف دسته‌جمعی. Range.UpdateFields() تمام فیلدهای بازه را دوباره محاسبه می‌کند، Range.UnlinkFields() تمام فیلدهای بازه را به متن ثابت تبدیل می‌کند، و Range.NormalizeFieldTypes() کد نوع ذخیره‌شده‌ی فیلد را با کد فیلد واقعی پس از ویرایش‌های دستی مطابقت می‌دهد. DocumentBuilder.InsertField() یک فیلد جدید را در مکان‌نما وارد می‌کند، با بارگذاری‌های اضافی که یا نتیجه فیلد جدید را بلافلافی به‌روز می‌کند یا برای یک عبور Range.UpdateFields() بعدی باقی می‌گذارد.


گزینه‌های به‌روزرسانی فیلد و فرهنگ

Document.FieldOptions یک نمونه FieldOptions است که نحوه رفتار فیلدهای کل سند را هنگام به‌روزرسانی تعیین می‌کند: CurrentUser مقدار UserInformation مورد استفاده توسط فیلدهای هویت را فراهم می‌کند، DefaultDocumentAuthor نتایج مرتبط با نویسنده را بذر می‌گذارد، LegacyNumberFormat و UseInvariantCultureNumberFormat قالب‌بندی عدد را کنترل می‌کنند، و PreProcessCulture و FieldUpdateCultureSource (به‌همراه فراخوانی IFieldUpdateCultureProvider) تعیین می‌کنند که کدام فرهنگ قالب‌بندی تاریخ و عدد را در طول به‌روزرسانی اداره می‌کند. TemplateName، FileName و BuiltInTemplatesPaths مقادیری را فراهم می‌کنند که فیلدهای آگاه به قالب و نام-فایل می‌خوانند.


ردیابی و سفارشی‌سازی به‌روزرسانی‌های فیلد

اجرای IFieldUpdatingCallback (FieldUpdating و FieldUpdated) بر روی FieldOptions برای اجرای کد بلافاصله قبل و بعد از هر بار محاسبه دوباره فیلد — مفید برای حسابرسی اینکه کدام فیلدها در یک کار دسته‌ای تغییر کرده‌اند. اجرای IFieldUpdatingProgressCallback (Notify) برای ردیابی پیشرفت کلی در یک سند بزرگ؛ این یک FieldUpdatingProgressArgs دریافت می‌کند که شامل TotalFieldsCount، UpdatedFieldsCount و UpdateCompleted است. برای تغییر نحوه رندر شدن عددی یا عمومی نتیجه یک فیلد به عنوان متن، IFieldResultFormatter (Format(value, format) و FormatNumeric(value, format)) را پیاده‌سازی کنید و آن را به FieldOptions.ResultFormatter اختصاص دهید.


تأمین داده‌های خارجی برای فیلدها

فیلد DATABASE ردیف‌های خود را از طریق IFieldDatabaseProvider.GetQueryResult() می‌خواند، که یک FieldDatabaseDataTable (ColumnNames، Rows) ساخته‌شده از نمونه‌های FieldDatabaseDataRow (Values) را برمی‌گرداند — پیاده‌سازی خود را به FieldOptions.FieldDatabaseProvider اختصاص دهید. فیلدهای مقایسه‌ای مانند IF شرط خود را از طریق IComparisonExpressionEvaluator.Evaluate() ارزیابی می‌کنند، که یک ComparisonExpression (LeftExpression، ComparisonOperator، RightExpression) دریافت می‌کند و یک ComparisonEvaluationResult (Result، ErrorMessage) برمی‌گرداند؛ یک ارزیاب سفارشی را به FieldOptions.ComparisonExpressionEvaluator اختصاص دهید تا منطق پیش‌فرض مقایسه را بازنویسی کنید. فیلدهایی که به‌طور معمول هنگام به‌روزرسانی کاربر را برای ورودی درخواست می‌کنند — مانند ASK و FILLIN — هنگام اختصاص یک مورد به FieldOptions.UserPromptRespondent، IFieldUserPromptRespondent.Respond() را فرا می‌خوانند، تا به‌روزرسانی بدون نظارت مسدود نشود و منتظر ورودی تعاملی نماند.


هویت کاربر و سند برای فیلدها

UserInformation (Name، Initials، Address، و UserInformation.DefaultUser ثابت) هویت را فراهم می‌کند که فیلدهای مرتبط با نام نویسنده و کاربر از آن می‌خوانند. یک نمونه را به Document.FieldOptions.CurrentUser اختصاص دهید قبل از به‌روزرسانی فیلدهایی که به نویسنده سند یا هویت کاربر وابسته‌اند.


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

  • Aspose.Words FOSS فیلدها را به‌صورت خودکار هنگام بارگذاری یا ذخیره‌سازی همانند ورد محاسبه نمی‌کند – پس از هر ویرایش برنامه‌نویسی که باید در نتایج فیلد منعکس شود، Range.UpdateFields() (یا Field.Update() برای یک فیلد) را به‌صورت صریح فراخوانی کنید.
  • FieldStart، Separator و FieldEnd گره‌های واقعی در درخت سند هستند؛ برای حذف یک فیلد از طریق Field.Remove() یا Field.Unlink() استفاده کنید نه اینکه گره‌های نشانگر را مستقیماً حذف کنید، در غیر این صورت ساختار فیلد ممکن است ناسازگار شود.
  • فیلدهایی که نتیجه‌شان به چیدمان صفحه وابسته است – PAGE، NUMPAGES و ورودی‌های شماره صفحه فهرست مطالب (TOC) – به یک جایگزین 0 ارزیابی می‌شوند، زیرا این نسخه شامل موتور چیدمان/رندر صفحه نیست.
  • قبل از اجرای Range.UpdateFields() روی سندی بزرگ یا ناآشنا، IFieldUpdatingCallback را ثبت کنید اگر نیاز دارید دقیقاً کدام فیلدها تغییر کرده‌اند را ثبت یا بررسی کنید.
  • قبل از به‌روزرسانی سند در یک خط لوله بدون نظارت، FieldOptions.UserPromptRespondent را تنظیم کنید (یا مقادیر DefaultResponse را برای کلاس‌های فیلد مبتنی بر پرسش‌های تک‌تک فراهم کنید) تا فیلدهای ASK/FILLIN منتظر ورودی تعاملی گیر نکنند.

مسائل رایج

مسئلهدلیلرفع
نتیجه فیلد پس از ویرایش سند به‌روز نیستAspose.Words FOSS فیلدها را هنگام بارگذاری یا ذخیره به‌صورت خودکار به‌روزرسانی نمی‌کندبه‌صورت صریح Range.UpdateFields() یا Field.Update() را فراخوانی کنید
PAGE، NUMPAGES یا شماره‌های صفحه TOC 0 نشان می‌دهندچیدمان/رندر صفحه بخشی از این نسخه نیسترفتار مورد انتظار – از نسخه تجاری استفاده کنید Aspose.Words برای .NET اگر به شماره‌صفحات محاسبه‌شده نیاز دارید
فیلد DATABASE هیچ ردیفی تولید نمی‌کندهیچ IFieldDatabaseProviderی به FieldOptions.FieldDatabaseProvider اختصاص داده نشده استپیاده‌سازی IFieldDatabaseProvider و اختصاص آن پیش از فراخوانی Range.UpdateFields()
به‌نظر می‌رسد به‌روزرسانی دسته‌ای فیلد گیر کرده استیک فیلد مبتنی بر درخواست (ASK، FILLIN) هیچ IFieldUserPromptRespondentی اختصاص یافته نداردمقدار FieldOptions.UserPromptRespondent را اختصاص دهید، یا DefaultResponse را در نمونه فیلد تنظیم کنید

FAQ

آیا Aspose.Words FOSS همه انواع فیلدهای ورد را ارزیابی می‌کند؟

مدل شیء 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 برمی‌گرداند.


API Reference خلاصه

کلاس / اینترفیستوضیح
Fieldکلاس پایه برای یک فیلد Word؛ GetFieldCode()، Update()، Unlink()، Remove()
FieldCollectionفیلدهای یک بازه، از طریق Range.Fields؛ Count، Remove()، Clear()
FieldTypeEnum که تعیین می‌کند کدام فیلد Word توسط یک نمونه Field نشان داده می‌شود
FieldOptionsپیکربندی به‌روزرسانی فیلد در سطح سند، از طریق Document.FieldOptions
IFieldUpdatingCallbackهوک‌های FieldUpdating / FieldUpdated در اطراف هر به‌روزرسانی فیلد
IFieldUpdatingProgressCallback / FieldUpdatingProgressArgsگزارش پیشرفت در به‌روزرسانی دسته‌ای فیلد
IFieldResultFormatterقالب‌بندی سفارشی نتیجه محاسبه‌شدهٔ فیلد
IFieldDatabaseProvider / FieldDatabaseDataTable / FieldDatabaseDataRowمنبع داده خارجی برای فیلد DATABASE
IComparisonExpressionEvaluator / ComparisonExpression / ComparisonEvaluationResultارزیابی سفارشی عبارات فیلد به سبک مقایسه‌ای
IFieldUserPromptRespondentپاسخ‌ها را برای فیلدهای مبتنی بر پرامپت در به‌روزرسانی‌های بدون نظارت فراهم می‌کند
IFieldUpdateCultureProvider / FieldUpdateCultureSourceانتخاب فرهنگ هنگام به‌روزرسانی فیلدها
UserInformationهویت نویسنده/کاربر (Name, Initials, Address) که توسط فیلدهای هویت خوانده می‌شود

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

 فارسی