كيفية العمل مع ترميز XML المخصص في .NET
كيفية العمل مع ترميز XML المخصص في .NET
يمكن لمستند Word أن يحمل بيانات XML مخصصة إلى جانب محتواه الظاهر — بيانات تُستخدم لربط عناصر التحكم في المحتوى، أو تخزين بيانات تعريفية خاصة بالتطبيق، أو تضمين أجزاء أضيفت بواسطة تطبيق آخر. يوضح هذا الدليل كيفية قراءة تلك البيانات، إضافة أجزاء XML مخصصة جديدة، وفحص العلامات الذكية القديمة التي قد لا تزال المستندات القديمة تحتوي عليها، باستخدام CustomXmlPart، CustomXmlProperty، وSmartTag في Aspose.Words FOSS لـ .NET.
دليل خطوة بخطوة
الخطوة 1: قراءة بيانات XML المخصصة من مستند
Document.CustomXmlParts تُعيد CustomXmlPartCollection — نفس الآلية التي يستخدمها Word لدعم عناصر التحكم في المحتوى المرتبطة بـ XML. قم بتكرار المجموعة، أو استدعِ GetById(id) عندما تعرف بالفعل أي جزء تحتاجه، للحصول على CustomXmlPart. كل جزء يُظهر Id، وهو مصفوفة بايت Data تحتوي على الـ XML الخام، وDataChecksum لاكتشاف ما إذا كانت البيانات قد تغيرت دون مقارنة بايت كاملة، وSchemas — وهو CustomXmlSchemaCollection يُسرد مخططات XML المرتبطة به.
الخطوة 2: إضافة أو تحديث جزء XML مخصص
استدعِ CustomXmlPartCollection.Add(id, xml) مع سلسلة معرف ومحتوى XML لإنشاء جزء مباشرة، أو أنشئ CustomXmlPart بشكل منفصل ومرره إلى Add(part). لإزالة البيانات، استخدم RemoveAt(index) على موضع محدد أو Clear() لإسقاط كل جزء. عند نسخ بيانات XML المخصَّصة بين المستندات، استخدم CustomXmlPart.Clone() (أو مجموعة Clone()) على الجزء المصدر بدلاً من إعادة القراءة وإضافة XML الخام مرة أخرى، ثم أضف النسخة المستنسخة إلى Document.CustomXmlParts الخاص بالمستند الهدف.
الخطوة 3: إدارة المخططات المرتبطة بجزء
CustomXmlPart.Schemas يصل إلى CustomXmlSchemaCollection، الذي يتتبع عناوين URI للمخططات المرتبطة بالجزء كسلاسل نصية عادية بدلاً من كائنات مخطط مُحلَّلة. استخدم Add(value) لتسجيل عنوان URI للمخطط، وRemove(name) أو RemoveAt(index) لإسقاط أحدها، وIndexOf(value) لتحديد موقع أحدها، وClear() لإزالتها جميعًا. Count يبلّغ عن عدد عناوين URI للمخططات المرتبطة حاليًا بالجزء.
الخطوة 4: العمل مع الأجزاء المخصَّصة على مستوى الحزمة
ليس كل جزء غير مرئي في حزمة OOXML هو XML مخصَّص. Document.PackageCustomParts يُعيد CustomPartCollection من كائنات CustomPart — أجزاء عشوائية مخزَّنة في الحزمة، مثل الأجزاء التي أضافها تطبيق آخر عالج الملف. كل CustomPart يحتوي على Name، ContentType، RelationshipType، ومصفوفة بايت Data، وعلم IsExternal يشير إلى ما إذا كان مرجعًا خارجيًا بدلاً من محتوى مضمّن. Add(part) وRemoveAt(index) وClear() يديرون المجموعة بنفس طريقة CustomXmlPartCollection. تحقق من PackageCustomParts — وليس CustomXmlParts — عندما لا يظهر الجزء الذي يجب أن يحمل مستندك في مجموعة XML المخصَّصة.
الخطوة 5: فحص العلامات الذكية القديمة وخصائصها
SmartTag هو نوع عقدة (NodeType.SmartTag، مُنشأ باستخدام SmartTag(doc)) يمثل علامة ذكية قديمة في Word ملفوفة حول نص مُعترف به. تحقق من Element وUri معًا لتحديد أي مُعرّف أنشأ العلامة، ثم اقرأ Properties — وهو CustomXmlPropertyCollection — للبيانات المهيكلة التي أرفقها المُعرّف. داخل CustomXmlPropertyCollection، يقوم الفهرس (مثلاً properties["MyProp"]) أو Contains(name) بالبحث عن خاصية معينة، IndexOfKey(name) تُعيد موقعها، وRemove(name)/RemoveAt(index)/Clear() تُزيل الإدخالات؛ كل CustomXmlProperty يُنشأ باستخدام CustomXmlProperty(name, uri, value) ويكشف عن Name وUri وValue. لأن SmartTag مشتق من CompositeNode، فإنه يشارك أيضًا في شجرة المستند مثل العقد الأخرى، داعمًا Accept(visitor) وAcceptStart(visitor) وAcceptEnd(visitor) للتنقل القائم على DocumentVisitor.
المشكلات الشائعة والحلول
CustomXmlPartCollection.GetById(id) لا يُعيد أي شيء قابل للاستخدام. المعرف لا يتطابق مع أي جزء موجود حاليًا في Document.CustomXmlParts. قم بإحصاء المجموعة لتأكيد وجود المعرف، أو أضف الجزء أولاً باستخدام Add(id, xml).
الجزء الذي أضيف بواسطة تطبيق آخر لا يتم العثور عليه عند التكرار CustomXmlParts. أجزاء الحزمة غير-XML تُعرض عبر Document.PackageCustomParts، وليس CustomXmlParts. تحقق من PackageCustomParts (أ CustomPartCollection) بدلاً من ذلك.
SmartTag.Properties فارغ على الرغم من أن العلامة موجودة بوضوح. ليس كل مُعرّف للوسوم الذكية يرفق خصائص مُنظمة. تحقق SmartTag.Element and Uri لتأكيد أي مُعرّف أنشأ العلامة قبل الافتراض بوجود خصائص محددة.
يبدو أن بيانات XML المخصصة لا ترتبط بالتحكم بالمحتوى الذي يجب ربطها به. تربط عناصر التحكم بالمحتوى إلى XML المخصص عبر إعدادات ربط البيانات الخاصة بها، وليس تلقائيًا إلى كل CustomXmlPart in Document.CustomXmlParts. تأكد من الجزء الذي يرتبط به عنصر التحكم بالمحتوى فعليًا بدلاً من الافتراض بوجود علاقة واحد لواحد.
الأسئلة المتكررة
كيف يمكنني إضافة بيانات XML مخصصة إلى مستند؟
استدعِ Document.CustomXmlParts.Add(id, xml) بسلسلة معرف ومحتوى XML، أو أنشئ CustomXmlPart بشكل منفصل ومرره إلى Add(part).
ما الفرق بين CustomXmlPart و CustomXmlProperty؟
CustomXmlPart هو جزيرة بيانات XML كاملة — حمولة مصفوفة بايت بالإضافة إلى المخططات المرتبطة — يتم الوصول إليها عبر Document.CustomXmlParts. CustomXmlProperty هو زوج اسم/قيمة واحد، عادةً ما يتم الوصول إليه عبر SmartTag.Properties بدلاً من الوصول مباشرةً من المستند.
كيف يمكنني نسخ بيانات XML المخصصة من مستند إلى آخر؟
استدعِ Clone() على CustomXmlPart المصدر، ثم أضف النسخة المستنسخة إلى Document.CustomXmlParts الخاص بالمستند الهدف باستخدام Add(part).
ما هو SmartTag، ومتى قد أصادفه؟
SmartTag هو ميزة قديمة في Word تمثل النص الذي تم التعرف عليه وتغليفه بواسطة مُعرّف العلامة الذكية — عقدة مستند (NodeType.SmartTag) تحتوي على Element و Uri لتحديد المُعرّف، بالإضافة إلى مجموعة Properties من قيم CustomXmlProperty. يظهر ذلك في المستندات التي تم إنشاؤها أو تحريرها مع تمكين العلامات الذكية في إصدارات Word القديمة.
كيف يمكنني معرفة عدد أجزاء XML المخصصة أو أجزاء الحزمة التي يحتويها المستند؟
اقرأ Count على Document.CustomXmlParts (وCustomXmlPartCollection) أو Document.PackageCustomParts (وCustomPartCollection) على التوالي.
