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

کلاس/متدتوضیح
FormAcroForm 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()یک فیلد را مستقیماً روی یک صفحه ایجاد کنید

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

 فارسی