Làm việc với Đánh dấu XML Tùy chỉnh

Làm việc với Đánh dấu XML Tùy chỉnh

Hướng dẫn này cho thấy cách đọc và quản lý dữ liệu XML tùy chỉnh mà một tài liệu Word có thể mang cùng với nội dung hiển thị của nó — dữ liệu được sử dụng để ràng buộc các điều khiển nội dung, lưu siêu dữ liệu đặc thù của ứng dụng, hoặc nhúng các phần gói tùy ý. Document.CustomXmlParts cung cấp dữ liệu XML tùy chỉnh ở mức độ tài liệu, và Document.PackageCustomParts cung cấp các phần tùy chỉnh ở mức độ gói mà không phải là XML tùy chỉnh cụ thể.

Các phần XML Tùy chỉnh

CustomXmlPart đại diện cho một hòn đảo dữ liệu XML tùy chỉnh được gắn vào tài liệu — cùng cơ chế mà Word sử dụng để hỗ trợ các điều khiển nội dung được ánh xạ XML. Mỗi phần có một Id, một mảng byte Data chứa XML thô, một DataChecksum, và một thuộc tính Schemas (một CustomXmlSchemaCollection) liệt kê các lược đồ XML liên quan đến nó. Document.CustomXmlParts trả về một CustomXmlPartCollection: Add(part) gắn một CustomXmlPart hiện có, Add(id, xml) tạo một phần trực tiếp từ một id và chuỗi XML, GetById(id) truy xuất một phần cụ thể, và RemoveAt(index)/Clear() xóa các phần. Cả CustomXmlPart và CustomXmlPartCollection đều cung cấp Clone() để sao chép dữ liệu XML tùy chỉnh, ví dụ khi sao chép nội dung giữa các tài liệu.

Các lược đồ XML Tùy chỉnh

CustomXmlSchemaCollection, được truy cập qua CustomXmlPart.Schemas, liệt kê các URI lược đồ liên quan đến một phần XML tùy chỉnh. Nó hỗ trợ Add(value), Remove(name), RemoveAt(index), IndexOf(value), Clear() và Clone(), cùng với một thuộc tính Count — các URI lược đồ được theo dõi dưới dạng chuỗi thuần thay vì các đối tượng lược đồ đã được phân tích.

Các thuộc tính XML Tùy chỉnh

Riêng biệt với CustomXmlPart, CustomXmlProperty đại diện cho một thuộc tính XML tên/giá trị duy nhất, được tạo bằng CustomXmlProperty(name, uri, value) và cung cấp Name, Uri, và Value. CustomXmlPropertyCollection quản lý một tập hợp các thuộc tính này: Add(property) thêm một mục, bộ chỉ mục (ví dụ properties["MyProp"]) tra tìm một mục theo tên và Contains(name) kiểm tra xem nó có tồn tại không, IndexOfKey(name) trả về vị trí của nó, và Remove(name)/RemoveAt(index)/Clear() xóa các mục. SmartTag.Properties trả về một CustomXmlPropertyCollection, đây là cách dữ liệu có cấu trúc của thẻ thông minh kế thừa được biểu diễn (xem bên dưới).

Các phần tùy chỉnh cấp gói

Document.PackageCustomParts trả về một CustomPartCollection các đối tượng CustomPart — các phần tùy ý được lưu trong gói OOXML mà không phải là dữ liệu XML tùy chỉnh, chẳng hạn như các phần được thêm bởi các ứng dụng khác đã chỉnh sửa tệp. Mỗi CustomPart có một Name, ContentType, RelationshipType, một mảng byte Data, và một cờ IsExternal cho biết phần đó là tham chiếu bên ngoài thay vì nội dung nhúng. Bộ sưu tập hỗ trợ Add(part), RemoveAt(index), Clear(), và Clone(), cùng với Count.

Thẻ Thông minh Kế thừa

