کار با خصوصیات سند

کار با ویژگی‌های سند

این راهنما نشان می‌دهد چگونه متادیتای یک سند 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 نیست، باز می‌گرداند. چندین overload Add(name, value) یک ویژگی جدید را از یک نام و یک مقدار تایپی (رشته، عدد، بولی یا تاریخ، بسته به overload) ایجاد می‌کنند، و 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 (یک مقدار enum 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 متفاوت باشد.
• قبل از دسترسی به هر یک از مجموعه‌های ویژگی‌ها بر اساس نام (مثلاً properties[name])، Contains(name) را بررسی کنید وقتی ممکن است ویژگی وجود نداشته باشد، تا از پردازش حالت عدم وجود ویژگی به‌عنوان مسیر استثنا جلوگیری کنید.
• از CustomDocumentProperties.AddLinkToContent(name, linkSource) استفاده کنید وقتی مقدار یک ویژگی سفارشی باید همیشه بخشی نشانه‌دار شده از سند را بازتاب دهد، به‌جای اینکه به‌صورت دستی ویژگی سفارشی ثابت را هر بار که آن محتوا تغییر می‌کند، همگام‌سازی کنید.
• آمار BuiltInDocumentProperties (Words، Characters، Pages و مشابه آن) را به‌عنوان مقادیری که در متادیتای فایل ذخیره شده‌اند، در نظر بگیرید نه به‌عنوان شمارش‌های همیشه زنده محاسبه‌شده — در صورت تغییر سند از زمان آخرین نوشتن، آن‌ها را به‌صورت صریح تازه‌سازی کنید.
• متغیر BuiltInDocumentProperties.Security را بخوانید تا وضعیت اعلام‌شدهٔ حفاظت سند را بررسی کنید قبل از این که تصمیم بگیرید آیا پردازش‌های مرتبط با حفاظت بیشتری لازم است یا خیر.

مسائل رایج

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 خلاصه

همچنین ببینید:

• Aspose.Words for .NET — Enterprise Documentation