Class TextInput
透過集合功能整理內容
你可以依據偏好儲存及分類內容。
內容詳盡的說明文件
setFieldName(fieldName)
設定事件物件中的鍵，用於在發生 UI 互動行為時，識別此文字輸入內容。使用者看不到。必要欄位，不得重複。
參數
| 名稱 | 類型 | 說明 |
fieldName | String | 用來識別此輸入內容的鍵。 |
回攻員
TextInput：這個物件用於鏈結。
setHint(hint)
設定文字輸入提示。用於為使用者提供額外輸入指引。舉例來說，提示可以說明電話號碼欄位的格式 (「xxx-xxx-xxxx」)。
參數
| 名稱 | 類型 | 說明 |
hint | String | 顯示在輸入欄位下方的文字提示。這段文字會一直顯示。 |
回攻員
TextInput：這個物件用於鏈結。
setMultiline(multiline)
設定輸入文字是否會顯示在一行或多行。
參數
| 名稱 | 類型 | 說明 |
multiline | Boolean | 多行設定。 |
回攻員
TextInput：這個物件用於鏈結。
setOnChangeAction(action)
設定每次文字輸入內容變更時要執行的動作。
參數
回攻員
TextInput：這個物件用於鏈結。
setSuggestions(suggestions)
setSuggestionsAction(suggestionsAction)
設定回呼動作，根據使用者輸入內容擷取自動完成建議。Action 參數必須指定回傳 SuggestionsResponse 物件的回呼函式。
const action = CardService.newAction()
.setFunctionName('suggestionCallback')
.setParameters({numSuggestions: 3});
CardService.newTextInput()
.setFieldName('option-field')
.setTitle('Option Selected')
.setSuggestionsAction(action);
// ...
function suggestionCallback(e) {
const suggestions = CardService.newSuggestions();
const numSuggestions = Number.parseInt(e.parameter.numSuggestions);
for (let i = 1; i <= numSuggestions; i++) {
suggestions.addSuggestion(`Suggestion ${i}`);
}
return CardService.newSuggestionsResponseBuilder()
.setSuggestions(suggestions)
.build();
}
參數
| 名稱 | 類型 | 說明 |
suggestionsAction | Action | 擷取此輸入內容建議的動作。 |
回攻員
TextInput：這個物件用於鏈結。
setTitle(title)
設定要在輸入欄位上方顯示的標題。必填。
參數
| 名稱 | 類型 | 說明 |
title | String | 這項輸入項目的文字標籤。 |
回攻員
TextInput：這個物件用於鏈結。
setValidation(validation)
設定這個小工具的驗證規則。
const validation = CardService.newValidation().setCharacterLimit('10').setType(
CardService.InputType.TEXT);
const input = CardService.newTextInput()
.setFieldName('text_name_xxx1')
.setTitle('Max 10 characters')
.setValidation(validation);
參數
回攻員
TextInput：這個物件用於鏈結。
setValue(value)
設定要設在輸入欄位的預先填入值。
參數
| 名稱 | 類型 | 說明 |
value | String | 輸入內容中的預設值。在表單回呼參數中，這項屬性一律會以字串表示。 |
回攻員
TextInput：這個物件用於鏈結。
除非另有註明，否則本頁面中的內容是採用創用 CC 姓名標示 4.0 授權，程式碼範例則為阿帕契 2.0 授權。詳情請參閱《Google Developers 網站政策》。Java 是 Oracle 和/或其關聯企業的註冊商標。
上次更新時間：2025-07-26 (世界標準時間)。
[null,null,["上次更新時間：2025-07-26 (世界標準時間)。"],[[["\u003cp\u003eTextInput is a UI element that allows users to input text within Google Workspace Add-ons and Google Chat apps.\u003c/p\u003e\n"],["\u003cp\u003eIt offers various customization options, including setting titles, hints, pre-filled values, and handling multi-line input.\u003c/p\u003e\n"],["\u003cp\u003eDevelopers can set actions triggered by text input changes or employ auto-completion with suggestions.\u003c/p\u003e\n"],["\u003cp\u003e\u003ccode\u003esetFieldName\u003c/code\u003e is a required method used to identify the TextInput element in event objects for data retrieval.\u003c/p\u003e\n"],["\u003cp\u003eEach customization method for the TextInput object returns the object itself, enabling method chaining for streamlined configuration.\u003c/p\u003e\n"]]],["The `TextInput` widget allows text input and supports form validation, blocking submission if required fields are empty. Key actions include setting a unique field name (`setFieldName`), providing user hints (`setHint`), enabling multiline input (`setMultiline`), and defining actions on text change (`setOnChangeAction`). Autocompletion is supported via suggestions (`setSuggestions`) or a callback to fetch them (`setSuggestionsAction`). You can set a title (`setTitle`), validation rules (`setValidation`), and pre-fill values (`setValue`).\n"],null,["# Class TextInput\n\nTextInput\n\nA input field widget that accepts text input.\n\nSupports form submission validation. When [Action.setAllWidgetsAreRequired(allWidgetsAreRequired)](/apps-script/reference/card-service/action#setAllWidgetsAreRequired(Boolean)) is set to\n`true` or this widget is specified through [Action.addRequiredWidget(requiredWidget)](/apps-script/reference/card-service/action#addRequiredWidget(String)), the submission\naction is blocked unless a value is entered.\n\nAvailable for Google Workspace add-ons and Google Chat apps.\n\n```javascript\nconst textInput = CardService.newTextInput()\n .setFieldName('text_input_form_input_key')\n .setTitle('Text input title')\n .setHint('Text input hint');\n``` \n\n### Methods\n\n| Method | Return type | Brief description |\n|--------------------------------------------------------------------------|----------------|--------------------------------------------------------------------------------------------------------------------|\n| [setFieldName(fieldName)](#setFieldName(String)) | [TextInput](#) | Sets the key that identifies this text input in the event object that is generated when there is a UI interaction. |\n| [setHint(hint)](#setHint(String)) | [TextInput](#) | Sets a hint for the text input. |\n| [setMultiline(multiline)](#setMultiline(Boolean)) | [TextInput](#) | Sets whether the input text shows on one line or multiple lines. |\n| [setOnChangeAction(action)](#setOnChangeAction(Action)) | [TextInput](#) | Sets an action to be performed whenever the text input changes. |\n| [setSuggestions(suggestions)](#setSuggestions(Suggestions)) | [TextInput](#) | Sets the suggestions for autocompletion in the text field. |\n| [setSuggestionsAction(suggestionsAction)](#setSuggestionsAction(Action)) | [TextInput](#) | Sets the callback action to fetch suggestions based on user input for autocompletion. |\n| [setTitle(title)](#setTitle(String)) | [TextInput](#) | Sets the title to be shown above the input field. |\n| [setValidation(validation)](#setValidation(Validation)) | [TextInput](#) | Sets the validation rule for this widget. |\n| [setValue(value)](#setValue(String)) | [TextInput](#) | Sets the pre-filled value to be set in the input field. |\n\nDetailed documentation\n----------------------\n\n### `set``Field``Name(fieldName)`\n\nSets the key that identifies this text input in the event object that is generated when there\nis a UI interaction. Not visible to the user. Required, must be unique.\n\n#### Parameters\n\n| Name | Type | Description |\n|---------------|----------|----------------------------------------------|\n| `field``Name` | `String` | The key that is used to identify this input. |\n\n#### Return\n\n\n[TextInput](#) --- This object, for chaining.\n\n*** ** * ** ***\n\n### `set``Hint(hint)`\n\nSets a hint for the text input. Used to give the user extra guidance on what to input. For\nexample, a hint could describe formatting (\"xxx-xxx-xxxx\") for a phone number field.\n\n#### Parameters\n\n| Name | Type | Description |\n|--------|----------|------------------------------------------------------------------------------|\n| `hint` | `String` | The text hint to display below the input field. This text is always visible. |\n\n#### Return\n\n\n[TextInput](#) --- This object, for chaining.\n\n*** ** * ** ***\n\n### `set``Multiline(multiline)`\n\nSets whether the input text shows on one line or multiple lines.\n\n#### Parameters\n\n| Name | Type | Description |\n|-------------|-----------|------------------------|\n| `multiline` | `Boolean` | The multiline setting. |\n\n#### Return\n\n\n[TextInput](#) --- This object, for chaining.\n\n*** ** * ** ***\n\n### `set``On``Change``Action(action)`\n\nSets an action to be performed whenever the text input changes.\n\n#### Parameters\n\n| Name | Type | Description |\n|----------|------------------------------------------------------|---------------------|\n| `action` | [Action](/apps-script/reference/card-service/action) | The action to take. |\n\n#### Return\n\n\n[TextInput](#) --- This object, for chaining.\n\n*** ** * ** ***\n\n### `set``Suggestions(suggestions)`\n\nSets the suggestions for autocompletion in the text field.\n\n#### Parameters\n\n| Name | Type | Description |\n|---------------|----------------------------------------------------------------|---------------------------------------|\n| `suggestions` | [Suggestions](/apps-script/reference/card-service/suggestions) | The collection of suggestions to use. |\n\n#### Return\n\n\n[TextInput](#) --- This object, for chaining.\n\n*** ** * ** ***\n\n### `set``Suggestions``Action(suggestionsAction)`\n\nSets the callback action to fetch suggestions based on user input for autocompletion. The\n[Action](/apps-script/reference/card-service/action) parameter must specify a callback function that returns a [SuggestionsResponse](/apps-script/reference/card-service/suggestions-response) object.\n\n```javascript\nconst action = CardService.newAction()\n .setFunctionName('suggestionCallback')\n .setParameters({numSuggestions: 3});\n\nCardService.newTextInput()\n .setFieldName('option-field')\n .setTitle('Option Selected')\n .setSuggestionsAction(action);\n\n// ...\n\nfunction suggestionCallback(e) {\n const suggestions = CardService.newSuggestions();\n const numSuggestions = Number.parseInt(e.parameter.numSuggestions);\n for (let i = 1; i \u003c= numSuggestions; i++) {\n suggestions.addSuggestion(`Suggestion ${i}`);\n }\n return CardService.newSuggestionsResponseBuilder()\n .setSuggestions(suggestions)\n .build();\n}\n```\n\n#### Parameters\n\n| Name | Type | Description |\n|-----------------------|------------------------------------------------------|-----------------------------------------------------|\n| `suggestions``Action` | [Action](/apps-script/reference/card-service/action) | The action that fetches suggestions for this input. |\n\n#### Return\n\n\n[TextInput](#) --- This object, for chaining.\n\n*** ** * ** ***\n\n### `set``Title(title)`\n\nSets the title to be shown above the input field. Required.\n\n#### Parameters\n\n| Name | Type | Description |\n|---------|----------|--------------------------------|\n| `title` | `String` | The text label for this input. |\n\n#### Return\n\n\n[TextInput](#) --- This object, for chaining.\n\n*** ** * ** ***\n\n### `set``Validation(validation)`\n\nSets the validation rule for this widget.\n\n```javascript\nconst validation = CardService.newValidation().setCharacterLimit('10').setType(\n CardService.InputType.TEXT);\n\nconst input = CardService.newTextInput()\n .setFieldName('text_name_xxx1')\n .setTitle('Max 10 characters')\n .setValidation(validation);\n```\n\n#### Parameters\n\n| Name | Type | Description |\n|--------------|--------------------------------------------------------------|-----------------------------------------------------|\n| `validation` | [Validation](/apps-script/reference/card-service/validation) | The validation rule for this [TextInput](#) widget. |\n\n#### Return\n\n\n[TextInput](#) --- This object, for chaining.\n\n*** ** * ** ***\n\n### `set``Value(value)`\n\nSets the pre-filled value to be set in the input field.\n\n#### Parameters\n\n| Name | Type | Description |\n|---------|----------|--------------------------------------------------------------------------------------------------------------|\n| `value` | `String` | The default value placed in the input. It is always represented as a string in the form callback parameters. |\n\n#### Return\n\n\n[TextInput](#) --- This object, for chaining."]]
