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

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

تحدد كائنات الإجراءات ما يحدث عندما يتفاعل المستخدم مع أداة (على سبيل المثال، زر) في واجهة مستخدم الإضافة.

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

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

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

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

  1. إنشاء تطبيق مصغر للزر.
  2. لضبط إجراء إنشاء بطاقة، أضِف وظيفة معالج التطبيقات المصغّرة للأزرار setOnClickAction(action).
  3. يمكنك إنشاء دالة استدعاء في "برمجة تطبيقات Google" لتنفيذها وتحديدها على أنّها (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 التي توفّر أدوات التحرير وتستخدم واجهات برمجة تطبيقات REST إجراءً إضافيًا حول التطبيقات المصغّرة لطلب الوصول إلى الملف. يتطلب هذا الإجراء دالة استدعاء الإجراء المرتبط لعرض كائن استجابة متخصص:

تمت محاولة تنفيذ الإجراء. يجب أن تُرجع دالة رد الاتصال
طلب الوصول إلى الملف في المستند الحالي 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();
}