פעולות עריכה

שימוש באובייקטים מסוג פעולה כדי ליצור אובייקטים אינטראקטיביים ההתנהגות של המשתמשים בתוספים של 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();
}