Εργασία με Πεδία
Επισκόπηση
Ένα πεδίο Word – DATE, IF, DATABASE, REF, και δεκάδες άλλα – εκπροσωπείται σε Aspose.Words FOSS για .NET από το Field κλάση και τις υποκλάσεις της, όλες στο Aspose.Words.Fields namespace. Αυτή η σελίδα καλύπτει τη βασική μηχανή πεδίων: το Field το ίδιο το μοντέλο αντικειμένων, πώς συλλέγονται και ενημερώνονται τα πεδία, και οι διεπαφές callback που σας επιτρέπουν να ενσωματώσετε προσαρμοσμένα δεδομένα και συμπεριφορά κατά τη διάρκεια μιας ενημέρωσης πεδίου. Συγκεκριμένες οικογένειες πεδίων – υπερσυνδέσμους και παραπομπές, πεδία ημερομηνίας/ώρας, πεδία συγχώνευσης αλληλογραφίας, πεδία ευρετηρίου και πίνακα περιεχομένων – κάθε μία έχει τη δική της αφιερωμένη σελίδα οδηγού προγραμματιστών.
Το Μοντέλο Αντικειμένου Πεδίου
Κάθε πεδίο σε ένα έγγραφο είναι μια παρουσία 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 page-number entries – αξιολογούνται σε ένα placeholder0, επειδή αυτή η έκδοση δεν περιλαμβάνει τη μηχανή page-layout/rendering engine. - Καταχωρίστε το
IFieldUpdatingCallbackπριν εκτελέσετε τοRange.UpdateFields()σε ένα μεγάλο ή άγνωστο έγγραφο εάν χρειάζεται να καταγράψετε ή να ελέγξετε ακριβώς ποια πεδία άλλαξαν. - Ορίστε το
FieldOptions.UserPromptRespondent(ή παρέχετε τιμέςDefaultResponseστις μεμονωμένες κλάσεις πεδίων που οδηγούνται από προτροπές) πριν ενημερώσετε ένα έγγραφο σε μια αυτόματη αλυσίδα, ώστε τα πεδίαASK/FILLINνα μην κολλήσουν περιμένοντας διαδραστική εισαγωγή.
Κοινά Προβλήματα
| Ζήτημα | Αιτία | Διόρθωση |
|---|---|---|
| Το αποτέλεσμα του πεδίου είναι παρωχημένο μετά την επεξεργασία του εγγράφου | Aspose.Words FOSS δεν ενημερώνει αυτόματα τα πεδία κατά τη φόρτωση ή την αποθήκευση | Καλέστε Range.UpdateFields() ή Field.Update() ρητά |
PAGE, NUMPAGES, ή οι αριθμοί σελίδας του Πίνακα Περιεχομένων εμφανίζουν 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 – αξιολογούνται σε έναν placeholder 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 hooks γύρω από κάθε ενημέρωση πεδίου |
IFieldUpdatingProgressCallback / FieldUpdatingProgressArgs | Αναφορά προόδου κατά τη διάρκεια μαζικής ενημέρωσης πεδίου |
IFieldResultFormatter | Προσαρμοσμένη μορφοποίηση του υπολογισμένου αποτελέσματος ενός πεδίου |
IFieldDatabaseProvider / FieldDatabaseDataTable / FieldDatabaseDataRow | Εξωτερική πηγή δεδομένων για το πεδίο DATABASE |
IComparisonExpressionEvaluator / ComparisonExpression / ComparisonEvaluationResult | Προσαρμοσμένη αξιολόγηση εκφράσεων πεδίων τύπου σύγκρισης |
IFieldUserPromptRespondent | Παρέχει απαντήσεις για πεδία που καθορίζονται από προτροπές σε αυτόματες ενημερώσεις |
IFieldUpdateCultureProvider / FieldUpdateCultureSource | Επιλογή πολιτισμού κατά τις ενημερώσεις πεδίου |
UserInformation | Ταυτότητα συγγραφέα/χρήστη (Name, Initials, Address) διαβάζεται από πεδία ταυτότητας |