کار با فیلدها
بررسی کلی
یک فیلد 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() |
FieldType | Enum که تعیین میکند کدام فیلد 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) که توسط فیلدهای هویت خوانده میشود |