کار با نشانه‌گذاری سفارشی XML

کار با نشانه‌گذاری سفارشی XML

این راهنما نشان می‌دهد چگونه داده‌های سفارشی XML را که یک سند Word می‌تواند همراه با محتوای قابل مشاهده‌اش حمل می‌کند، بخوانید و مدیریت کنید — داده‌هایی که برای اتصال کنترل‌های محتوا، ذخیرهٔ فراداده‌های مخصوص برنامه، یا جاسازی بخش‌های دلخواه بسته استفاده می‌شوند. Document.CustomXmlParts داده‌های سفارشی XML در سطح سند را افشا می‌کند، و Document.PackageCustomParts بخش‌های سفارشی در سطح بسته را که به‌طور خاص XML سفارشی نیستند، افشا می‌کند.

بخش‌های سفارشی XML

CustomXmlPart یک جزیره داده سفارشی XML متصل به سند را نشان می‌دهد — همان مکانیزمی که Word برای پشتیبانی از کنترل‌های محتوا با نگاشت XML استفاده می‌کند. هر بخش دارای یک Id، یک آرایه بایتی Data که XML خام را نگه می‌دارد، یک DataChecksum، و یک ویژگی Schemas (یک CustomXmlSchemaCollection) است که طرح‌واره‌های XML مرتبط با آن را فهرست می‌کند. Document.CustomXmlParts یک CustomXmlPartCollection برمی‌گرداند: Add(part) یک CustomXmlPart موجود را پیوست می‌کند، Add(id, xml) یک مورد را مستقیماً از یک شناسه و رشته XML ایجاد می‌کند، GetById(id) یک بخش خاص را بازیابی می‌کند، و RemoveAt(index)/Clear() بخش‌ها را حذف می‌کنند. هر دو CustomXmlPart و CustomXmlPartCollection Clone() را برای تکثیر داده‌های سفارشی XML افشا می‌کنند، برای مثال هنگام کپی محتوا بین اسناد.

طرح‌واره‌های سفارشی XML

CustomXmlSchemaCollection، که از طریق CustomXmlPart.Schemas قابل دسترسی است، URIهای طرح‌واره مرتبط با یک بخش سفارشی XML را فهرست می‌کند. این مورد از Add(value)، Remove(name)، RemoveAt(index)، IndexOf(value)، Clear() و Clone() پشتیبانی می‌کند، به‌همراه یک ویژگی Count — URIهای طرح‌واره به‌عنوان رشته‌های ساده ردیابی می‌شوند نه به‌عنوان اشیای طرح‌وارهٔ تجزیه‌شده.

ویژگی‌های سفارشی XML

به‌صورت جداگانه از CustomXmlPart، CustomXmlProperty یک ویژگی XML تک‌نام/مقدار را نشان می‌دهد که با CustomXmlProperty(name, uri, value) ساخته شده و Name، Uri و Value را در دسترس می‌گذارد. CustomXmlPropertyCollection مجموعه‌ای از این‌ها را مدیریت می‌کند: Add(property) یک مورد را اضافه می‌کند، فهرست‌گذار (مثلاً properties["MyProp"]) بر اساس نام یک مورد را جستجو می‌کند و Contains(name) بررسی می‌کند که آیا وجود دارد، IndexOfKey(name) موقعیت آن را برمی‌گرداند، و Remove(name)/RemoveAt(index)/Clear() ورودی‌ها را حذف می‌کنند. SmartTag.Properties یک CustomXmlPropertyCollection برمی‌گرداند که نشان‌دهندهٔ نحوهٔ نمایش داده‌های ساختاری یک برچسب هوشمند قدیمی است (به پایین نگاه کنید).

بخش‌های سفارشی در سطح بسته

Document.PackageCustomParts یک CustomPartCollection از اشیاء CustomPart را برمی‌گرداند — بخش‌های دلخواهی که در بسته OOXML ذخیره شده‌اند و داده‌های سفارشی XML نیستند، مانند بخش‌هایی که توسط برنامه‌های دیگر که فایل را دست‌کاری کرده‌اند اضافه شده‌اند. هر CustomPart دارای یک Name، ContentType، RelationshipType، یک آرایه بایتی Data و یک پرچم IsExternal است که نشان می‌دهد آیا بخش یک مرجع خارجی است نه محتوای جاسازی‌شده. این مجموعه Add(part)، RemoveAt(index)، Clear() و Clone() را پشتیبانی می‌کند، به‌همراه Count.

برچسب‌های هوشمند قدیمی

