Làm việc với Trường

Tổng quan

Một trường Word – DATE, IF, DATABASE, REF, và hàng chục trường khác – được biểu diễn trong Aspose.Words FOSS cho .NET bởi Field lớp và các lớp con của nó, tất cả trong Aspose.Words.Fields không gian tên. Trang này đề cập đến động cơ trường cốt lõi: Field bản mô hình đối tượng, cách các trường được thu thập và cập nhật, và các giao diện callback cho phép bạn chèn dữ liệu và hành vi tùy chỉnh trong quá trình cập nhật trường. Các họ trường cụ thể – siêu liên kết và tham chiếu chéo, trường ngày/giờ, trường mail-merge, trường chỉ mục và mục lục – mỗi họ đều có trang hướng dẫn nhà phát triển riêng.


Mô hình Đối tượng Trường

Mỗi trường trong một tài liệu là một thể hiện Field bao gồm ba nút đánh dấu – FieldStart, Separator, và FieldEnd – được mở ra dưới dạng các thuộc tính Field.Start, Field.Separator, và Field.End. Field.Type xác định FieldType nào mà trường đại diện, Field.Result và Field.DisplayResult cung cấp giá trị đã tính toán lần cuối, và Field.Format chứa bất kỳ công tắc nào (chẳng hạn chuỗi định dạng số hoặc ngày-giờ) được gắn vào mã trường. Field.IsLocked và Field.IsDirty báo cáo trạng thái khóa và lỗi thời của trường. Gọi Field.GetFieldCode() để đọc văn bản mã trường thô, Field.Update() để tính lại kết quả, Field.Unlink() để thay thế trường bằng văn bản tĩnh, và Field.Remove() để xóa hoàn toàn.


Truy cập và Cập nhật Các Trường trong Tài liệu

Document.Range.Fields trả về một FieldCollection – các trường nằm trong phạm vi đó, với Count, Remove(), RemoveAt(), và Clear() để xóa hàng loạt. Range.UpdateFields() tính lại mọi trường trong phạm vi, Range.UnlinkFields() chuyển mọi trường trong phạm vi thành văn bản tĩnh, và Range.NormalizeFieldTypes() điều chỉnh mã loại lưu trữ của trường so với mã trường thực tế sau khi chỉnh sửa thủ công. DocumentBuilder.InsertField() chèn một trường mới tại con trỏ, với các overload cho phép hoặc cập nhật ngay kết quả của trường mới hoặc để lại cho lần chạy Range.UpdateFields() sau.


Tùy chọn Cập nhật Trường và Văn hoá

Document.FieldOptions là một thể hiện FieldOptions điều khiển cách các trường của toàn bộ tài liệu hoạt động khi được cập nhật: CurrentUser cung cấp UserInformation được các trường nhận dạng sử dụng, DefaultDocumentAuthor tạo ra các kết quả liên quan tới tác giả, LegacyNumberFormat và UseInvariantCultureNumberFormat kiểm soát định dạng số, và PreProcessCulture và FieldUpdateCultureSource (kèm theo callback IFieldUpdateCultureProvider) xác định nền văn hoá nào chi phối định dạng ngày và số trong quá trình cập nhật. TemplateName, FileName, và BuiltInTemplatesPaths cung cấp các giá trị mà các trường nhận thức mẫu và tên tệp đọc lại.


Theo dõi và Tùy chỉnh Cập nhật Trường

Triển khai IFieldUpdatingCallback (FieldUpdating và FieldUpdated) trên FieldOptions để chạy mã ngay trước và ngay sau mỗi lần trường được tính lại – hữu ích để kiểm tra những trường nào đã thay đổi trong một công việc batch. Triển khai IFieldUpdatingProgressCallback (Notify) để theo dõi tiến độ tổng thể trên một tài liệu lớn; nó nhận một FieldUpdatingProgressArgs với TotalFieldsCount, UpdatedFieldsCount, và UpdateCompleted. Để thay đổi cách kết quả số hoặc chung của một trường được hiển thị dưới dạng văn bản, triển khai IFieldResultFormatter (Format(value, format) và FormatNumeric(value, format)) và gán nó cho FieldOptions.ResultFormatter.


