עבודה עם שדות
סקירה
שדה 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() |
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) נקראת משדות הזהות |