اطلاعات سند
اطلاعات سند
این راهنما نشان می‌دهد چگونه متادیتای سند را با 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موجود هستند، بنابراین فراداده حتی وقتی محتوای بارگذاری‌شده متن ساده است، به‌صورت round-trip منتقل می‌شود.
مسائل رایج
| مشکل | دلیل | راه‌حل |
|---|---|---|
ایندکس‌کننده برای یک ویژگی سفارشی null را برمی‌گرداند | ویژگی هنوز اضافه نشده است | ابتدا CustomDocumentProperties.Add(name, value) را فراخوانی کنید، یا قبل از خواندن Contains(name) را بررسی کنید |
FieldDocProperty پس از تغییر یک ویژگی مقدار منقضی‌شده‌ای نشان می‌دهد | فیلد به‌روزرسانی نشده بود | متد Update() را روی فیلد فراخوانی کنید، یا Document.UpdateFields() را برای تازه‌سازی همه فیلدها در سند اجرا کنید |
DocumentProperty.ToInt() / ToDateTime() استثنا می‌اندازد | مقدار واقعی Type خاصیت با تبدیل درخواست‌شده مطابقت ندارد | قبل از انتخاب کمکی که باید برای تبدیل صدا بزنید، DocumentProperty.Type را بررسی کنید |
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 خلاصه
| کلاس / متد | توضیح |
|---|---|
Document.BuiltInDocumentProperties | مجموعه استاندارد متادیتای OOXML (Author، Title، Pages، و غیره) |
Document.CustomDocumentProperties | مجموعهٔ ویژگی‌های نام/مقدار تعریف‌شده توسط برنامه |
CustomDocumentProperties.Add() / فهرست‌ساز بر اساس نام / AddLinkToContent() | افزودن، بازیابی یا لینک‌دادن به محتوا برای یک ویژگی سفارشی |
DocumentProperty | ورودی تک‌ویژگی؛ Value، Type، و ToString()/ToInt()/ToDouble()/ToDateTime()/ToBool()/ToByteArray() ابزارهای تبدیل |
FieldAuthor / FieldComments / FieldDocProperty | AUTHOR، COMMENTS و DOCPROPERTY فیلدها؛ Update()، Result، GetFieldCode() |
DocumentBuilder.InsertField() | فیلدی را با کد فیلد یا FieldType وارد می‌کند |