Cung cấp Dữ liệu Ngoại vi cho Các Trường

Trường DATABASE đọc các hàng của nó thông qua IFieldDatabaseProvider.GetQueryResult(), thứ trả về một FieldDatabaseDataTable (ColumnNames, Rows) được xây dựng từ các thể hiện FieldDatabaseDataRow (Values) – gán triển khai của bạn cho FieldOptions.FieldDatabaseProvider. Các trường so sánh như IF đánh giá điều kiện của chúng thông qua IComparisonExpressionEvaluator.Evaluate(), thứ nhận một ComparisonExpression (LeftExpression, ComparisonOperator, RightExpression) và trả về một ComparisonEvaluationResult (Result, ErrorMessage); gán một bộ đánh giá tùy chỉnh cho FieldOptions.ComparisonExpressionEvaluator để ghi đè logic so sánh mặc định. Các trường thường yêu cầu người dùng nhập dữ liệu trong quá trình cập nhật – như ASK và FILLIN – gọi IFieldUserPromptRespondent.Respond() khi một thứ được gán cho FieldOptions.UserPromptRespondent, để một cập nhật không có người giám sát không bị chặn chờ nhập tương tác.


Nhận dạng Người dùng và Tài liệu cho Các Trường

UserInformation (Name, Initials, Address, và UserInformation.DefaultUser tĩnh) cung cấp nhận dạng mà các trường liên quan đến tác giả và tên người dùng đọc từ. Gán một thể hiện cho Document.FieldOptions.CurrentUser trước khi cập nhật các trường phụ thuộc vào tác giả tài liệu hoặc nhận dạng người dùng.


Mẹo và Thực hành Tốt nhất

  • Aspose.Words FOSS không tự động tính lại các trường khi tải hoặc lưu như Word làm – hãy gọi Range.UpdateFields() (hoặc Field.Update() cho một trường duy nhất) một cách rõ ràng sau bất kỳ chỉnh sửa lập trình nào mà kết quả nên được phản ánh trong các trường.
  • FieldStart, Separator, và FieldEnd là các nút thực trong cây tài liệu; hãy xóa một trường thông qua Field.Remove() hoặc Field.Unlink() thay vì xóa trực tiếp các nút đánh dấu, nếu không cấu trúc trường có thể trở nên không nhất quán.
  • Các trường mà kết quả phụ thuộc vào bố cục trang – PAGE, NUMPAGES, và các mục số trang của TOC – sẽ đánh giá thành một placeholder 0, vì phiên bản này không bao gồm công cụ bố cục/trình diễn trang.
  • Đăng ký IFieldUpdatingCallback trước khi chạy Range.UpdateFields() trên một tài liệu lớn hoặc chưa quen nếu bạn cần ghi nhật ký hoặc kiểm toán chính xác những trường nào đã thay đổi.
  • Thiết lập FieldOptions.UserPromptRespondent (hoặc cung cấp các giá trị DefaultResponse cho các lớp trường dựa trên lời nhắc riêng lẻ) trước khi cập nhật tài liệu trong một pipeline không có người giám sát, để các trường ASK/FILLIN không bị treo chờ đầu vào tương tác.

Các vấn đề thường gặp