SmartTag là một kiểu nút (NodeType.SmartTag) đại diện cho một thẻ thông minh Word kế thừa được bọc quanh văn bản đã được nhận dạng. Một SmartTag được tạo bằng SmartTag(doc), và cung cấp Element (tên phần tử nhận dạng) và Uri (không gian tên của bộ nhận dạng), cùng với Properties — một CustomXmlPropertyCollection chứa dữ liệu có cấu trúc mà bộ nhận dạng gắn vào văn bản đã gắn thẻ. Vì SmartTag là một nút, nó cũng tham gia vào cây tài liệu như các nút khác, hỗ trợ Accept(visitor), AcceptStart(visitor), và AcceptEnd(visitor) cho việc duyệt dựa trên DocumentVisitor.

MarkupLevel

MarkupLevel là một enum — Unknown, Inline, Block, Row, Cell — mô tả mức độ cấu trúc trong cây tài liệu mà ở đó một phần tử đánh dấu như thẻ tài liệu có cấu trúc có thể xuất hiện.

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

• Sử dụng CustomXmlPartCollection.GetById(id) thay vì lặp lại bộ sưu tập một cách thủ công khi bạn biết id của phần bạn cần.
• Đọc CustomXmlPart.DataChecksum để phát hiện liệu dữ liệu XML nền đã thay đổi hay chưa mà không thực hiện so sánh byte toàn bộ.
• Phân biệt Document.CustomXmlParts (dữ liệu XML tùy chỉnh, thường gắn với các điều khiển nội dung) với Document.PackageCustomParts (các phần gói không phải XML tùy ý) — chúng phục vụ các mục đích khác nhau và được lưu trữ riêng biệt.
• Khi làm việc với tài liệu legacy sử dụng thẻ thông minh, hãy kiểm tra SmartTag.Element và Uri cùng nhau để xác định bộ nhận dạng nào đã tạo thẻ trước khi dựa vào Properties của nó.
• Nhân bản các phần XML tùy chỉnh bằng CustomXmlPart.Clone() (hoặc Clone() của bộ sưu tập) khi sao chép dữ liệu giữa các tài liệu thay vì đọc lại và thêm lại XML thô.

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

FAQ

Sự khác biệt giữa CustomXmlPart và CustomXmlProperty là gì?

CustomXmlPart là một hòn đảo dữ liệu XML toàn bộ (với tải trọng mảng byte và các schema liên quan), được truy cập qua Document.CustomXmlParts. CustomXmlProperty là một cặp tên/giá trị đơn, thường được truy cập qua SmartTag.Properties hơn là trực tiếp từ tài liệu.

Làm thế nào để tôi thêm dữ liệu XML tùy chỉnh vào tài liệu?

Gọi Document.CustomXmlParts.Add(id, xml) với một chuỗi id và nội dung XML, hoặc tạo một CustomXmlPart riêng biệt và truyền nó cho Add(part).

Các phần tùy chỉnh của gói là gì, và chúng khác gì so với các phần XML tùy chỉnh?

Document.PackageCustomParts (một CustomPartCollection của các đối tượng CustomPart) chứa các phần gói OOXML tùy ý không phải là XML tùy chỉnh — mỗi phần có một ContentType, RelationshipType, và Data thô. Document.CustomXmlParts được dành riêng cho các hòn đảo dữ liệu XML tùy chỉnh.

SmartTag là gì?

SmartTag là một tính năng Word kế thừa, đại diện cho văn bản được nhận dạng và bao bọc bởi bộ nhận dạng smart-tag. Nó là một nút tài liệu (NodeType.SmartTag) với một Element và Uri xác định bộ nhận dạng, và một bộ sưu tập Properties của các giá trị CustomXmlProperty mà bộ nhận dạng gắn vào.

Làm thế nào để tôi sao chép dữ liệu XML tùy chỉnh giữa các tài liệu?

Sử dụng CustomXmlPart.Clone() trên phần nguồn, sau đó thêm bản sao vào Document.CustomXmlParts của tài liệu đích với Add(part).

Tóm tắt API Reference

Xem thêm

• Aspose.Words for .NET — Enterprise Documentation