עבודה עם שדות

סקירה

שדה Word – DATE, IF, DATABASE, REF, ועשרות אחרים – מיוצג ב Aspose.Words FOSS עבור .NET על-ידי ה Field מחלקה ותתי-מחלקותיה, כולם ב Aspose.Words.Fields מרחב השמות. דף זה מכסה את מנוע השדה המרכזי: ה Field מודל האובייקט עצמו, כיצד השדות נאספים ומעודכנים, והאינטרפֵסְים של קריאות חזרה שמאפשרים לך לשלב נתונים והתנהגות מותאמים אישית במהלך עדכון שדה. משפחות שדה ספציפיות – hyperlinks and cross-references, date/time fields, mail-merge fields, index and table-of-contents fields – לכל אחת יש דף מדריך למפתחים ייעודי.


מודל האובייקט של השדה

כל שדה במסמך הוא מופע של 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 – קוראים ל-IFieldUserPromptRespondent.Respond() כאשר אחד מוקצה ל-FieldOptions.UserPromptRespondent, כך שעדכון ללא פיקוח אינו חוסם ממתינה לקלט אינטראקטיבי.


זהות משתמש ומסמך עבור שדות

UserInformation (Name, Initials, Address, וה-UserInformation.DefaultUser הסטטי) מספק את הזהות שממנה קוראים השדות הקשורים למחבר ולשם המשתמש. הקצה מופע ל-Document.FieldOptions.CurrentUser לפני עדכון שדות התלויים במחבר המסמך או בזהות המשתמש.


טיפים ושיטות מומלצות

  • Aspose.Words FOSS אינו מחשב מחדש שדות באופן אוטומטי בטעינה או שמירה כפי ש-Word עושה – יש לקרוא ל-Range.UpdateFields() (או Field.Update() לשדה בודד) במפורש לאחר כל עריכה תוכנתית שצריכה להשתקף בתוצאות השדה.
  • FieldStart, Separator ו-FieldEnd הם צמתים אמיתיים בעץ המסמך; יש להסיר שדה דרך Field.Remove() או Field.Unlink() במקום למחוק את צמתי הסמן ישירות, אחרת מבנה השדה עלול להפוך לחסר עקביות.
  • שדות שהתוצאה שלהם תלויה בפריסת העמוד – PAGE, NUMPAGES וערכי מספרי העמוד של TOC – מתערכים למחליף 0, מכיוון שהגרסה הזו אינה כוללת מנוע פריסת/הצגת עמודים.
  • רשום את IFieldUpdatingCallback לפני הפעלת Range.UpdateFields() על מסמך גדול או לא מוכר אם אתה צריך לרשום או לבצע ביקורת מדויקת על אילו שדות השתנו.
  • הגדר את 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 מעריך כל סוג שדה של 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 מופעים.


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) נקראת משדות הזהות

ראה גם

 עברית