كيفية العمل مع خصائص المستند في .NET
كيفية العمل مع خصائص المستند في .NET
يحمل كل مستند Word فئتين من البيانات الوصفية — الحقول القياسية التي يتتبعها Word لكل ملف، وأي قيم معرفة من قبل التطبيق أضافها البرنامج. يوضح هذا الدليل كيفية قراءة وتعيين كلاهما باستخدام Aspose.Words FOSS لـ .NET، باستخدام Document.BuiltInDocumentProperties و Document.CustomDocumentProperties، وكلاهما في النهاية مبنيان على نفس تمثيل DocumentProperty.
دليل خطوة بخطوة
الخطوة 1: قراءة وتعيين خصائص المستند المدمجة
Document.BuiltInDocumentProperties يُعيد مجموعة BuiltInDocumentProperties. نظرًا لأنها مجموعة ثابتة ومعروفة من الخصائص، تُقرأ القيم وتُكتب كأعضاء عاديين بدلاً من البحث عنها بالاسم — على سبيل المثال BuiltInDocumentProperties.Author، .Title، .Subject، .Manager، .Company، .Category، .Keywords، و.Comments للحقول الوصفية، أو .CreatedTime، .LastSavedTime، .LastPrinted، و.LastSavedBy للطوابع الزمنية. إحصاءات مثل .Characters، .CharactersWithSpaces، .Lines، و.Bytes تُعرض أيضًا بهذه الطريقة، إلى جانب .Template و.HyperlinkBase.
الخطوة 2: إضافة خاصية مستند مخصصة
Document.CustomDocumentProperties تُعيد مجموعة CustomDocumentProperties للبيانات الوصفية المعرفة من قبل التطبيق والتي لا تكون جزءًا من مجموعة Word المدمجة. استدعِ أحد التحميلات Add(name, value) مع اسم وقيمة ذات نوع — سلسلة، رقم، منطقية، أو تاريخ، اعتمادًا على أي تحميل يطابق نوع القيمة — لإنشاء خاصية جديدة.
الخطوة 3: ربط خاصية مخصصة بمحتوى المستند
بدلاً من قيمة ثابتة، يمكن لخاصية مخصصة تتبع نطاق محتوى معلم بإشارة مرجعية بحيث تظل قيمتها متزامنة مع ذلك المحتوى. استدعِ CustomDocumentProperties.AddLinkToContent(name, linkSource)، مع تمرير اسم الإشارة المرجعية كـ linkSource، بدلاً من إعادة مزامنة الخاصية الثابتة يدويًا كلما تغيّر المحتوى المرتبط.
الخطوة 4: البحث عن الخصائص، التحقق منها، وإزالتها
كلا من BuiltInDocumentProperties وCustomDocumentProperties يُشتقان من الفئة المجردة DocumentPropertyCollection، لذا يتم فحصهما بنفس الطريقة: الفهرسة بالاسم (مثلاً properties[name]) تسترجع خاصية، Contains(name) تتحقق مما إذا كانت موجودة، IndexOf(name) تُعيد موقعها، وCount تُبلغ عن عدد الخصائص التي تحتويها المجموعة. استدعِ Contains(name) قبل الفهرسة بالاسم عندما قد لا تكون الخاصية المخصصة موجودة، لتجنب معالجة خاصية مفقودة كمسار استثناء. احذف خاصية باستخدام Remove(name) أو RemoveAt(index)، أو امسح جميع الخصائص في المجموعة باستخدام Clear().
الخطوة 5: قراءة قيمة خاصية مخصصة دون معرفة نوعها مسبقًا
لدى DocumentProperty Name، وValue غير مكتوب النوع، وType — قيمة تعداد PropertyType: Boolean، DateTime، Double، Number، String، StringArray، ObjectArray، ByteArray أو Other. نظرًا لأن Value غير مكتوب النوع، استخدم accessor المكتوب النوع المطابق بدلاً من التحويل المباشر: ToInt()، ToDouble()، ToDateTime()، ToBool()، ToByteArray() أو ToString(). تحقق من IsLinkToContent وLinkSource لمعرفة ما إذا كانت الخاصية مرتبطة بمحتوى المستند (انظر الخطوة 3) بدلاً من احتواء قيمة ثابتة.
الخطوة 6: التحقق من حالة حماية المستند
BuiltInDocumentProperties.Security يُبلغ عن قيمة DocumentSecurity تصف بيانات التعريف الخاصة بالحماية المخزنة للوثيقة: None، PasswordProtected، ReadOnlyRecommended، ReadOnlyEnforced أو ReadOnlyExceptAnnotations. اقرأ هذه الخاصية قبل اتخاذ القرار بما إذا كان هناك حاجة لمعالجة إضافية متعلقة بالحماية على وثيقة محمَّلة.
المشكلات الشائعة والحلول
فهرسة a CustomDocumentProperties المجموعة حسب الاسم لا تُعيد شيئًا قابلاً للاستخدام. الخاصية غير موجودة في هذا المستند. استدعِ Contains(name) أولاً، أو أضف الخاصية بالملائمة Add(name, value) التجاوز.
قراءة قيمة الخاصية المخصصة تُعطي النوع الخاطئ. DocumentProperty.Value بدون نوع object; المتصل افترض نوعًا لا يتطابق Type. استخدم accessor المكتوب بالنوع المقابل (ToInt(), ToDouble(), ToDateTime(), ToBool(), ToByteArray()) بناءً على DocumentProperty.Type.
قيمة خاصية مخصصة مرتبطة تبدو قديمة. الخاصية مرتبطة عبر AddLinkToContent، وتغيّر المحتوى المعلّم. تأكد من linkSource ما زال العلامة تحدد النطاق الذي يجب أن يغذي قيمة الخاصية.
إحصائيات الكلمات مثل Characters or Lines لا تتطابق مع المحتوى الحالي الفعلي للمستند. الإحصاءات المدمجة تعكس البيانات الوصفية المخزنة، وليس إحصاءً حياً. أعد الحساب وتحديث القيم ذات الصلة BuiltInDocumentProperties القيم إذا كان هناك حاجة إلى عدد محدث.
الأسئلة الشائعة
كيف يمكنني قراءة أو تعيين مؤلف المستند وعنوانه؟
استخدم Document.BuiltInDocumentProperties.Author و.Title مباشرة — فهما خصائص نصية عادية في مجموعة BuiltInDocumentProperties التي يتم الوصول إليها من Document.BuiltInDocumentProperties.
كيف يمكنني إضافة بيانات تعريف خاصة بالتطبيق ليست خاصية Word قياسية؟
استخدم Document.CustomDocumentProperties.Add(name, value) مع اسم الخاصية وقيمتها؛ يتم اختيار التحميل المتطابق Add بناءً على نوع القيمة.
ما الفرق بين BuiltInDocumentProperties وCustomDocumentProperties؟
BuiltInDocumentProperties هو مجموعة الحقول القياسية للبيانات الوصفية الثابتة في Word، يتم الوصول إليها كأعضاء مسمى. CustomDocumentProperties هي مجموعة مسماة مفتوحة من قيم DocumentProperty للبيانات الوصفية المعرفة من قبل التطبيق، يتم الوصول إليها بالاسم عبر الفهرس (مثال: properties[name]) وContains.
كيف يمكنني جعل خاصية مخصصة تتبع جزء من محتوى المستند بدلاً من قيمة ثابتة؟
استخدم CustomDocumentProperties.AddLinkToContent(name, linkSource)، مع تمرير اسم إشارة مرجعية كـ linkSource؛ ثم تعكس قيمة الخاصية ذلك المحتوى المرجعي.
كيف يمكنني التحقق مما إذا كان المستند محميًا بكلمة مرور؟
اقرأ Document.BuiltInDocumentProperties.Security، وهي قيمة DocumentSecurity؛ يشير PasswordProtected إلى أن بيانات التعريف المخزنة للمستند تُعلن عن حماية بكلمة مرور.
