פעולות עריכה

אפשר להשתמש באובייקטים של Action כדי ליצור התנהגות אינטראקטיבית בתוספים של Google Workspace.

אובייקטים של פעולות מגדירים מה קורה כשמשתמש יוצר אינטראקציה עם ווידג'ט (לדוגמה, לחצן) בממשק המשתמש של התוסף.

הוספת פעולה לווידג'ט

כדי לצרף פעולה לווידג'ט, צריך להשתמש בפונקציה של handler של ווידג'טים, שמגדירה גם את התנאי שמפעיל את הפעולה. כשהפעולה מופעלת, היא מפעילה פונקציית קריאה חוזרת ייעודית. לפונקציית הקריאה החוזרת מועבר אובייקט אירוע שנושא את המידע על האינטראקציות של המשתמש בצד הלקוח. צריך להטמיע את פונקציית הקריאה החוזרת ולבקש ממנה להחזיר אובייקט תגובה ספציפי.

דוגמה: הצגת כרטיס חדש כאשר לוחצים על לחצן

כדי להוסיף לחצן לתוסף שיוצר ומציג כרטיס חדש כשלוחצים עליו, צריך לפעול לפי השלבים הבאים:

1. יוצרים ווידג'ט של לחצן.
2. כדי להגדיר פעולה של בניית כרטיסים, מוסיפים את הפונקציה של handler של הלחצן לווידג'ט setOnClickAction(action).
3. צריך ליצור פונקציית קריאה חוזרת ב-Apps Script כדי להפעיל אותה ולציין אותה בתור (action) בתוך פונקציית ה-handler של הווידג'ט. במקרה כזה, פונקציית הקריאה החוזרת צריכה ליצור את הכרטיס הרצוי ולהחזיר אובייקט ActionResponse. אובייקט התגובה מורה לתוסף להציג את הכרטיס שיצרה פונקציית הקריאה החוזרת.

בדוגמה הבאה מוצגת יצירה של ווידג'ט לחצן. הפעולה מבקשת בשם התוסף את ההיקף drive.file של הקובץ הנוכחי.

/**
 * Adds a section to the Card Builder that displays a "REQUEST PERMISSION" button.
 * When it's clicked, the callback triggers file scope permission flow. This is used in
 * the add-on when the home-page displays basic data.
 */
function addRequestFileScopeButtonToBuilder(cardBuilder) {
    var buttonSection = CardService.newCardSection();
    // If the add-on does not have access permission, add a button that
    // allows the user to provide that permission on a per-file basis.
    var buttonAction = CardService.newAction()
      .setFunctionName("onRequestFileScopeButtonClickedInEditor");

    var button = CardService.newTextButton()
      .setText("Request permission")
      .setBackgroundColor("#4285f4")
      .setTextButtonStyle(CardService.TextButtonStyle.FILLED)
      .setOnClickAction(buttonAction);

    buttonSection.addWidget(button);
    cardBuilder.addSection(buttonSection);
}

/**
 * Callback function for a button action. Instructs Docs to display a
 * permissions dialog to the user, requesting `drive.file` scope for the 
 * current file on behalf of this add-on.
 *
 * @param {Object} e The parameters object that contains the document’s ID
 * @return {editorFileScopeActionResponse}
 */
function onRequestFileScopeButtonClickedInEditor(e) {
  return CardService.newEditorFileScopeActionResponseBuilder()
      .requestFileScopeForActiveDocument().build();

אינטראקציות של גישה לקבצים בממשקי API ל-REST

בתוספים של Google Workspace שמרחיבים את העורכים ומשתמשים בממשקי API ל-REST, אפשר להגדיר פעולה נוספת בווידג'ט כדי לבקש גישה לקובץ. לפעולה הזו נדרשת פונקציית הקריאה החוזרת לפעולה המשויכת כדי להחזיר אובייקט תגובה מיוחד:

בוצע ניסיון לפעולה	פונקציית הקריאה החוזרת אמורה לחזור
בקשת גישה לקובץ עבור current_document	EditorFileScopeActionResponse

כדי להשתמש בפעולה הזו בווידג'ט ובאובייקט התגובה, כל התנאים הבאים צריכים להתקיים:

• התוסף משתמש בממשקי API ל-REST.
• התוסף מציג את תיבת הדו-שיח של היקף הקובץ של הבקשה באמצעות השיטה CardService.newEditorFileScopeActionResponseBuilder().requestFileScopeForActiveDocument().build();.
• התוסף כולל את היקף העריכה https://www.googleapis.com/auth/drive.file ואת הטריגר onFileScopeGranted במניפסט שלו.

בקשת גישה לקובץ עבור המסמך הנוכחי

כך מבקשים הרשאת גישה לקובץ המסמך הנוכחי:

1. איך ליצור כרטיס בדף הבית שבודק אם לתוסף יש היקף של drive.file.
2. במקרים שבהם התוסף לא קיבל הרשאה להיקף של drive.file, צריך לבנות איך לבקש מהמשתמשים להקצות את ההיקף של drive.file למסמך הנוכחי.

דוגמה: קבלת גישה נוכחית למסמך ב-Google Docs

בדוגמה הבאה נוצר ממשק ל-Google Docs שמציג את הגודל של המסמך הנוכחי. אם לתוסף אין הרשאה מסוג drive.file, יוצג לחצן להפעלת ההרשאה של היקף הקובץ.

/**
 * Build a simple card that checks selected items' quota usage. Checking
 * quota usage requires user-permissions, so this add-on provides a button
 * to request `drive.file` scope for items the add-on doesn't yet have
 * permission to access.
 *
 * @param e The event object passed containing information about the
 *   current document.
 * @return {Card}
 */
function onDocsHomepage(e) {
  return createAddOnView(e);
}

function onFileScopeGranted(e) {
  return createAddOnView(e);
}

/**
 * For the current document, display either its quota information or
 * a button that allows the user to provide permission to access that
 * file to retrieve its quota details.
 *
 * @param e The event containing information about the current document
 * @return {Card}
 */
function createAddOnView(e) {
  var docsEventObject = e['docs'];
  var builder =  CardService.newCardBuilder();

  var cardSection = CardService.newCardSection();
  if (docsEventObject['addonHasFileScopePermission']) {
    cardSection.setHeader(docsEventObject['title']);
    // This add-on uses the recommended, limited-permission `drive.file`
    // scope to get granular per-file access permissions.
    // See: https://developers.google.com/drive/api/v2/about-auth
    // If the add-on has access permission, read and display its quota.
    cardSection.addWidget(
      CardService.newTextParagraph().setText(
          "This file takes up: " + getQuotaBytesUsed(docsEventObject['id'])));
  } else {
    // If the add-on does not have access permission, add a button that
    // allows the user to provide that permission on a per-file basis.
    cardSection.addWidget(
      CardService.newTextParagraph().setText(
          "The add-on needs permission to access this file's quota."));

    var buttonAction = CardService.newAction()
      .setFunctionName("onRequestFileScopeButtonClicked");

    var button = CardService.newTextButton()
      .setText("Request permission")
      .setOnClickAction(buttonAction);

    cardSection.addWidget(button);
  }
  return builder.addSection(cardSection).build();
}

/**
 * Callback function for a button action. Instructs Docs to display a
 * permissions dialog to the user, requesting `drive.file` scope for the
 * current file on behalf of this add-on.
 *
 * @param {Object} e The parameters object that contains the document’s ID
 * @return {editorFileScopeActionResponse}
 */
function onRequestFileScopeButtonClicked(e) {
  return CardService.newEditorFileScopeActionResponseBuilder()
      .requestFileScopeForActiveDocument().build();
}