FormsApi.setValues()
Sets fields by fully qualified name and resolves to a SetFieldResult; nothing is thrown for a field, a value of the wrong kind included. Every field is read_only when the document forbids filling it in — by its permissions, or by a certification that allows no changes. Needs the forms feature.
The rules, which a viewer open on the document applies through its fields: a text field keeps as many characters as its length limit allows; a formatted field (number, percentage, date, time, phone…) takes what its format accepts when typed, a date also as YYYY-MM-DD; a check box or radio group takes the export value of the widget to turn on, 'Off' or '' turning all off (a radio group that cannot be turned off refuses 'Off'); a dropdown or list box takes one of its options — a multi-select list box its choices as an array ([] clears it; '' clears any list box), and '' is taken for a dropdown only when it holds no choice (a dropdown cannot be emptied); an array of more than one for a field that takes one is invalid_value; a comb field distributes characters as typing would, up to its length limit. Without a viewer a password field is refused (unsupported_type): a file never keeps a password field's text.
Signature
Parameters
| Parameter | Type | Description |
|---|---|---|
| values | Record<string, FormValue | boolean> | By fully qualified name — a string, an array of strings for a multi-select list box, or a boolean: true turns a check box on (its export value), false turns a check box or radio group off ('Off'); true for a radio group is invalid_value, since a group has no one "on". |
Returns
Promise<SetFieldResult> applied names and rejected ones with a reason: unknown_field, read_only, invalid_value or unsupported_type (exported as SetFieldRejection.UNKNOWN_FIELD, .READ_ONLY, …).
Throws
FEATURE_NOT_LICENSED— the license lacksforms.DOCUMENT_CLOSED— the document has been closed.EXPORT_FAILED— with no viewer open, the document could not be saved to keep a formatted field's value as entered, or, on the form's first write, to name a font every reader has for its fields.INVALID_STATE— a progressive document still downloading.
Example
const { applied, rejected } = await doc.forms.setValues({ 'topmostSubform[0].Page1[0].f1_01[0]': 'Ada Lovelace', 'topmostSubform[0].Page1[0].c1_1[0]': true, // a check box, on }); for (const { name, reason } of rejected) console.warn(name, reason);