العمل مع ترميز 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 هو تعداد — Unknown، Inline، Block، Row، Cell — يصف المستوى الهيكلي في شجرة المستند الذي يمكن أن يظهر فيه عنصر توصيف مثل علامة مستند مهيكلة.
نصائح وممارسات أفضل
- استخدم
CustomXmlPartCollection.GetById(id)بدلاً من تكرار المجموعة يدويًا عندما تعرف معرف الجزء الذي تحتاجه. - اقرأ
CustomXmlPart.DataChecksumلاكتشاف ما إذا كانت بيانات XML الأساسية قد تغيرت دون إجراء مقارنة بايت كاملة. - فرق بين
Document.CustomXmlParts(بيانات XML مخصصة، غالبًا ما تكون مرتبطة بضوابط المحتوى) وDocument.PackageCustomParts(أجزاء حزمة غير XML عشوائية) — فهي تخدم أغراضًا مختلفة وتُخزن بشكل منفصل. - عند العمل على مستندات قديمة تستخدم العلامات الذكية، تحقق من
SmartTag.ElementوUriمعًا لتحديد أي مُعرّف أنشأ العلامة قبل الاعتماد علىPropertiesالخاص به. - استنسخ أجزاء XML المخصصة باستخدام
CustomXmlPart.Clone()(أوClone()الخاص بالمجموعة) عند نسخ البيانات بين المستندات بدلاً من إعادة القراءة وإعادة إضافة XML الخام.
مشكلات شائعة
| مشكلة | السبب | إصلاح |
|---|---|---|
CustomXmlPartCollection.GetById(id) لا يُعيد شيئًا قابلًا للاستخدام | الـ id لا يتطابق مع أي جزء موجود حاليًا في Document.CustomXmlParts | عدد المجموعة لتأكيد الـ id، أو أضف الجزء أولاً باستخدام Add(id, xml) |
| بيانات XML المخصصة تبدو غير مرتبطة بعناصر التحكم الظاهرة في المحتوى | عناصر التحكم في المحتوى ترتبط بـ XML المخصص عبر تكوين ربط البيانات الخاص بها، وليس تلقائيًا بكل CustomXmlPart | تأكد من الجزء الذي يرتبط به عنصر التحكم بالمحتوى المحدد بدلاً من افتراض علاقة 1:1 مع Document.CustomXmlParts |
الجزء الحزمي الذي أضافه تطبيق آخر غير موجود في CustomXmlParts | الأجزاء الحزمية غير XML تُعرض عبر Document.PackageCustomParts، وليس عبر CustomXmlParts | تحقق من PackageCustomParts (وهو CustomPartCollection) بدلاً من ذلك |
SmartTag.Properties فارغ | ليس كل مميّز للوسوم الذكية يرفق خصائص مُنظمة | تحقق من SmartTag.Element/Uri لتأكيد أي مميّز أنشأ الوسم قبل توقع خصائص معينة |
FAQ
ما الفرق بين CustomXmlPart وCustomXmlProperty؟
CustomXmlPart هو جزيرة بيانات XML كاملة (مع حمولة مصفوفة بايت ومخططات مرتبطة)، يتم الوصول إليها عبر Document.CustomXmlParts. CustomXmlProperty هو زوج اسم/قيمة واحد، يُستَخدم عادةً عبر SmartTag.Properties بدلاً من الوصول مباشرةً من المستند.
كيف يمكنني إضافة بيانات XML مخصصة إلى مستند؟
استدعِ Document.CustomXmlParts.Add(id, xml) مع سلسلة معرّف ومحتوى 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 ملخص
| فئة/طريقة | وصف |
|---|---|
CustomXmlPart | جزيرة بيانات مخصصة XML واحدة مرفقة بوثيقة |
Document.CustomXmlParts | الCustomXmlPartCollection لجميع أجزاء XML المخصصة على مستند |
CustomXmlPartCollection.Add(id, xml) / GetById(id) | إضافة أو استرجاع جزء XML مخصص حسب المعرف |
CustomXmlSchemaCollection | عناوين URI للمخطط المرتبطة بـ CustomXmlPart |
CustomXmlProperty | خاصية XML اسم/قيمة واحدة |
CustomXmlPropertyCollection | مجموعة من قيم CustomXmlProperty، مثلاً على SmartTag.Properties |
Document.PackageCustomParts | الCustomPartCollection لأجزاء حزمة OOXML غير XML العشوائية |
CustomPart | جزء مخصص على مستوى الحزمة واحد يحتوي على Name، ContentType، وData الخام |
SmartTag | نوع العقدة القديمة الذي يلتف حول النص الذي يتعرف عليه مُعرّف العلامات الذكية |
MarkupLevel | Enum يصف المكان الذي يمكن أن يتواجد فيه عنصر الترميز في شجرة المستند |
