چگونه با ویژگی‌های سند در .NET کار کنیم
نحوه کار با ویژگی‌های سند در .NET
هر سند Word دو دسته متادیتا دارد — فیلدهای استانداردی که Word برای هر فایل ردیابی می‌کند، و هر مقدار تعریف‌شده توسط برنامه‌ای که افزوده است. این راهنما نشان می‌دهد چگونه هر دو را با Aspose.Words FOSS برای .NET بخوانید و تنظیم کنید، با استفاده از Document.BuiltInDocumentProperties و Document.CustomDocumentProperties، که هر دو در نهایت بر پایهٔ همان نمایش DocumentProperty ساخته شده‌اند.
راهنمای گام‌به‌گام
گام ۱: خواندن و تنظیم ویژگی‌های داخلی سند
Document.BuiltInDocumentProperties یک مجموعهٔ BuiltInDocumentProperties برمی‌گرداند. از آنجا که این مجموعهٔ ثابتی از ویژگی‌هاست که شناخته شده‌اند، مقادیر به‌عنوان اعضای عادی خوانده و نوشته می‌شوند نه اینکه بر اساس نام جستجو شوند — برای مثال BuiltInDocumentProperties.Author، .Title، .Subject، .Manager، .Company، .Category، .Keywords و .Comments برای فیلدهای توصیفی، یا .CreatedTime، .LastSavedTime، .LastPrinted و .LastSavedBy برای زمان‌سنج‌ها. آمارهایی مانند .Characters، .CharactersWithSpaces، .Lines و .Bytes نیز به همین شکل در دسترس هستند، همراه با .Template و .HyperlinkBase.
گام ۲: افزودن یک ویژگی سفارشی سند
Document.CustomDocumentProperties یک مجموعه CustomDocumentProperties برمی‌گرداند برای فراداده‌های تعریف‌شده توسط برنامه که بخشی از مجموعه پیش‌فرض Word نیستند. یکی از overloadهای Add(name, value) را با یک نام و مقدار دارای نوع — رشته، عدد، بولی یا تاریخ، بسته به این که کدام overload با نوع مقدار مطابقت دارد — صدا بزنید تا یک ویژگی جدید ایجاد کنید.
مرحله 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 است — یک مقدار enum PropertyType: Boolean، DateTime، Double، Number، String، StringArray، ObjectArray، ByteArray یا Other. چون Value بدون نوع است، به‌جای تبدیل مستقیم، از accessor متناسب با نوع استفاده کنید: ToInt()، ToDouble()، ToDateTime()، ToBool()، ToByteArray() یا ToString(). برای فهمیدن اینکه آیا یک ویژگی به محتوای سند لینک شده است (به مرحله 3 مراجعه کنید) یا یک مقدار ثابت دارد، IsLinkToContent و LinkSource را بررسی کنید.
مرحله 6: بررسی وضعیت محافظت سند
BuiltInDocumentProperties.Security یک مقدار DocumentSecurity گزارش می‌دهد که متادیتای حفاظت ذخیره‌شده سند را توصیف می‌کند: None، PasswordProtected، ReadOnlyRecommended، ReadOnlyEnforced یا ReadOnlyExceptAnnotations. قبل از تصمیم‌گیری دربارهٔ نیاز به پردازش‌های مرتبط با حفاظت بر روی سند بارگذاری شده، این ویژگی را بخوانید.
مشکلات رایج و راه‌حل‌ها
نمایه‌گذاری یک CustomDocumentProperties مجموعه‌ای که بر اساس نام ایندکس می‌شود، خروجی قابل استفاده‌ای ندارد. این ویژگی در این سند وجود ندارد. فراخوانی Contains(name) اول، یا ویژگی را با Add(name, value) بارگذاری.
خواندن مقدار یک ویژگی سفارشی، نوع نادرستی را برمی‌گرداند. DocumentProperty.Value بدون نوع object; فراخواننده نوعی را فرض کرده بود که مطابقت ندارد Type. از دسترسی‌گر تایپ‌شدهٔ مربوطه استفاده کنید (ToInt(), ToDouble(), ToDateTime(), ToBool(), ToByteArray()) بر اساس DocumentProperty.Type.
مقدار یک ویژگی سفارشی پیوندشده به نظر می‌رسد که به‌روز نیست. ویژگی از طریق AddLinkToContent, و محتوای نشانک‌گذاری شده تغییر کرد. تأیید کنید که linkSource نشانک هنوز محدوده‌ای را که باید مقدار ویژگی را تامین کند، علامت‌گذاری می‌کند.
آمارهای کلمه‌ای مانند Characters or Lines با محتوای واقعی فعلی سند مطابقت ندارند. آمارهای توکار متادیتای ذخیره‌شده را بازتاب می‌دهند، نه یک شمارش زنده. دوباره محاسبه کنید و موارد مربوطه را به‌روز کنید. BuiltInDocumentProperties مقادیر را اگر شمارش به‌روز مورد نیاز باشد.
سؤالات متداول
چگونه می‌توانم نویسنده و عنوان سند را بخوانم یا تنظیم کنم؟
از Document.BuiltInDocumentProperties.Author و .Title به‌صورت مستقیم استفاده کنید — آن‌ها ویژگی‌های رشته‌ای معمولی در مجموعهٔ BuiltInDocumentProperties هستند که از Document.BuiltInDocumentProperties دسترسی می‌یابند.
چگونه می‌توانم متادیتای خاص برنامه که یک ویژگی استاندارد ورد نیست را اضافه کنم؟
از Document.CustomDocumentProperties.Add(name, value) همراه با نام و مقدار ویژگی استفاده کنید؛ overload مطابقت‌دهندهٔ Add بر اساس نوع مقدار انتخاب می‌شود.
تفاوت بین BuiltInDocumentProperties و CustomDocumentProperties چیست؟
BuiltInDocumentProperties مجموعهٔ ثابت فیلدهای متادیتای استاندارد ورد است که به‌صورت اعضای نام‌گذاری‌شده دسترسی می‌شوند. CustomDocumentProperties یک مجموعهٔ باز و نام‌گذاری‌شده از مقادیر DocumentProperty برای متادیتای تعریف‌شده توسط برنامه است که با نام از طریق ایندکس‌گیر (مثلاً properties[name]) و Contains دسترسی می‌یابد.
چگونه می‌توانم یک ویژگی سفارشی را طوری تنظیم کنم که محتوای بخشی از سند را دنبال کند به جای یک مقدار ثابت؟
از CustomDocumentProperties.AddLinkToContent(name, linkSource) استفاده کنید و نام یک نشانک را به‌عنوان linkSource عبور دهید؛ مقدار ویژگی سپس محتوای نشانک‌گذاری شده را بازتاب می‌دهد.
چگونه می‌توانم بررسی کنم که آیا یک سند دارای حفاظت با رمز عبور است؟
مقدار Document.BuiltInDocumentProperties.Security را بخوانید، یک مقدار DocumentSecurity؛ PasswordProtected نشان می‌دهد که متادیتای ذخیره‌شده سند حفاظت با رمز عبور را اعلام می‌کند.
