إجراءات المحرِّر

استخدِم عناصر الإجراء لإنشاء سلوك تفاعلي في إضافات Google Workspace.

تحدِّد عناصر الإجراءات ما يحدث عندما يتفاعل المستخدِم مع تطبيق مصغّر (مثل زر) في واجهة مستخدم الإضافة.

إضافة إجراء إلى تطبيق مصغّر

لإرفاق إجراء بتطبيق مصغّر، استخدِم دالة معالِج التطبيق المصغّر، التي تحدِّد أيضًا الشرط الذي يؤدي إلى تنفيذ الإجراء. عند بدء الإجراء، يؤدي الإجراء إلى تنفيذ دالة ردّ اتصال محدّدة. يتمّ تمرير عنصر حدث إلى الدالة المخصّصة للردّ، وهو يحمل معلومات عن تفاعلات المستخدِم من جهة العميل. يجب تنفيذ دالة ردّ الاتصال وجعلها تعرِض عنصر استجابة محدّدًا.

مثال: عرض بطاقة جديدة عند النقر على زر

إذا كنت تريد إضافة زر إلى الإضافة ينشئ بطاقة جديدة ويعرضها عند النقر عليه، اتّبِع الخطوات التالية:

1. أنشئ أداة زر.
2. لضبط إجراء لإنشاء بطاقة، أضِف دالة معالِج التطبيق المصغّر للزر setOnClickAction(action).
3. أنشئ دالة ردّ اتصال في Apps Script لتنفيذها وتحديدها على أنّها (action) ضمن دالة معالِج التطبيق المصغّر. في هذه الحالة، يجب أن تنشئ دالة ردّ الاتصال البطاقة التي تريدها وتُرجع عنصر 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();

تفاعلات الوصول إلى الملفات لواجهات برمجة تطبيقات REST

يمكن أن تتضمّن إضافات Google Workspace التي توفّر ميزات إضافية في "محرّري Google" وتستخدم واجهات برمجة التطبيقات REST API إجراء إضافي في التطبيقات المصغّرة لطلب الوصول إلى الملفات. يتطلّب هذا الإجراء أن تُرجع دالة ردّ الاتصال المرتبط بالإجراء عنصر استجابة مخصّصًا:

الإجراء الذي تمّت محاولة تنفيذه	يجب أن تُرجع دالّة ردّ الاتصال
طلب الوصول إلى الملف current_document	EditorFileScopeActionResponse

لاستخدام إجراء التطبيق المصغّر وعنصر الاستجابة هذا، يجب أن يكون كلّ ما يلي صحيحًا:

• تستخدم الإضافة واجهات برمجة تطبيقات REST.
• تعرِض الإضافة مربّع حوار نطاق ملف الطلب باستخدام الطريقة CardService.newEditorFileScopeActionResponseBuilder().requestFileScopeForActiveDocument().build();.
• تتضمّن الإضافة ملف البيان الذي يتضمّن https://www.googleapis.com/auth/drive.file نطاق المحرِّر و onFileScopeGranted عامل التفعيل.

طلب الوصول إلى الملف للمستند الحالي

لطلب الوصول إلى الملف للمستند الحالي، اتّبِع الخطوات التالية:

1. أنشئ بطاقة صفحة رئيسية تتحقّق مما إذا كانت الإضافة لها نطاق drive.file.
2. في الحالات التي لم تحصل فيها الإضافة على نطاق drive.file، أنشئ طريقة لطلب من المستخدمين منح نطاق drive.file للمستند الحالي.

مثال: الحصول على إذن الوصول إلى المستند الحالي في "مستندات Google"

ينشئ المثال التالي واجهة لخدمة "مستندات Google" تعرِض حجم المستند الحالي. إذا لم تكن لديك إضافة 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();
}