A question item that allows the respondent to select one choice from a drop-down list. Items can
be accessed or created from a Form.
// Open a form by ID and add a new list item.
var form = FormApp.openById('1234567890abcdefghijklmnopqrstuvwxyz');
var item = form.addListItem();
item.setTitle('Do you prefer cats or dogs?')
.setChoices([
item.createChoice('Cats'),
item.createChoice('Dogs')
]);
Methods
| Method | Return type | Brief description |
|---|---|---|
createChoice(value) | Choice | Creates a new choice. |
createChoice(value, navigationItem) | Choice | Creates a new choice with a page-navigation option that jumps to a given page-break item. |
createChoice(value, navigationType) | Choice | Creates a new choice with a page-navigation option. |
createResponse(response) | ItemResponse | Creates a new ItemResponse for this list item. |
duplicate() | ListItem | Creates a copy of this item and appends it to the end of the form. |
getChoices() | Choice[] | Gets all choices for an item. |
getHelpText() | String | Gets the item's help text (sometimes called description text for layout
items like ImageItems,
PageBreakItems, and
SectionHeaderItems). |
getId() | Integer | Gets the item's unique identifier. |
getIndex() | Integer | Gets the index of the item among all the items in the form. |
getTitle() | String | Gets the item's title (sometimes called header text, in the case of a
SectionHeaderItem). |
getType() | ItemType | Gets the item's type, represented as an ItemType. |
isRequired() | Boolean | Determines whether the respondent must answer the question. |
setChoiceValues(values) | ListItem | Sets the choices for an item from an array of strings. |
setChoices(choices) | ListItem | Sets an array of choices for an item. |
setHelpText(text) | ListItem | Sets the item's help text (sometimes called description text for layout
items like ImageItems,
PageBreakItems, and
SectionHeaderItems). |
setRequired(enabled) | ListItem | Sets whether the respondent must answer the question. |
setTitle(title) | ListItem | Sets the item's title (sometimes called header text, in the case of a
SectionHeaderItem). |
Detailed documentation
createChoice(value)
Creates a new choice.
Parameters
| Name | Type | Description |
|---|---|---|
value | String | the choice's value, which respondents see as a label when viewing the form |
Return
Choice — the new choice
createChoice(value, navigationItem)
Creates a new choice with a page-navigation option that jumps to a given page-break item. This
is equivalent to createChoice(value, navigationType) with
navigationType set to FormApp.PageNavigationType.GO_TO_PAGE. Choices that use
page navigation cannot be combined in the same item with choices that do not use page
navigation.
The page navigation occurs after the respondent completes a page that contains the option, and only if the respondent chose that option. If the respondent chose multiple options with page-navigation instructions on the same page, only the last navigation option has any effect. Page navigation also has no effect on the last page of a form.
Parameters
| Name | Type | Description |
|---|---|---|
value | String | the choice's value, which respondents see as a label when viewing the form |
navigationItem | PageBreakItem | the item to navigate to |
Return
Choice — the new choice
createResponse(response)
Creates a new ItemResponse for this list item. Throws an exception if the
response argument does not match a valid choice for this item.
Parameters
| Name | Type | Description |
|---|---|---|
response | String | a valid answer for this list item |
Return
ItemResponse — the item response
duplicate()
Creates a copy of this item and appends it to the end of the form.
Return
getHelpText()
Gets the item's help text (sometimes called description text for layout
items like ImageItems,
PageBreakItems, and
SectionHeaderItems).
Return
String — the item's help text or description text
getId()
Gets the item's unique identifier.
Return
Integer — the item's ID
getIndex()
Gets the index of the item among all the items in the form.
Return
Integer — the index of the item
getTitle()
Gets the item's title (sometimes called header text, in the case of a
SectionHeaderItem).
Return
String — the item's title or header text
isRequired()
Determines whether the respondent must answer the question.
Return
Boolean — whether the respondent must answer the question
setChoiceValues(values)
Sets the choices for an item from an array of strings. Throws an exception if the given array is empty.
// Open a form by ID and add a new list item.
var form = FormApp.openById('1234567890abcdefghijklmnopqrstuvwxyz');
var item = form.addListItem();
item.setTitle('Do you prefer cats or dogs?');
item.setChoiceValues(['Dogs', 'Cats']);
Parameters
| Name | Type | Description |
|---|---|---|
values | String[] | the array of choice values, which respondents see as labels when viewing the form |
Return
setChoices(choices)
Sets an array of choices for an item. Throws an exception if the given array is empty or
contains a null element.
// Open a form by ID and add a new list item.
var form = FormApp.openById('1234567890abcdefghijklmnopqrstuvwxyz');
var item = form.addListItem();
item.setTitle('Do you prefer cats or dogs?')
item.setChoices([
item.createChoice('Cats'),
item.createChoice('Dogs')
]);
Parameters
| Name | Type | Description |
|---|---|---|
choices | Choice[] | an array of choices |
Return
setHelpText(text)
Sets the item's help text (sometimes called description text for layout
items like ImageItems,
PageBreakItems, and
SectionHeaderItems).
Parameters
| Name | Type | Description |
|---|---|---|
text | String | the new help text |
Return
setRequired(enabled)
Sets whether the respondent must answer the question.
Parameters
| Name | Type | Description |
|---|---|---|
enabled | Boolean | whether the respondent must answer the question |
Return
ListItem — the current item (for chaining)
setTitle(title)
Sets the item's title (sometimes called header text, in the case of a
SectionHeaderItem).
Parameters
| Name | Type | Description |
|---|---|---|
title | String | the new title or header text |