العمل مع خصائص المستند
العمل مع خصائص المستند
يوضح هذا الدليل كيفية قراءة وإدارة بيانات التعريف الخاصة بمستند Word — الخصائص الظاهرة في لوحة المعلومات/الخصائص في Word، بالإضافة إلى أي قيم مخصصة معرفة من قبل التطبيق. Document.BuiltInDocumentProperties و Document.CustomDocumentProperties تكشف عن هاتين الفئتين، وكلاهما مبني في النهاية على تمثيل DocumentProperty الأساسي.
خصائص المستند المدمجة
Document.BuiltInDocumentProperties تُرجع مجموعة BuiltInDocumentProperties تغطي بيانات التعريف القياسية التي يتعقبها Word لكل مستند: حقول وصفية مثل Title، Subject، Author، Manager، Company، Category، Keywords، وComments؛ طوابع زمنية مثل CreatedTime، LastSavedTime، وLastPrinted، بالإضافة إلى LastSavedBy وRevisionNumber؛ وإحصائيات مثل Words، Characters، CharactersWithSpaces، Lines، Paragraphs، وPages. Security تُبلغ عن حالة حماية المستند كقيمة DocumentSecurity، وTemplate، NameOfApplication، وTotalEditingTime تصف بيئة التأليف. لأن BuiltInDocumentProperties هي مجموعة ثابتة ومعروفة من الخصائص، يتم قراءة وكتابة القيم الفردية كخصائص عادية (BuiltInDocumentProperties.Author = "...") بدلاً من البحث عنها بالاسم.
خصائص المستند المخصصة
Document.CustomDocumentProperties تُرجع مجموعة CustomDocumentProperties للبيانات التعريفية التي يحددها التطبيق والتي لا تُعد جزءًا من مجموعة Word المدمجة. عدة تحميلات Add(name, value) تُنشئ خاصية جديدة من اسم وقيمة مُحددة النوع (نص، رقم، منطقية، أو تاريخ، حسب التحميل)، وAddLinkToContent(name, linkSource) تُنشئ خاصية تكون قيمتها مرتبطة وتتابع نطاقًا مشارًا إليه في المستند بدلاً من احتفاظها بقيمة ثابتة. الفهرسة بالاسم (مثال: properties[name]) وContains(name) تبحث عن خاصية، IndexOf(name) تُرجع موقعها، وRemove(name)/RemoveAt(index) تحذف واحدة.
كائن DocumentProperty وقاعدة المجموعة المشتركة
كل من BuiltInDocumentProperties وCustomDocumentProperties مشتقان من DocumentPropertyCollection المجرد، الذي يعرّف فهرسًا بالاسم، GetEnumerator()، Contains(name)، IndexOf(name)، وCount — لذا يتم فحص المجموعتين بنفس الطريقة رغم أن الخصائص المدمجة ثابتة والخصائص المخصصة مفتوحة النهاية. بشكل فردي، يحتوي DocumentProperty على Name، وValue غير مكتوب النوع، وType (قيمة تعداد PropertyType: Boolean، DateTime، Double، Number، String، StringArray، ObjectArray، ByteArray أو Other). IsLinkToContent وLinkSource يبلّغان ما إذا كانت الخاصية مرتبطة بمحتوى المستند بدلاً من احتفاظها بقيمة ثابتة (انظر AddLinkToContent أعلاه). بما أن Value غير مكتوب النوع، يوفر DocumentProperty مُدخلات مكتوبة النوع — ToInt()، ToDouble()، ToDateTime()، ToBool()، ToByteArray()، وToString() — لقراءتها كنوع محدد دون تحويل صريح.
أمان المستند
يقوم BuiltInDocumentProperties.Security بالإبلاغ عن قيمة DocumentSecurity تصف حالة حماية المستند: None، PasswordProtected، ReadOnlyRecommended، ReadOnlyEnforced أو ReadOnlyExceptAnnotations. هذا يعكس بيانات الحماية المخزنة للمستند كما تم قراءتها من خصائص الملف.
نصائح وأفضل الممارسات
- استخدم مُدخلات النوع (
ToInt()،ToDouble()،ToDateTime()،ToBool()) علىDocumentProperty.Valueبدلاً من تحويل القيمة غير المكتوبة النوعobjectمباشرةً، لأن نوع التخزين الأساسي يمكن أن يختلف حسبPropertyType. - تحقّق من
Contains(name)قبل الفهرسة إلى أي من مجموعتي الخصائص بالاسم (مثال:properties[name]) عندما قد لا تكون الخاصية موجودة، لتجنّب معالجة حالة عدم وجود الخاصية كمسار استثناء. - استخدم
CustomDocumentProperties.AddLinkToContent(name, linkSource)عندما يجب أن تعكس قيمة الخاصية المخصصة دائمًا جزءًا مُعلَّمًا من المستند، بدلاً من إعادة مزامنة الخاصية المخصصة الثابتة يدويًا كلما تغيّر ذلك المحتوى. - عامل إحصاءات
BuiltInDocumentProperties(Words،Characters،Pages، وما شابه) كالقيم المخزنة في بيانات ملف التعريف بدلاً من كونها حسابات مباشرة دائمة — قم بتحديثها صراحةً إذا تغيّر المستند منذ آخر كتابة لها. - اقرأ
BuiltInDocumentProperties.Securityللتحقق من حالة الحماية المعلنة للمستند قبل اتخاذ قرار ما إذا كان هناك حاجة لمزيد من المعالجة المتعلقة بالحماية.
المشكلات الشائعة
| المشكلة | السبب | الإصلاح |
|---|---|---|
فهرسة مجموعة CustomDocumentProperties حسب الاسم لا تُعيد أي شيء قابل للاستخدام | الخاصية غير موجودة في هذا المستند | استدعِ Contains(name) أولاً، أو أضف الخاصية باستخدام التحميل الزائد المناسب لـ Add(name, value) |
| قراءة قيمة الخاصية المخصصة تُعطي النوع الخاطئ | DocumentProperty.Value غير مكتوب النوع object؛ المتصل افترض نوعًا لا يتطابق مع Type | استخدم المحدد المكتوب بنوع (ToInt(), ToDouble(), ToDateTime(), ToBool(), ToByteArray()) بناءً على DocumentProperty.Type |
| قيمة الخاصية المخصصة المرتبطة تبدو قديمة | الخاصية مرتبطة عبر AddLinkToContent، وتغيّر المحتوى المرتبط دون أن يتم تحديث المستند بشكل مناسب | تأكد من أن نطاق linkSource المُعلَّم لا يزال يعكس المحتوى المقصود |
إحصاءات الكلمات (Words, Pages، وما إلى ذلك) لا تتطابق مع المحتوى الفعلي الحالي للمستند | الإحصاءات المدمجة تعكس البيانات الوصفية المخزنة، وليس عدًا مباشرًا | أعد حساب وقم بتحديث القيم BuiltInDocumentProperties ذات الصلة إذا كان هناك حاجة إلى عدّ محدث |
FAQ
كيف يمكنني قراءة أو تعيين مؤلف المستند والعنوان؟
استخدم Document.BuiltInDocumentProperties.Author و.Title مباشرة — فهما خصائص سلسلة عادية في مجموعة BuiltInDocumentProperties التي يتم الوصول إليها من Document.BuiltInDocumentProperties.
كيف يمكنني إضافة بيانات تعريف خاصة بالتطبيق ليست خاصية قياسية في Word؟
استخدم Document.CustomDocumentProperties.Add(name, value) مع اسم الخاصية والقيمة؛ يتم اختيار التحميل الزائد المناسب لـ Add بناءً على نوع القيمة.
ما الفرق بين BuiltInDocumentProperties وCustomDocumentProperties؟
BuiltInDocumentProperties هي مجموعة Word الثابتة من حقول البيانات الوصفية القياسية (المؤلف، العنوان، الإحصاءات، وما إلى ذلك)، تُستَخدم كخصائص مسماة. CustomDocumentProperties هي مجموعة مسماة مفتوحة النهاية من قيم DocumentProperty للبيانات الوصفية المعرفة من قبل التطبيق، تُستَخدم بالاسم عبر الفهرس (مثال: properties[name]) وContains.
كيف أقرأ خاصية مخصصة دون معرفة نوعها المخزن الدقيق مسبقًا؟
استرجع الـDocumentProperty عن طريق فهرسة المجموعة (مثال: properties[name])، تحقق من Type الخاصة به (قيمة PropertyType)، واستخدم أداة الوصول ذات النوع المطابق مثل ToInt() أو ToDouble() أو ToDateTime() أو ToBool() على Value الخاص به.
كيف أجعل خاصية مخصصة تتبع جزءًا من محتوى المستند؟
استخدم CustomDocumentProperties.AddLinkToContent(name, linkSource)، مع تمرير اسم إشارة مرجعية كـlinkSource؛ ثم تعكس قيمة الخاصية ذلك المحتوى المرجعي بدلاً من قيمة ثابتة.
API Reference ملخص
| فئة/طريقة | وصف |
|---|---|
Document.BuiltInDocumentProperties | حقول البيانات الوصفية القياسية في Word (المؤلف، العنوان، الإحصاءات، الأمان، وما إلى ذلك) |
Document.CustomDocumentProperties | خصائص البيانات الوصفية المسماة التي يحددها التطبيق |
CustomDocumentProperties.Add(name, value) | أضف خاصية مخصصة من اسم وقيمة مُعَرَّفَة |
CustomDocumentProperties.AddLinkToContent(name, linkSource) | أضف خاصية مخصصة مرتبطة بمحتوى المستند المُشار إليه |
DocumentPropertyCollection | قاعدة مجردة مشتركة لكلا مجموعتي الخصائص |
DocumentProperty | اسم خاصية واحدة، قيمة غير مُعَرَّفَة، وPropertyType |
DocumentProperty.ToInt() / ToDouble() / ToDateTime() / ToBool() | الوصوليات المكتوبة لنوع قيمة الخاصية |
PropertyType | تعداد يصف نوع قيمة DocumentProperty |
DocumentSecurity | تعداد يصف حالة حماية المستند، عبر BuiltInDocumentProperties.Security |