SmartTag یک نوع گره (NodeType.SmartTag) است که یک برچسب هوشمند قدیمی Word را که دور متن شناسایی‌شده پیچیده است، نشان می‌دهد. یک SmartTag با SmartTag(doc) ساخته می‌شود و Element (نام عنصر شناسایی‌کننده) و Uri (فضای نام شناسایی‌کننده) را به‌همراه Properties — یک CustomXmlPropertyCollection که داده‌های ساختاری‌ای که شناسایی‌کننده به متن برچسب‌دار الصاق کرده را نگه می‌دارد — در دسترس می‌گذارد. از آنجا که SmartTag یک گره است، به‌همین دلیل در ساختار درخت سند مانند گره‌های دیگر مشارکت می‌کند و Accept(visitor)، AcceptStart(visitor) و AcceptEnd(visitor) را برای پیمایش مبتنی بر DocumentVisitor پشتیبانی می‌کند.

MarkupLevel

MarkupLevel یک enum است — Unknown، Inline، Block، Row، Cell — که سطح ساختاری در درخت سند را که در آن یک عنصر نشانه‌گذاری مانند برچسب سند ساختار یافته می‌تواند ظاهر شود، توصیف می‌کند.

نکات و بهترین شیوه‌ها

• به جای پیمایش دستی مجموعه، وقتی شناسهٔ بخشی که نیاز دارید را می‌دانید از CustomXmlPartCollection.GetById(id) استفاده کنید.
• برای تشخیص اینکه آیا دادهٔ XML زیرین تغییر کرده است بدون انجام مقایسهٔ بایت به بایت، CustomXmlPart.DataChecksum را بخوانید.
• تمایز Document.CustomXmlParts (دادهٔ سفارشی XML که اغلب به کنترل‌های محتوا مرتبط است) از Document.PackageCustomParts (بخش‌های بستهٔ دلخواه غیر XML) — آن‌ها مقاصد متفاوتی دارند و به‌صورت جداگانه ذخیره می‌شوند.
• هنگام کار با اسناد قدیمی که از برچسب‌های هوشمند استفاده می‌کنند، برای شناسایی شناساگری که برچسب را ایجاد کرده است، قبل از اتکا به Properties، SmartTag.Element و Uri را به‌طور مشترک بررسی کنید.
• برای کپی‌کردن داده‌ها بین اسناد، به‌جای خواندن مجدد و افزودن مستقیم XML خام، بخش‌های سفارشی XML را با استفاده از CustomXmlPart.Clone() (یا Clone() مجموعه) تکثیر کنید.

مشکلات رایج

FAQ

تفاوت CustomXmlPart و CustomXmlProperty چیست؟

CustomXmlPart یک جزیره دادهٔ کامل XML است (با محمولهٔ آرایه بایتی و طرح‌نامه‌های مرتبط)، که از طریق Document.CustomXmlParts دسترسی می‌شود. CustomXmlProperty یک جفت نام/مقدار تک است که معمولاً از طریق SmartTag.Properties به‌جای دسترسی مستقیم از سند به آن می‌رسند.

چگونه می‌توانم دادهٔ سفارشی XML را به یک سند اضافه کنم؟

با یک رشتهٔ شناسه و محتوای XML، Document.CustomXmlParts.Add(id, xml) را فراخوانی کنید، یا به‌طور جداگانه یک CustomXmlPart بسازید و آن را به Add(part) پاس بدهید.

بخش‌های سفارشی بسته چیستند و چگونه از بخش‌های سفارشی XML متفاوت هستند؟

Document.PackageCustomParts (یک CustomPartCollection از اشیاء CustomPart) بخش‌های دلخواه بستهٔ OOXML را که سفارشی XML نیستند نگهداری می‌کند — هر کدام دارای ContentType، RelationshipType و Data خام هستند. Document.CustomXmlParts مخصوص جزایر دادهٔ سفارشی XML است.

«SmartTag» چیست؟

SmartTag یک ویژگی قدیمی Word است که متن شناسایی‌شده و توسط یک تشخیص‌گر برچسب هوشمند بسته‌بندی شده را نشان می‌دهد. این یک گرهٔ سند (NodeType.SmartTag) با یک Element و Uri است که تشخیص‌گر را شناسایی می‌کند، و یک مجموعهٔ Properties از مقادیر CustomXmlProperty که توسط تشخیص‌گر افزوده شده‌اند.

چگونه می‌توانم دادهٔ سفارشی XML را بین اسناد کپی کنم؟

از CustomXmlPart.Clone() در بخش منبع استفاده کنید، سپس کلون را به Document.CustomXmlParts سند هدف با Add(part) اضافه کنید.

API Reference خلاصه

همچنین ببینید:

• Aspose.Words for .NET — Enterprise Documentation