معلومات المستند

معلومات المستند

يُظهر هذا الدليل كيفية قراءة وكتابة بيانات تعريف المستند باستخدام Aspose.Words FOSS لـ .NET. كل Document مُحمَّل أو مُنشأ حديثًا يحمل نوعين من بيانات التعريف إلى جانب محتواه: مجموعة ثابتة من الخصائص المدمجة (المؤلف، العنوان، عدد الكلمات، وما إلى ذلك) ومجموعة غير محدودة من الخصائص المخصصة التي تُعرِّفها بنفسك. كما يُطبق Aspose.Words FOSS لـ .NET حقول Word التي تُظهر هذه البيانات داخل متن المستند — AUTHOR، COMMENTS، وDOCPROPERTY — بحيث يمكن أن تظهر قيم الخصائص كنص حي يمكن تحديثه.

خصائص المستند المدمجة

يقوم Document.BuiltInDocumentProperties بإرجاع مجموعة BuiltInDocumentProperties تحتوي على خاصية واحدة لكل حقل بيانات تعريف Word القياسي: Author، Title، Subject، Comments، Category، Company، Manager، Keywords، CreatedTime، LastSavedTime، LastSavedBy، LastPrinted، RevisionNumber، TotalEditingTime، وإحصائيات مثل Pages، Words، Characters، CharactersWithSpaces، Paragraphs، وLines. نظرًا لأن BuiltInDocumentProperties مشتق من DocumentPropertyCollection، فهو يدعم أيضًا البحث بالاسم عبر الفهرس الخاص به، Contains()، IndexOf()، والتعداد عبر GetEnumerator(). تُعرض نفس المجموعة على PlainTextDocument.BuiltInDocumentProperties عند العمل مع مدخل نص عادي.

خصائص المستند المخصصة

يقوم Document.CustomDocumentProperties بإرجاع مجموعة CustomDocumentProperties للخصائص التي يحددها التطبيق نفسه — أزواج اسم/قيمة عشوائية يخزنها Word إلى جانب المجموعة المدمجة. أضف خاصية باستخدام Add(name, value)، والتي تُحمَّل عبر CustomDocumentProperties لأنواع القيم التي يمكن للخاصية أن تحملها؛ استرجع واحدة بالاسم عبر الفهرس، مثال properties[name]؛ واحذف الإدخالات باستخدام Remove(name) أو RemoveAt(index) أو Clear(). يقوم AddLinkToContent(name, linkSource) بإنشاء خاصية تكون قيمتها مرتبطة بإشارة مرجعية أو نطاق داخل المستند بدلاً من أن تُخزن كقيمة ثابتة.

كل إدخال في أي من المجموعتين — المدمجة أو المخصصة — هو DocumentProperty، الذي يكشف عن Name وValue وType (قيمة PropertyType: String أو Number أو Double أو Boolean أو DateTime أو StringArray أو ObjectArray أو ByteArray أو Other)، بالإضافة إلى IsLinkToContent وLinkSource للخصائص المرتبطة. يوفر DocumentProperty مساعدات تحويل مثل ToString() وToInt() وToDouble() وToDateTime() وToBool() وToByteArray() لاسترجاع القيمة الأساسية بالنوع .NET المطلوب.

حقول معلومات المستند

ثلاث فئات فرعية من Field تكشف عن بيانات تعريف المستند كحقول داخل جسم المستند نفسه: FieldAuthor (حقل AUTHOR، مع خاصية AuthorName)، FieldComments (حقل COMMENTS، مع خاصية Text)، وFieldDocProperty (حقل DOCPROPERTY، الذي يقرأ خاصية مستند مسماة — مدمجة أو مخصصة — إلى المستند). مثل كل Field، تشترك هذه الثلاثة في دورة حياة Field الأساسية: GetFieldCode() لقراءة رمز الحقل الأساسي، Result / DisplayResult لقراءة القيمة المحسوبة الأخيرة، Update() لإعادة حساب القيمة، Unlink() لاستبدال الحقل بنتيجته الثابتة، وRemove() لحذفها. أدخل حقل معلومات المستند باستخدام DocumentBuilder.InsertField(fieldCode) — على سبيل المثال رمز حقل AUTHOR أو DOCPROPERTY "Company" — أو باستخدام التحميل الزائد InsertField(fieldType, updateField) باستخدام قيمة FieldType مثل FieldType.FieldAuthor، FieldType.FieldComments، أو FieldType.FieldDocProperty.

نظرًا لأن FieldDocProperty يقرأ أي خاصية مستند يتم ربطه بها، فإن تغيير القيمة الأساسية لـ BuiltInDocumentProperties أو CustomDocumentProperties ثم استدعاء Update() — أو Document.UpdateFields() لتحديث جميع الحقول في المستند مرة واحدة — ينقل القيمة الجديدة إلى النتيجة المعروضة للحقل.

نصائح وأفضل الممارسات

• قم بتعيين الخصائص المدمجة مثل Title وAuthor وSubject قبل الحفظ — حيث يقرأ Word والمستهلكون الآخرون هذه القيم من BuiltInDocumentProperties لقوائم المستندات وفهرسة البحث.
• استخدم DocumentProperty.Type للتحقق من PropertyType الخاص بالخاصية قبل استدعاء أداة تحويل محددة (ToInt()، ToDateTime()، إلخ) لتجنب عدم توافق التحويل في خاصية لم تقم بإنشائها بنفسك.
• AddLinkToContent() يحافظ على تزامن خاصية مخصصة مع محتوى المستند (مثل نطاق معلم) بدلاً من قيمة ثابتة — استخدمها عندما يجب أن تعكس الخاصية دائمًا ما هو موجود حاليًا في المستند.
• استدعِ Document.UpdateFields() بعد تغيير خصائص المستند حتى تلتقط أي حقول FieldDocProperty أو FieldAuthor أو FieldComments موجودة بالفعل في جسم المستند القيم الجديدة.
• BuiltInDocumentProperties و CustomDocumentProperties متاحان كلاهما على PlainTextDocument وكذلك على Document، لذا يتم نقل البيانات الوصفية حتى عندما يكون المحتوى المحمَّل نصًا عاديًا.

المشكلات الشائعة

FAQ

ما الفرق بين خصائص المستند المدمجة والخصائص المخصصة؟

الخصائص المدمجة (Document.BuiltInDocumentProperties) هي مجموعة ثابتة معرفة بتنسيق OOXML — Author، Title، Pages، وما إلى ذلك. الخصائص المخصصة (Document.CustomDocumentProperties) هي مجموعة غير محدودة، يحددها التطبيق، من أزواج الاسم/القيمة تُضاف باستخدام Add().

كيف أجعل الخاصية المخصصة تتعقب محتوى المستند بدلاً من قيمة ثابتة؟

استخدم CustomDocumentProperties.AddLinkToContent(name, linkSource)، الذي يربط قيمة الخاصية بإشارة مرجعية أو نطاق في المستند بدلاً من تخزين قيمة ثابتة.

هل يؤدي تحديث خاصية المستند إلى تحديث الحقول التي تعرضها تلقائيًا؟

لا — استدعِ Update() على الحقل المحدد أو Document.UpdateFields() لإعادة حساب كل حقل في المستند، بما في ذلك حالات FieldDocProperty وFieldAuthor وFieldComments.

هل يمكنني قراءة خصائص المستند من مستند نص عادي؟

نعم. يُظهر PlainTextDocument نفس خصائص BuiltInDocumentProperties وCustomDocumentProperties كما في Document.

API Reference ملخص

انظر أيضاً

• Aspose.Words for .NET — Enterprise Documentation