במדריך הזה מוסבר איך ליצור כרטיס הגדרה שמאפשר למשתמשים להתאים אישית שלב ב-Google Workspace Studio ולספק לו קלט.
באופן כללי, כדי ליצור כרטיס הגדרה, צריך ליצור ממשק כרטיס כמו בכל תוסף אחר ל-Google Workspace. כדי לקבל עזרה ביצירת ממשקי כרטיסי הגדרה, אפשר לעיין במאמרים הבאים:
- הכלי ליצירת כרטיסים, כלי אינטראקטיבי שעוזר לכם ליצור ולהגדיר כרטיסים.
- כרטיס במאמרי העזרה של Google Workspace API.
- Card Service, שירות Apps Script שמאפשר לסקריפטים להגדיר וליצור כרטיסים.
- ממשקים מבוססי-כרטיסים במסמכי התיעוד למפתחים של תוספים ל-Google Workspace.
חלק מהווידג'טים של הכרטיסים כוללים פונקציות ותכונות מיוחדות שספציפיות ל-Workspace Studio, שמפורטות במדריך הזה.
הגדרת כרטיס הגדרה
מגדירים כרטיס הגדרות אישיות במניפסט Apps Script ובקוד.
בדוגמה הבאה מוצג איך ליצור כרטיס הגדרה שמבקש מהמשתמשים לבחור מרחב ב-Google Chat.
עריכת קובץ המניפסט
בקובץ המניפסט, מגדירים את workflowElements.
JSON
{
"timeZone": "America/Los_Angeles",
"exceptionLogging": "STACKDRIVER",
"runtimeVersion": "V8",
"addOns": {
"common": {
"name": "Chat space selector",
"logoUrl": "https://www.gstatic.com/images/branding/productlogos/gsuite_addons/v6/web-24dp/logo_gsuite_addons_color_1x_web_24dp.png",
"useLocaleFromApp": true
},
"flows": {
"workflowElements": [
{
"id": "actionElement",
"state": "ACTIVE",
"name": "Chat space selector",
"description": "Lets the user select a space from Google Chat",
"workflowAction": {
"inputs": [
{
"id": "chooseSpace",
"description": "Choose a Chat space",
"cardinality": "SINGLE",
"dataType": {
"basicType": "STRING"
}
}
],
"onConfigFunction": "onConfigSpacePicker",
"onExecuteFunction": "onExecuteSpacePicker"
}
}
]
}
}
}
עריכת הקוד
מחזירים כרטיס בקוד של האפליקציה.
Apps Script
/**
* Generates and displays a configuration card to choose a Chat space
*/
function onConfigSpacePicker() {
const selectionInput = CardService.newSelectionInput()
.setTitle("First Value")
.setFieldName("chooseSpace")
.setType(CardService.SelectionInputType.MULTI_SELECT)
.setPlatformDataSource(
CardService.newPlatformDataSource()
.setHostAppDataSource(
CardService.newHostAppDataSource()
.setWorkflowDataSource(
CardService.newWorkflowDataSource()
.setIncludeVariables(true)
.setType(CardService.WorkflowDataSourceType.SPACE)
)
)
);
const cardSection = CardService.newCardSection()
.setHeader("Select Chat Space")
.setId("section_1")
.addWidget(selectionInput)
var card = CardService.newCardBuilder()
.addSection(cardSection)
.build();
return card;
}
function onExecuteSpacePicker(e) {
}
הגדרת השלמה אוטומטית לרכיבי קלט
אתם יכולים להגדיר השלמה אוטומטית לווידג'טים של SelectionInput כדי לעזור למשתמשים לבחור מתוך רשימת אפשרויות. לדוגמה, אם משתמש מתחיל להקליד Atl לתפריט שמאכלס ערים בארצות הברית, הרכיב יכול להציע אוטומטית Atlanta לפני שהמשתמש מסיים להקליד. אפשר להשלים אוטומטית עד 100 פריטים.
ההצעות להשלמה אוטומטית יכולות להגיע ממקורות הנתונים הבאים:
- השלמה אוטומטית בצד השרת: ההצעות מאוכלסות ממקור נתונים חיצוני או של צד שלישי שאתם מגדירים.
- נתונים מ-Google Workspace: ההצעות מגיעות ממקורות ב-Google Workspace, כמו משתמשי Google Workspace או מרחבים ב-Google Chat.
השלמה אוטומטית בצד השרת
אתם יכולים להגדיר את הווידג'ט SelectionInput כך שיציג הצעות להשלמה אוטומטית ממקור נתונים חיצוני. לדוגמה, אתם יכולים לעזור למשתמשים לבחור מתוך רשימה של לידים למכירות ממערכת לניהול קשרי לקוחות (CRM).
כדי להטמיע השלמה אוטומטית בצד השרת, צריך:
- מגדירים את מקור הנתונים: בווידג'ט
SelectionInputמוסיפיםDataSourceConfigשמצייןRemoteDataSource. ההגדרה הזו מצביעה על פונקציית Apps Script שמביאה הצעות להשלמה אוטומטית. - הטמעה של פונקציית ההשלמה האוטומטית: הפונקציה הזו מופעלת כשהמשתמש מקליד בשדה הקלט. הפונקציה צריכה לשלוח שאילתה למקור הנתונים החיצוני על סמך הקלט של המשתמש ולהחזיר רשימה של הצעות.
בדוגמה הבאה אפשר לראות איך מגדירים את הווידג'ט SelectionInput להשלמה אוטומטית בצד השרת:
Apps Script
// In your onConfig function:
var multiSelect1 =
CardService.newSelectionInput()
.setFieldName("value1")
.setTitle("Server Autocomplete")
.setType(CardService.SelectionInputType.MULTI_SELECT)
.setMultiSelectMaxSelectedItems(3)
.addDataSourceConfig(
CardService.newDataSourceConfig()
.setRemoteDataSource(
CardService.newAction().setFunctionName('getAutocompleteResults')
)
)
.addDataSourceConfig(
CardService.newDataSourceConfig()
.setPlatformDataSource(
CardService.newPlatformDataSource()
.setHostAppDataSource(
CardService.newHostAppDataSource()
.setWorkflowDataSource(
CardService.newWorkflowDataSource()
.setIncludeVariables(true)
))
)
);
// ... add widget to card ...
טיפול בבקשה להשלמה אוטומטית
הפונקציה שצוינה ב-setFunctionName (למשל, getAutocompleteResults) מקבל אובייקט של אירוע כשהמשתמש מקליד בשדה. הפונקציה צריכה:
- בודקים את
event.workflow.elementUiAutocomplete.invokedFunctionכדי לוודא שהוא תואם לשם הפונקציה הצפוי. - מקבלים את הקלט של המשתמש מ-
event.workflow.elementUiAutocomplete.query. - שולחים שאילתה למקור הנתונים החיצוני באמצעות השאילתה.
- החזרת עד 100 הצעות בפורמט הנדרש.
בדוגמה הבאה מוצג אופן ההטמעה של הפונקציה handleAutocompleteRequest() כדי להחזיר הצעות על סמך השאילתה של המשתמש:
Apps Script
function handleAutocompleteRequest(event) {
var invokedFunction = event.workflow.elementUiAutocomplete.invokedFunction;
var query = event.workflow.elementUiAutocomplete.query;
if (invokedFunction != "getAutocompleteResults" || query == undefined || query == "") {
return {};
}
// Query your data source to get results based on the query
let autocompleteResponse = AddOnsResponseService.newUpdateWidget()
.addSuggestion(
query + " option 1",
query + "_option1",
false,
"https://developers.google.com/workspace/add-ons/images/person-icon.png",
"option 1 bottom text"
)
.addSuggestion(
query + " option 2",
query + "_option2",
false,
"https://developers.google.com/workspace/add-ons/images/person-icon.png",
"option 2 bottom text"
).addSuggestion(
query + " option 3",
query + "_option3",
false,
"https://developers.google.com/workspace/add-ons/images/person-icon.png",
"option 3 bottom text"
);
const modifyAction = AddOnsResponseService.newAction()
.addModifyCard(
AddOnsResponseService.newModifyCard()
.setUpdateWidget(autocompleteResponse)
);
return AddOnsResponseService.newRenderActionBuilder()
.setAction(modifyAction)
.build();
}
// In your onConfig function, handle the autocomplete event
function onConfigAutocompleteTest(event) {
// Handle autocomplete request
if (event.workflow && event.workflow.elementUiAutocomplete) {
return handleAutocompleteRequest(event);
}
// ... rest of your card building logic ...
}
שיקולים ומגבלות לגבי כרטיסים
- ניווט בכרטיסים כמו
popCard(),pushCard()ו-updateCard()לא נתמך בתוספים שמרחיבים את Workspace Studio.
נושאים קשורים
- איך יוצרים שלב
- משתני קלט
- אימות משתנה קלט
- משתני פלט
- רישום פעילות ושגיאות ביומן
- אובייקטים של אירועים ב-Workspace Studio