Class TextInput
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
TextInput
أداة حقل إدخال تقبل إدخال نص
يتيح التحقّق من صحة عمليات إرسال النماذج. عند ضبط Action.setAllWidgetsAreRequired(allWidgetsAreRequired) على
true أو تحديد هذه الأداة من خلال Action.addRequiredWidget(requiredWidget)، يتم حظر
إجراء الإرسال ما لم يتم إدخال قيمة.
تتوفّر هذه الميزة لإضافات Google Workspace وتطبيقات Google Chat.
const textInput = CardService.newTextInput()
.setFieldName('text_input_form_input_key')
.setTitle('Text input title')
.setHint('Text input hint');
مستندات تفصيلية
setFieldName(fieldName)
تُستخدَم لضبط المفتاح الذي يحدِّد إدخال النص هذا في عنصر الحدث الذي يتم إنشاؤه عند حدوث تفاعل مع واجهة المستخدم. لا تظهر هذه البيانات للمستخدم. مطلوب، ويجب أن يكون فريدًا.
المعلمات
| الاسم | النوع | الوصف |
fieldName | String | المفتاح المستخدَم لتحديد هذا الإدخال. |
الإرجاع
TextInput: هذا العنصر، لإنشاء سلسلة.
setHint(hint)
لضبط تلميح لإدخال النص تُستخدَم هذه السمة لتقديم إرشادات إضافية للمستخدم حول ما يجب إدخاله. على سبيل المثال، يمكن أن يصف التلميح تنسيق حقل رقم الهاتف ("xxx-xxx-xxxx").
المعلمات
| الاسم | النوع | الوصف |
hint | String | تلميح النص الذي سيتم عرضه أسفل حقل الإدخال يظهر هذا النص دائمًا. |
الإرجاع
TextInput: هذا العنصر، لإنشاء سلسلة.
setMultiline(multiline)
لضبط ما إذا كان نص الإدخال يظهر على سطر واحد أو عدة أسطر.
المعلمات
| الاسم | النوع | الوصف |
multiline | Boolean | إعداد "السطور المتعددة" |
الإرجاع
TextInput: هذا العنصر، لإنشاء سلسلة.
setOnChangeAction(action)
تُستخدَم لضبط إجراء يتم تنفيذه عند تغيير إدخال النص.
المعلمات
| الاسم | النوع | الوصف |
action | Action | الإجراء الذي يجب اتّخاذه |
الإرجاع
TextInput: هذا العنصر، لإنشاء سلسلة.
setSuggestions(suggestions)
لضبط الاقتراحات الخاصة بالملء التلقائي في حقل النص
المعلمات
| الاسم | النوع | الوصف |
suggestions | Suggestions | مجموعة الاقتراحات التي يمكن استخدامها |
الإرجاع
TextInput: هذا العنصر، لإنشاء سلسلة.
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: هذا العنصر، لإنشاء سلسلة.
إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0 ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 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."]]
