تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
تتيح لك عناصر Action إنشاء سلوك تفاعلي في إضافات Google Workspace. وهي تحدّد الإجراءات التي تحدث عندما يتفاعل المستخدم مع أداة (مثل زر) في واجهة المستخدم الخاصة بالإضافة.
يتم ربط إجراء بأداة معيّنة باستخدام دالة معالجة الأدوات، والتي تحدّد أيضًا الشرط الذي يؤدي إلى تنفيذ الإجراء. عندما يتم تشغيل الإجراء، ينفّذ دالّة ردّ اتصال معيّنة.
يتم تمرير عنصر حدث إلى دالة معاودة الاتصال، ويحمل هذا العنصر معلومات حول تفاعلات المستخدم من جهة العميل. يجب تنفيذ دالة
معالجة النتائج وإرجاع عنصر استجابة محدّد.
على سبيل المثال، لنفترض أنّك تريد زرًا ينشئ بطاقة جديدة ويعرضها عند النقر عليه. لإجراء ذلك، عليك إنشاء أداة زر جديدة واستخدام دالة معالج أداة الزر setOnClickAction(action) لضبط Action لإنشاء البطاقات. يحدّد
Action الذي تحدّده دالة رد اتصال Apps Script
يتم تنفيذها عند النقر على الزر. في هذه الحالة، عليك تنفيذ دالة رد الاتصال لإنشاء البطاقة التي تريدها وعرض كائن ActionResponse. يطلب عنصر الاستجابة من الإضافة عرض البطاقة التي أنشأتها دالة رد الاتصال.
توضّح هذه الصفحة إجراءات الأدوات الخاصة بـ "تقويم Google" التي يمكنك تضمينها في الإضافة.
التفاعلات مع التقويم
يمكن أن تتضمّن إضافات Google Workspace التي توسّع نطاق "تقويم Google" بعض الإجراءات الإضافية الخاصة بأدوات "تقويم Google". تتطلّب هذه الإجراءات أن تعرض دالّة ردّ الاتصال المرتبطة بالإجراء عناصر ردّ مخصّصة:
بالإضافة إلى ذلك، لا يتم حفظ أي تغييرات أجرتها دالة معاودة الاتصال الخاصة بالإجراء إلا بعد أن يحفظ المستخدم حدث "تقويم Google".
إضافة ضيوف باستخدام دالة رد الاتصال
يوضّح المثال التالي كيفية إنشاء زر يضيف ضيفًا معيّنًا إلى حدث في "تقويم Google" يتم تعديله:
/***Buildasimplecardwithabuttonthatsendsanotification.*ThisfunctioniscalledaspartoftheeventOpenTriggerthatbuilds*aUIwhentheuseropensanevent.**@parameTheeventobjectpassedtoeventOpenTriggerfunction.*@return{Card}*/functionbuildSimpleCard(e){varbuttonAction=CardService.newAction().setFunctionName('onAddAttendeesButtonClicked');varbutton=CardService.newTextButton().setText('Add new attendee').setOnClickAction(buttonAction);//Checktheeventobjecttodetermineiftheusercanadd//attendeesanddisablethebuttonifnot.if(!e.calendar.capabilities.canAddAttendees){button.setDisabled(true);}//...continuecreatingcardsectionsandwidgets,thencreateaCard//objecttoaddthemto.ReturnthebuiltCardobject.}/***Callbackfunctionforabuttonaction.Addsattendeestothe*Calendareventbeingedited.**@param{Object}eTheactioneventobject.*@return{CalendarEventActionResponse}*/functiononAddAttendeesButtonClicked(e){returnCardService.newCalendarEventActionResponseBuilder().addAttendees(["aiko@example.com","malcom@example.com"]).build();}
ضبط بيانات المؤتمر باستخدام دالة معاودة الاتصال
يؤدي هذا الإجراء إلى ضبط بيانات المكالمة على الحدث المفتوح. بالنسبة إلى بيانات المؤتمر هذه، يجب تحديد رقم تعريف حلّ المؤتمر، لأنّ المستخدم لم يتّخذ الإجراء من خلال اختيار الحلّ المطلوب.
يوضّح المثال التالي كيفية إنشاء زر يضبط بيانات الاجتماع
لحدث يتم تعديله:
/***Buildasimplecardwithabuttonthatsendsanotification.*ThisfunctioniscalledaspartoftheeventOpenTriggerthatbuilds*aUIwhentheuseropensaCalendarevent.**@parameTheeventobjectpassedtoeventOpenTriggerfunction.*@return{Card}*/functionbuildSimpleCard(e){varbuttonAction=CardService.newAction().setFunctionName('onSaveConferenceOptionsButtonClicked').setParameters({'phone':"1555123467",'adminEmail':"joyce@example.com"});varbutton=CardService.newTextButton().setText('Add new attendee').setOnClickAction(buttonAction);//Checktheeventobjecttodetermineiftheusercanset//conferencedataanddisablethebuttonifnot.if(!e.calendar.capabilities.canSetConferenceData){button.setDisabled(true);}//...continuecreatingcardsectionsandwidgets,thencreateaCard//objecttoaddthemto.ReturnthebuiltCardobject.}/***Callbackfunctionforabuttonaction.Setsconferencedataforthe*Calendareventbeingedited.**@param{Object}eTheactioneventobject.*@return{CalendarEventActionResponse}*/functiononSaveConferenceOptionsButtonClicked(e){varparameters=e.commonEventObject.parameters;//Createanentrypointandaconferenceparameter.varphoneEntryPoint=ConferenceDataService.newEntryPoint().setEntryPointType(ConferenceDataService.EntryPointType.PHONE).setUri('tel:'+parameters['phone']);varadminEmailParameter=ConferenceDataService.newConferenceParameter().setKey('adminEmail').setValue(parameters['adminEmail']);//CreateaconferencedataobjecttosettothisCalendarevent.varconferenceData=ConferenceDataService.newConferenceDataBuilder().addEntryPoint(phoneEntryPoint).addConferenceParameter(adminEmailParameter).setConferenceSolutionId('myWebScheduledMeeting').build();returnCardService.newCalendarEventActionResponseBuilder().setConferenceData(conferenceData).build();}
إضافة مرفقات باستخدام دالة ردّ الاتصال
يوضّح المثال التالي كيفية إنشاء زر يضيف مرفقًا إلى حدث في "تقويم Google" يتم تعديله:
/***Buildasimplecardwithabuttonthatcreatesanewattachment.*ThisfunctioniscalledaspartoftheeventAttachmentTriggerthat*buildsaUIwhentheusergoesthroughtheadd-attachmentsflow.**@parameTheeventobjectpassedtoeventAttachmentTriggerfunction.*@return{Card}*/functionbuildSimpleCard(e){varbuttonAction=CardService.newAction().setFunctionName('onAddAttachmentButtonClicked');varbutton=CardService.newTextButton().setText('Add a custom attachment').setOnClickAction(buttonAction);//Checktheeventobjecttodetermineiftheusercanadd//attachmentsanddisablethebuttonifnot.if(!e.calendar.capabilities.canAddAttachments){button.setDisabled(true);}//...continuecreatingcardsectionsandwidgets,thencreateaCard//objecttoaddthemto.ReturnthebuiltCardobject.}/***Callbackfunctionforabuttonaction.AddsattachmentstotheCalendar*eventbeingedited.**@param{Object}eTheactioneventobject.*@return{CalendarEventActionResponse}*/functiononAddAttachmentButtonClicked(e){returnCardService.newCalendarEventActionResponseBuilder().addAttachments([CardService.newAttachment().setResourceUrl("https://example.com/test").setTitle("Custom attachment").setMimeType("text/html").setIconUrl("https://example.com/test.png")]).build();}
ضبط رمز المرفق
يجب استضافة رمز المرفق على بنية Google الأساسية. لمزيد من التفاصيل، يمكنك الاطّلاع على توفير رموز المرفقات.
تاريخ التعديل الأخير: 2025-08-29 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","easyToUnderstand","thumb-up"],["ساعَدني المحتوى في حلّ مشكلتي.","solvedMyProblem","thumb-up"],["غير ذلك","otherUp","thumb-up"]],[["لا يحتوي على المعلومات التي أحتاج إليها.","missingTheInformationINeed","thumb-down"],["الخطوات معقدة للغاية / كثيرة جدًا.","tooComplicatedTooManySteps","thumb-down"],["المحتوى قديم.","outOfDate","thumb-down"],["ثمة مشكلة في الترجمة.","translationIssue","thumb-down"],["مشكلة في العيّنات / التعليمات البرمجية","samplesCodeIssue","thumb-down"],["غير ذلك","otherDown","thumb-down"]],["تاريخ التعديل الأخير: 2025-08-29 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\u003cp\u003eActions enable interactive behavior in Google Workspace add-ons by defining responses to user interactions with UI widgets.\u003c/p\u003e\n"],["\u003cp\u003eActions are linked to widgets using handlers, triggering callback functions with event details for custom logic.\u003c/p\u003e\n"],["\u003cp\u003eCalendar add-ons have specific actions for attendee management, conference data, and attachments, requiring proper setup and permissions.\u003c/p\u003e\n"],["\u003cp\u003eCallback functions for Calendar actions return specialized response objects to manipulate event details like attendees and attachments.\u003c/p\u003e\n"],["\u003cp\u003eChanges made by these actions are only saved when the user saves the Calendar event itself.\u003c/p\u003e\n"]]],["Actions in Google Workspace add-ons define interactive behaviors triggered by widget interactions. Widget handler functions link actions to widgets, invoking callback functions upon user interaction. These callbacks, receiving event object data, return specific response objects. Calendar add-ons offer actions to add attendees, set conference data, and add attachments, requiring `CalendarEventActionResponse` returns and specific permissions. Example code demonstrates creating buttons that, when clicked, modify calendar events by adding attendees, setting conference data, or add an attachement.\n"],null,["# Calendar actions\n\n[`Action`](/workspace/add-ons/concepts/actions) objects let you build interactive\nbehavior into Google Workspace add-ons. They define\nwhat happens when a user interacts with a widget (for example, a button) in\nthe add-on UI.\n\nAn action is attached to a given widget using a\n[widget handler function](/workspace/add-ons/concepts/actions#widget_handler_functions),\nwhich also defines the condition that triggers the action. When triggered, the\naction executes a designated\n[callback function](/workspace/add-ons/concepts/actions#callback_functions).\nThe callback function is passed an\n[event object](/workspace/add-ons/concepts/event-objects) that carries\ninformation about the user's client-side interactions. You must implement the\ncallback function and have it return a specific response object.\n\nFor example, say you want a button that builds and displays a new card when\nclicked. For this, you must create a new button widget and use the button widget\nhandler function\n[`setOnClickAction(action)`](/apps-script/reference/card-service/text-button#setOnClickAction(Action))\nto set a card-building [`Action`](/workspace/add-ons/concepts/actions). The\n[`Action`](/workspace/add-ons/concepts/actions) you define specifies an Apps Script\ncallback function that executes when the button is clicked. In this case, you\nimplement the callback function to build the card you want and return an\n[`ActionResponse`](/apps-script/reference/card-service/action-response)\nobject. The response object tells the add-on to display the card the callback\nfunction built.\n\nThis page describes Calendar-specific widget actions you can include in your\nadd-on.\n\nCalendar interactions\n---------------------\n\nGoogle Workspace add-ons that extend Calendar\ncan include a few additional Calendar-specific widget actions. These actions\nrequire the associated action [callback function](/workspace/add-ons/concepts/actions#callback_functions)\nto return specialized response objects:\n\n| Action attempted | Callback function should return |\n|------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------|\n| [Adding attendees](#adding_attendees_with_a_callback_function) | [`CalendarEventActionResponse`](/apps-script/reference/card-service/calendar-event-action-response) |\n| [Setting conference data](#setting_conference_data_with_a_callback_function) | [`CalendarEventActionResponse`](/apps-script/reference/card-service/calendar-event-action-response) |\n| [Adding attachments](#add_attachments_with_a_callback_function) | [`CalendarEventActionResponse`](/apps-script/reference/card-service/calendar-event-action-response) |\n\nTo make use of these widget actions and response objects, all of the following\nmust be true:\n\n- The action is triggered while the user has a Calendar event open.\n- The add-on's [`addOns.calendar.currentEventAccess`](/apps-script/manifest/calendar-addons#Calendar.FIELDS.currentEventAccess) manifest field is set to `WRITE` or `READ_WRITE`.\n- The add-on includes the `https://www.googleapis.com/auth/calendar.addons.current.event.write` [Calendar scope](/workspace/add-ons/concepts/workspace-scopes#calendar_scopes).\n\nIn addition, any changes made by the action callback function aren't saved until\nthe user saves the Calendar event.\n\n### Adding attendees with a callback function\n\nThe following example shows how to create a button that adds a specific\nattendee to a Calendar event being edited: \n\n /**\n * Build a simple card with a button that sends a notification.\n * This function is called as part of the eventOpenTrigger that builds\n * a UI when the user opens an event.\n *\n * @param e The event object passed to eventOpenTrigger function.\n * @return {Card}\n */\n function buildSimpleCard(e) {\n var buttonAction = CardService.newAction()\n .setFunctionName('onAddAttendeesButtonClicked');\n var button = CardService.newTextButton()\n .setText('Add new attendee')\n .setOnClickAction(buttonAction);\n\n // Check the event object to determine if the user can add\n // attendees and disable the button if not.\n if (!e.calendar.capabilities.canAddAttendees) {\n button.setDisabled(true);\n }\n\n // ...continue creating card sections and widgets, then create a Card\n // object to add them to. Return the built Card object.\n }\n\n /**\n * Callback function for a button action. Adds attendees to the\n * Calendar event being edited.\n *\n * @param {Object} e The action event object.\n * @return {CalendarEventActionResponse}\n */\n function onAddAttendeesButtonClicked (e) {\n return CardService.newCalendarEventActionResponseBuilder()\n .addAttendees([\"aiko@example.com\", \"malcom@example.com\"])\n .build();\n }\n\n### Setting conference data with a callback function\n\nThis action sets the conference data on the open event. For this conference data\nthe conference solution ID needs to be specified, because the action was not\ntriggered by the user selecting the desired solution.\n\nThe following example shows how to create a button that sets conference data\nfor an event being edited: \n\n /**\n * Build a simple card with a button that sends a notification.\n * This function is called as part of the eventOpenTrigger that builds\n * a UI when the user opens a Calendar event.\n *\n * @param e The event object passed to eventOpenTrigger function.\n * @return {Card}\n */\n function buildSimpleCard(e) {\n var buttonAction = CardService.newAction()\n .setFunctionName('onSaveConferenceOptionsButtonClicked')\n .setParameters(\n {'phone': \"1555123467\", 'adminEmail': \"joyce@example.com\"});\n var button = CardService.newTextButton()\n .setText('Add new attendee')\n .setOnClickAction(buttonAction);\n\n // Check the event object to determine if the user can set\n // conference data and disable the button if not.\n if (!e.calendar.capabilities.canSetConferenceData) {\n button.setDisabled(true);\n }\n\n // ...continue creating card sections and widgets, then create a Card\n // object to add them to. Return the built Card object.\n }\n\n /**\n * Callback function for a button action. Sets conference data for the\n * Calendar event being edited.\n *\n * @param {Object} e The action event object.\n * @return {CalendarEventActionResponse}\n */\n function onSaveConferenceOptionsButtonClicked(e) {\n var parameters = e.commonEventObject.parameters;\n\n // Create an entry point and a conference parameter.\n var phoneEntryPoint = ConferenceDataService.newEntryPoint()\n .setEntryPointType(ConferenceDataService.EntryPointType.PHONE)\n .setUri('tel:' + parameters['phone']);\n\n var adminEmailParameter = ConferenceDataService.newConferenceParameter()\n .setKey('adminEmail')\n .setValue(parameters['adminEmail']);\n\n // Create a conference data object to set to this Calendar event.\n var conferenceData = ConferenceDataService.newConferenceDataBuilder()\n .addEntryPoint(phoneEntryPoint)\n .addConferenceParameter(adminEmailParameter)\n .setConferenceSolutionId('myWebScheduledMeeting')\n .build();\n\n return CardService.newCalendarEventActionResponseBuilder()\n .setConferenceData(conferenceData)\n .build();\n }\n\n### Add attachments with a callback function\n\nThe following example shows how to create a button that adds an attachment to a\nCalendar event being edited: \n\n /**\n * Build a simple card with a button that creates a new attachment.\n * This function is called as part of the eventAttachmentTrigger that\n * builds a UI when the user goes through the add-attachments flow.\n *\n * @param e The event object passed to eventAttachmentTrigger function.\n * @return {Card}\n */\n function buildSimpleCard(e) {\n var buttonAction = CardService.newAction()\n .setFunctionName('onAddAttachmentButtonClicked');\n var button = CardService.newTextButton()\n .setText('Add a custom attachment')\n .setOnClickAction(buttonAction);\n\n // Check the event object to determine if the user can add\n // attachments and disable the button if not.\n if (!e.calendar.capabilities.canAddAttachments) {\n button.setDisabled(true);\n }\n\n // ...continue creating card sections and widgets, then create a Card\n // object to add them to. Return the built Card object.\n }\n\n /**\n * Callback function for a button action. Adds attachments to the Calendar\n * event being edited.\n *\n * @param {Object} e The action event object.\n * @return {CalendarEventActionResponse}\n */\n function onAddAttachmentButtonClicked(e) {\n return CardService.newCalendarEventActionResponseBuilder()\n .addAttachments([\n CardService.newAttachment()\n .setResourceUrl(\"https://example.com/test\")\n .setTitle(\"Custom attachment\")\n .setMimeType(\"text/html\")\n .setIconUrl(\"https://example.com/test.png\")\n ])\n .build();\n }\n\n#### Setting the attachment icon\n\nThe attachment icon must be hosted on Google's infrastructure. See [Provide\nattachment icons](/workspace/add-ons/calendar/attachment/providing-icons)\nfor details."]]