Forms
بررسی کلی
این صفحه به ایجاد و مدیریت فیلدهای تعاملی AcroForm میپردازد. Form، که از طریق doc.Form دسترسی مییابد، واسط تمام انواع فیلد است؛ هر متد Add*() یک فیلد مرتبط با یک صفحه و یک مستطیل ویجت ایجاد میکند و یک دستگیرهٔ نوعی (TextField, CheckboxField, ChoiceField, ButtonField یا RadioField) برمیگرداند که ویژگیهای مشترک Field شامل Value، ReadOnly و Required را دارد.
ایجاد فیلدها
Form.AddTextField()، Form.AddCheckbox()، Form.AddComboBox() و همپیوستگانشان هر کدام یک شیء گزینهها میپذیرند که page هدف (صفرپایه) را نامگذاری میکند، rect ویجت، یک name فیلد، و استایلهایی مانند borderColor و backgroundColor.
const form = doc.Form;
const pageNum = page.Number;
form.AddTextField({
page: pageNum, rect: [200, 670, 450, 690], name: 'FullName', value: 'Alice Sample',
borderColor: [0.05, 0.1, 0.3], backgroundColor: [0.9, 0.93, 1], borderWidth: 1,
font: 'Helvetica', fontSize: 12,
});
form.AddCheckbox({
page: pageNum, rect: [200, 630, 218, 648], name: 'Subscribe',
checked: true, borderColor: [0.05, 0.1, 0.3], borderWidth: 1,
});
form.AddComboBox({
page: pageNum, rect: [200, 550, 350, 570], name: 'Country', value: 'US',
options: [
{ export: 'US', display: 'United States' },
{ export: 'UK', display: 'United Kingdom' },
{ export: 'DE', display: 'Germany' },
],
});Page.AddTextField() و Page.AddCheckbox() انواع فیلد یکسان را مستقیماً روی یک صفحه ایجاد میکنند، بدون اینکه doc.Form یا شمارهٔ page را در شیء گزینهها نام ببرند.
خواندن و تغییر فیلدها
Form.Fields یک آرایه از تمام Fieldهای موجود در سند است؛ Form.Get() یکی را بر اساس نام کاملاً تعیینشدهاش جستجو میکند. Value هر فیلد میتواند خوانده یا دوباره مقداردهی شود، و ReadOnly / Required ویژگیهای بولی سادهای هستند.
const nameField = doc.Form.Get('FullName');
if (nameField) {
console.log(nameField.Value);
nameField.Value = 'Bob Sample';
}تسطیح فیلدها
هر متد Flatten() از نوع فیلد، ظاهر فعلی آن را در محتوای ثابت صفحه میپذیرد و آن را از AcroForm حذف میکند — همان اثر دائمی و غیرقابل تعامل که Annotation.Flatten() برای حاشیهنویسیها دارد.
const tb = form.AddTextField({
page: pageNum, rect: [210, 660, 460, 680], name: 'FlattenName', value: 'Alice Sample',
});
tb.Flatten();نکات و بهترین شیوهها
- دستگیره فیلد را که مستقیماً توسط فراخوانی
Add*()بازگردانده میشود، یا دستگیرهای که تازه باForm.Get()جستجو میکنید، اصلاح کنید — یک ارجاع قدیمی تغییرات اعمالشده در جای دیگر را نمیبیند. Form.RemoveField()یک دستگیرهFieldیا رشته نام فیلد را میپذیرد.- پس از تغییر مقادیر فیلدها به صورت دستهای،
Form.GenerateAppearances()را فراخوانی کنید تا ظاهر روی-صفحه هر فیلد باValueآن هماهنگ بماند. - جعبههای ترکیبی و جعبههای لیستی مقدار انتخابشده
exportرا در/Vذخیره میکنند؛ متنdisplayهمان چیزی است که ظاهر تولید شده نشان میدهد.
مشکلات رایج
| مشکل | دلیل | رفع |
|---|---|---|
فیلدی که با Form.AddTextField() اضافه شده است در صفحه ظاهر نمیشود | مختصات rect خارج از ابعاد صفحه هدف هستند | تأیید کنید که مستطیل در محدودههای صفحه قرار دارد |
فیلد پس از Flatten() هنوز بهصورت تعاملی ظاهر میشود | Flatten() روی یک کپی فراخوانی شد نه روی هندل Add*() / Form.Get() که برگردانده شد | فراخوانی Flatten() بر روی شیءای که مستقیماً از فرم بهدست آمده |
| تغییر مقدار فیلد روی صفحه قابل مشاهده نیست | ظاهر فیلد پس از تغییر مقدار دوباره تولید نشد | فراخوانی Form.GenerateAppearances()، یا GenerateAppearance() خود فیلد |
FAQ
چگونه میتوانم مقدار یک فیلد را پس از ایجاد آن بخوانم یا تغییر دهم؟
با استفاده از Form.Get('fieldName') آن را جستجو کنید (یا از هندل که فراخوانی Add*() برگرداند استفاده کنید) و مستقیماً ویژگی Value آن را بخوانید یا مقداردهی کنید.
رابط فرم چه انواع فیلدهایی را پشتیبانی میکند؟
فیلدهای متنی، چکباکسها، گروههای رادیویی، جعبههای ترکیبی، جعبههای لیست و دکمههای فشاردهی، از طریق Form.AddTextField()، Form.AddCheckbox()، Form.AddRadioGroup()، Form.AddComboBox()، Form.AddListBox() و Form.AddPushButton().
چگونه یک فیلد را حذف کنم؟
با فراخوانی Form.RemoveField() همراه با هندل فیلد یا نام آن اقدام کنید.
چگونه یک فیلد فرم را دائم و غیرقابل ویرایش میکنیم؟
دستور Flatten() را روی دسته فیلد فراخوانی کنید — همان الگویی که برای حاشیهنویسیها استفاده میشود — که ظاهر فعلی آن را در صفحه پخت میکند و از AcroForm حذف مینماید.
API Reference خلاصه
| کلاس/متد | توضیح |
|---|---|
Form | AcroForm facade، که از طریق doc.Form دسترسی میشود |
Form.AddTextField() / Form.AddCheckbox() / Form.AddRadioGroup() / Form.AddComboBox() / Form.AddListBox() / Form.AddPushButton() | یک فیلد از نوع مربوطه ایجاد کنید |
Form.Fields | هر Field در سند، به صورت آرایه |
Form.Get() | یک فیلد را با نام کامل آن جستجو کنید |
Form.RemoveField() | یک فیلد را با هندل یا نام آن حذف کنید |
Form.GenerateAppearances() | ظاهر روی صفحه برای هر فیلد را بازسازی کنید |
TextField / CheckboxField / ChoiceField / ButtonField / RadioField | هندلهای فیلدهای تایپشده که Value، ReadOnly، Required را به اشتراک میگذارند |
Page.AddTextField() / Page.AddCheckbox() | یک فیلد را مستقیماً روی یک صفحه ایجاد کنید |