فیلدهای فرم قدیمی
فیلدهای فرم قدیمی
Aspose.Words منبع باز برای .NET فیلدهای فرم قدیمی (پیش از کنترل محتوا) ورد را می‌خواند و دستکاری می‌کند — فیلدهای ورودی متن، چک‌باکس و کشویی — از طریق کلاس FormField و سه زیرکلاس تخصصی فیلد آن در Aspose.Words.Fields.
خواندن مقادیر فیلدهای فرم
Document.Range.FormFields (یک FormFieldCollection) دسترسی مستقیم به هر فیلد فرم قدیمی در یک بازه را بدون پیمایش دستی درخت گره فراهم می‌کند. هر FormField شامل Name (شناسه به-صورت بوکمارک که برای ارجاع به فیلد استفاده می‌شود)، Type (یک مقدار FieldType که نوع فیلد فرم را مشخص می‌کند)، Result (مقدار فعلی)، Enabled، و متن راهنما/وضعیت از طریق HelpText/OwnHelp و StatusText/OwnStatus می‌شود. SetTextInputValue(newValue) مقدار جدیدی را برای فیلد ورودی متن به‌صورت مستقیم تنظیم می‌کند. با ایندکس‌گذاری در FormFieldCollection بر اساس نام بوکمارک (مثلاً formFields["BookmarkName"]) می‌توانید فیلد خاصی را بازیابی کنید، و Remove(formField) / RemoveAt(index) فیلدها را از مجموعه حذف می‌کند.
انواع فیلدهای متن، چک‌باکس و کشویی
سه نوع فیلد فرم قدیمی هر کدام کلاس اختصاصی خود را دارند: FieldFormText (فیلد FORMTEXT که با FieldType.FieldFormTextInput مطابقت دارد) برای ورودی متن آزاد، FieldFormCheckBox (فیلد FORMCHECKBOX) برای تغییر حالت بولی، و FieldFormDropDown (فیلد FORMDROPDOWN) برای لیست انتخابی. در گره پایهٔ FormField، TextInputType (یک مقدار TextFormFieldType — Regular، Number، Date، CurrentDate، CurrentTime یا Calculated) و TextInputFormat نحوهٔ تفسیر و قالب‌بندی مقدار فیلد متن را کنترل می‌کنند؛ MaxLength طول ورودی آن را محدود می‌کند؛ TextInputDefault مقدار پیش‌فرض آن را فراهم می‌کند. Checked و Default برای فیلدهای چک‌باکس اعمال می‌شوند، به‌همراه IsCheckBoxExactSize/CheckBoxSize که اندازهٔ رندر شدهٔ آن را تنظیم می‌کند. فیلدهای کشویی لیست گزینه‌های خود را در DropDownItems نگه می‌دارند، یک DropDownItemCollection که از Add، Insert، Remove، Contains و IndexOf پشتیبانی می‌کند، به‌علاوهٔ DropDownSelectedIndex برای مورد انتخاب‌شدهٔ فعلی.
نکات و بهترین روش‌ها
- به جای فیلتر کردن دستی
Document.Range.Fieldsبر اساس نوع، ازDocument.Range.FormFieldsاستفاده کنید — این نقطه ورودی مستقیم و تایپ‌شده برای فیلدهای فرم قدیمی است. - زمانی که مقدار یک فیلد فرم باید محاسبه مجدد فیلدهای وابسته را به محض خروج کاربر از آن فعال کند،
CalculateOnExitرا تنظیم کنید. FormField.EntryMacro/ExitMacroبه نام‌های ماکرو VBA که در سند اصلی پیکربندی شده‌اند اشاره دارند — خواندن آن‌ها هیچ کد ماکرویی را اجرا نمی‌کند.- قبل از تجزیه
Resultیک فیلد متنی به عنوان عدد یا تاریخ،TextInputTypeرا بررسی کنید — فیلدهایRegularهیچ محدودیت فرمت‌ای اعمال نمی‌کنند.
مسائل رایج
| مشکل | دلیل | رفع |
|---|---|---|
نمایه‌سازی FormFieldCollection بر اساس نام نشانک مقدار null برمی‌گرداند | نام نشانک فیلد فرم مطابقت ندارد، یا فیلد در محدوده جستجو وجود ندارد | در حین شمارش، نام دقیق نشانک را از طریق FormField.Name تأیید کنید |
وضعیت چک‌باکس پس از تنظیم Checked منعکس نمی‌شود | سند پس از تغییر ذخیره نمی‌شود | پس از تغییر، سند را ذخیره کنید؛ Checked در دسترسی بعدی خوانده می‌شود |
فهرست کشویی DropDownSelectedIndex خارج از محدوده است | اندیس با هیچ موردی در DropDownItems مطابقت ندارد | قبل از تنظیم، اندیس را نسبت به DropDownItems.Count اعتبارسنجی کنید |
| مقدار فیلد متنی اعمال نشد | به جای SetTextInputValue، از انتساب مستقیم ویژگی استفاده شد | متد SetTextInputValue(newValue) را بر روی FormField فراخوانی کنید |
FAQ
تفاوت FormField و FieldFormText/FieldFormCheckBox/FieldFormDropDown چیست؟
FormField گرهٔ عمومی است که هر فیلد فرم قدیمی را نمایندگی می‌کند و از طریق Document.Range.FormFields قابل دسترسی است. FieldFormText، FieldFormCheckBox و FieldFormDropDown کلاس‌های مخصوص به فیلد هستند (که از Field ارث می‌برند) برای هر نوع فیلد هنگامی که به‌جای آن از مجموعهٔ عمومی Field استفاده می‌کنید.
چگونه می‌توانم تمام مقادیر فیلدهای فرم را در یک سند دریافت کنم؟
فهرست Document.Range.FormFields را تهیه کنید و Name/Result را در هر FormField بخوانید.
آیا می‌توانم گزینه‌ها را به یک فیلد فرم کشویی اضافه کنم؟
بله — FormField.DropDownItems یک DropDownItemCollection است که دارای Add(value)، Insert(index, value) و Remove(name) می‌باشد.
آیا این‌ها همان کنترل‌های محتوای مدرن هستند؟
نه. فیلدهای فرم قدیمی (FORMTEXT، FORMCHECKBOX، FORMDROPDOWN) پیش از مدل برچسب سند ساختاری ورد (کنترل محتوا) وجود داشتند؛ هر دو می‌توانند در یک سند ظاهر شوند.
API Reference خلاصه
| کلاس / متد | توضیح |
|---|---|
Document.Range.FormFields | دسترسی مستقیم به تمام فیلدهای فرم‌های قدیمی در یک بازه |
FormField | گرهٔ عمومی فرم قدیمی: نام، نوع، نتیجه، وضعیت فعال |
FormFieldCollection | مجموعه‌ای از اشیای FormField؛ ایندِکس‌کننده بر اساس نام نشانک، Remove() |
FieldFormText | کلاس فیلد FORMTEXT |
FieldFormCheckBox | کلاس فیلد FORMCHECKBOX |
FieldFormDropDown | کلاس فیلد FORMDROPDOWN |
TextFormFieldType | Enum برای قالب ورودی فیلد متن (Regular, Number, Date, و غیره.) |
DropDownItemCollection | لیست قابل ویرایش گزینه‌های فیلد کشویی |