Vấn đềNguyên nhânSửa
Kết quả trường đã lỗi thời sau khi chỉnh sửa tài liệuAspose.Words FOSS không tự động cập nhật các trường khi tải hoặc lưuGọi Range.UpdateFields() hoặc Field.Update() một cách rõ ràng
PAGE, NUMPAGES, hoặc số trang TOC hiển thị 0Bố cục/trình bày trang không phải là một phần của phiên bản nàyHành vi mong đợi – sử dụng phiên bản thương mại Aspose.Words cho .NET nếu bạn cần số trang được tính toán
trường DATABASE không tạo ra dòng nàoKhông có IFieldDatabaseProvider nào được gán cho FieldOptions.FieldDatabaseProviderTriển khai IFieldDatabaseProvider và gán nó trước khi gọi Range.UpdateFields()
Cập nhật trường hàng loạt dường như bị treoTrường được điều khiển bằng lời nhắc (ASK, FILLIN) không có IFieldUserPromptRespondent nào được gánGán FieldOptions.UserPromptRespondent, hoặc đặt DefaultResponse trên thể hiện trường

FAQ

Liệu Aspose.Words FOSS có đánh giá mọi loại trường Word không?

Mô hình đối tượng Field đại diện cho mọi giá trị FieldType và cập nhật hầu hết chúng, nhưng các trường mà kết quả phụ thuộc vào bố cục trang — chẳng hạn như PAGE và NUMPAGES — sẽ được đánh giá thành một placeholder 0 vì phiên bản này không bao gồm công cụ bố cục/hiển thị.

Làm sao tôi có thể đánh giá lại các trường sau khi chỉnh sửa tài liệu một cách lập trình?

Gọi Range.UpdateFields() trên phạm vi bao phủ nội dung đã chỉnh sửa, hoặc Document.Range.UpdateFields() để cập nhật mọi trường trong tài liệu.

Tôi có thể chuyển một trường thành văn bản tĩnh, đơn giản không?

Có – Field.Unlink() thay thế trường bằng kết quả đã tính cuối cùng dưới dạng văn bản thông thường, loại bỏ mã trường nền.

Làm thế nào để tôi xóa một trường hoàn toàn, bao gồm cả kết quả của nó?

Gọi Field.Remove(). Nó xóa các nút FieldStart, Separator và FieldEnd cùng với mã và nội dung kết quả của trường.

Làm thế nào để tôi cung cấp dữ liệu tùy chỉnh cho trường DATABASE?

Triển khai IFieldDatabaseProvider và gán nó cho Document.FieldOptions.FieldDatabaseProvider. Việc triển khai GetQueryResult() của bạn trả về một FieldDatabaseDataTable được xây dựng từ các thể hiện FieldDatabaseDataRow.


API Reference Tóm tắt

Lớp / Giao diệnMô tả
FieldLớp cơ sở cho một trường Word; GetFieldCode(), Update(), Unlink(), Remove()
FieldCollectionCác trường trong một phạm vi, thông qua Range.Fields; Count, Remove(), Clear()
FieldTypeEnum xác định trường Word nào mà một đối tượng Field đại diện
FieldOptionsCấu hình cập nhật trường trên toàn tài liệu, qua Document.FieldOptions
IFieldUpdatingCallbackFieldUpdating / FieldUpdated các hook quanh mỗi lần cập nhật trường
IFieldUpdatingProgressCallback / FieldUpdatingProgressArgsBáo cáo tiến độ cho việc cập nhật trường hàng loạt
IFieldResultFormatterĐịnh dạng tùy chỉnh cho kết quả tính toán của trường
IFieldDatabaseProvider / FieldDatabaseDataTable / FieldDatabaseDataRowNguồn dữ liệu bên ngoài cho trường DATABASE
IComparisonExpressionEvaluator / ComparisonExpression / ComparisonEvaluationResultĐánh giá tùy chỉnh cho các biểu thức trường kiểu so sánh
IFieldUserPromptRespondentCung cấp phản hồi cho các trường dựa trên lời nhắc trong cập nhật không giám sát
IFieldUpdateCultureProvider / FieldUpdateCultureSourceLựa chọn văn hoá khi cập nhật trường
UserInformationDanh tính tác giả/người dùng (Name, Initials, Address) được đọc bởi các trường danh tính

Xem thêm

 Tiếng Việt