تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

مربعات الحوار والأشرطة الجانبية في مستندات Google Workspace

النصوص البرمجية المقيدة في "مستندات Google" أو "جداول بيانات Google" أو "نماذج Google" يمكنها عرض عدّة أنواع من عناصر واجهة المستخدم، بما في ذلك التنبيهات والتنبيهات المُنشأة مسبقًا، بالإضافة إلى مربعات الحوار والأشرطة الجانبية التي تحتوي على صفحات خدمة HTML مخصّصة. ويتم فتح هذه العناصر عادة من عناصر القائمة. (لاحظ أنه في نماذج Google، لا تظهر عناصر واجهة المستخدم إلا للمحرر الذي يفتح النموذج لتعديله، وليس للمستخدم الذي يفتح النموذج للرد).

مربعات حوار التنبيهات

التنبيه هو مربّع حوار مُعَد سابقًا يفتح في محرّر المستندات أو جداول البيانات أو العروض التقديمية أو النماذج من Google. ويعرض رسالة وزر "حسنًا"، أما العنوان والأزرار البديلة، فهي اختيارية. وهو يشبه استدعاء window.alert() في جافا سكريبت من جانب العميل داخل متصفح الويب.

تعمل التنبيهات على تعليق النص البرمجي من جانب الخادم أثناء فتح مربع الحوار. يستأنف النص البرمجي بعد إغلاق المستخدم لمربّع الحوار، ولكن لا تستمر اتصالات JDBC خلال عملية التعليق.

كما هو موضح في المثال أدناه، تستخدم "مستندات Google" و"نماذج Google" و"العروض التقديمية من Google" و"جداول بيانات Google" جميعًا الطريقة Ui.alert() المتاحة في ثلاث صيغ. لإلغاء زر "OK" التلقائي، مرّر قيمة من تعداد Ui.ButtonSet كوسيطة buttons. لتقييم الزر الذي نقر عليه المستخدم، قارِن قيمة عرض alert() بتعداد Ui.Button.

function onOpen() {
  SpreadsheetApp.getUi() // Or DocumentApp or SlidesApp or FormApp.
      .createMenu('Custom Menu')
      .addItem('Show alert', 'showAlert')
      .addToUi();
}

function showAlert() {
  var ui = SpreadsheetApp.getUi(); // Same variations.

  var result = ui.alert(
     'Please confirm',
     'Are you sure you want to continue?',
      ui.ButtonSet.YES_NO);

  // Process the user's response.
  if (result == ui.Button.YES) {
    // User clicked "Yes".
    ui.alert('Confirmation received.');
  } else {
    // User clicked "No" or X in the title bar.
    ui.alert('Permission denied.');
  }
}

مربعات حوار المطالبات

رسالة المطالبة هي مربّع حوار مصمَّم مسبقًا يتم فتحه في "مستندات Google" أو "جداول بيانات Google" أو "العروض التقديمية من Google" أو "محرر نماذج Google". ويعرض رسالة وحقل إدخال نص وزر "حسنًا"، أما العنوان والأزرار البديلة فهي اختيارية. وهو يشبه استدعاء window.prompt() في جافا سكريبت من جانب العميل داخل متصفح الويب.

تؤدي المطالبات إلى تعليق النص البرمجي من جانب الخادم أثناء فتح مربع الحوار. يستأنف النص البرمجي بعد إغلاق المستخدم لمربّع الحوار، ولكن لا تستمر اتصالات JDBC خلال عملية التعليق.

كما هو موضّح في المثال أدناه، تستخدم "مستندات Google" و"نماذج Google" و"العروض التقديمية من Google" و"جداول بيانات Google" جميعًا الطريقة Ui.prompt() المتاحة في ثلاث صيغ. لإلغاء الزر "OK" التلقائي، مرّر قيمة من تعداد Ui.ButtonSet كوسيطة buttons. لتقييم رد المستخدم، عليك تسجيل قيمة الإرجاع لـ prompt()، ثم الاتصال PromptResponse.getResponseText() باسترداد إدخال المستخدم، ومقارنة قيمة عرض PromptResponse.getSelectedButton() بتعداد Ui.Button.

function onOpen() {
  SpreadsheetApp.getUi() // Or DocumentApp or SlidesApp or FormApp.
      .createMenu('Custom Menu')
      .addItem('Show prompt', 'showPrompt')
      .addToUi();
}

function showPrompt() {
  var ui = SpreadsheetApp.getUi(); // Same variations.

  var result = ui.prompt(
      'Let\'s get to know each other!',
      'Please enter your name:',
      ui.ButtonSet.OK_CANCEL);

  // Process the user's response.
  var button = result.getSelectedButton();
  var text = result.getResponseText();
  if (button == ui.Button.OK) {
    // User clicked "OK".
    ui.alert('Your name is ' + text + '.');
  } else if (button == ui.Button.CANCEL) {
    // User clicked "Cancel".
    ui.alert('I didn\'t get your name.');
  } else if (button == ui.Button.CLOSE) {
    // User clicked X in the title bar.
    ui.alert('You closed the dialog.');
  }
}

مربعات حوار مخصصة

يمكن لمربع حوار مخصص عرض واجهة مستخدم خدمة HTML داخل محرر مستندات Google أو جداول البيانات أو العروض التقديمية أو النماذج.

لا تُعلّق مربعات الحوار المخصصة النص البرمجي من جانب الخادم أثناء فتح مربع الحوار. يمكن للمكوّن من جهة العميل إجراء استدعاءات غير متزامنة للنص البرمجي من جهة الخادم باستخدام واجهة برمجة تطبيقات google.script لواجهات خدمة HTML.

يمكن إغلاق مربع الحوار من خلال استدعاء google.script.host.close() في جانب العميل لواجهة خدمة HTML. ولا يمكن إغلاق مربع الحوار من خلال واجهات أخرى، بل من قِبل المستخدم نفسه فقط.

كما هو موضّح في المثال أدناه، تستخدم "مستندات Google" و"نماذج Google" و"العروض التقديمية من Google" و"جداول بيانات Google" جميعًا الطريقة Ui.showModalDialog() لفتح مربّع الحوار.

Code.gs

function onOpen() {
  SpreadsheetApp.getUi() // Or DocumentApp or SlidesApp or FormApp.
      .createMenu('Custom Menu')
      .addItem('Show dialog', 'showDialog')
      .addToUi();
}

function showDialog() {
  var html = HtmlService.createHtmlOutputFromFile('Page')
      .setWidth(400)
      .setHeight(300);
  SpreadsheetApp.getUi() // Or DocumentApp or SlidesApp or FormApp.
      .showModalDialog(html, 'My custom dialog');
}

Page.html

Hello, world! <input type="button" value="Close" onclick="google.script.host.close()" />

الأشرطة الجانبية المخصصة

يمكن أن يعرض الشريط الجانبي واجهة مستخدم خدمة HTML داخل محرّر مستندات Google أو النماذج أو العروض التقديمية أو جداول البيانات.

ولا تعلّق الأشرطة الجانبية النص البرمجي من جانب الخادم أثناء فتح مربع الحوار. يمكن للمكوّن من جهة العميل إجراء استدعاءات غير متزامنة للنص البرمجي من جهة الخادم باستخدام google.script API لواجهات خدمة HTML.

يمكن أن يتم إغلاق الشريط الجانبي تلقائيًا من خلال استدعاء google.script.host.close() في جانب العميل لواجهة خدمة HTML. ولا يمكن إغلاق الشريط الجانبي بواسطة واجهات أخرى، بل من قِبل المستخدم نفسه فقط.

كما هو موضّح في المثال أدناه، تستخدم "مستندات Google" و"نماذج Google" و"العروض التقديمية من Google" و"جداول بيانات Google" الطريقة Ui.showSidebar() لفتح الشريط الجانبي.

Code.gs

function onOpen() {
  SpreadsheetApp.getUi() // Or DocumentApp or SlidesApp or FormApp.
      .createMenu('Custom Menu')
      .addItem('Show sidebar', 'showSidebar')
      .addToUi();
}

function showSidebar() {
  var html = HtmlService.createHtmlOutputFromFile('Page')
      .setTitle('My custom sidebar');
  SpreadsheetApp.getUi() // Or DocumentApp or SlidesApp or FormApp.
      .showSidebar(html);
}

Page.html

Hello, world! <input type="button" value="Close" onclick="google.script.host.close()" />

مربعات حوار فتح الملفات

منتقي Google هو مربع حوار "فتح الملفات" للمعلومات المخزنة في خوادم Google، بما في ذلك Google Drive وبحث الصور من Google وبحث الفيديو من Google والمزيد.

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

لتفعيل "منتقي" والحصول على مفتاح واجهة برمجة التطبيقات، اتبع هذه الإرشادات:

تحقَّق من أن مشروع النص البرمجي يستخدم مشروع Google Cloud Platform عادي.
تفعيل "واجهة برمجة تطبيقات منتقي Google" في مشروع Google Cloud Platform.
عندما يظل مشروعك على Google Cloud Platform مفتوحًا، اختَر واجهات برمجة التطبيقات والخدمات، ثم انقر على بيانات الاعتماد.
انقر على إنشاء بيانات اعتماد > واجهة برمجة التطبيقات. يؤدي هذا الإجراء إلى إنشاء المفتاح، ولكن يجب تعديل المفتاح لإضافة قيود التطبيق وقيود واجهة برمجة التطبيقات على المفتاح.
في مربع حوار مفتاح واجهة برمجة التطبيقات، انقر على إغلاق.
بجانب مفتاح واجهة برمجة التطبيقات الذي أنشأته، انقر على رمز المزيد > تعديل مفتاح واجهة برمجة التطبيقات.
ضمن قيود التطبيق، أكمل الخطوات التالية:
1. حدد مُحيلات HTTP (مواقع الويب).
2. ضمن قيود مواقع الويب، انقر على إضافة عنصر.
3. انقر على الإحالة وأدخِل *.google.com.
4. أضف عنصرًا آخر وأدخل *.googleusercontent.com كمُحيل.
5. انقر على تم.
ضمن قيود واجهة برمجة التطبيقات، أكمل الخطوات التالية:
1. اختَر تقييد المفتاح.
2. في القسم تحديد واجهات برمجة التطبيقات، حدد واجهة برمجة تطبيقات منتقي Google وانقر على موافق.
  
  ملاحظة: لا تظهر واجهة برمجة تطبيقات Google Picker ما لم يتم تفعيلها لأن القائمة لا تعرض سوى واجهات برمجة التطبيقات التي تم تمكينها لمشروع Cloud.
ضمن مفتاح واجهة برمجة التطبيقات، انقر على رمز النسخ إلى الحافظة .
في أسفل الشاشة، انقر على حفظ.

يستدعي المثال التالي ScriptApp.getOAuthToken() لكي يتمكن من تمرير رمز الدخول المميز لبروتوكول OAuth 2.0 إلى أداة الاختيار. يمنع هذا الأسلوب من المنتقي من الحاجة إلى عرض مربع حوار التفويض الخاص به، ولكن لا يمكن ذلك إلا إذا كان نطاق OAuth الذي يحتاجه منتقي متاحًا في برمجة التطبيقات. وبخلاف ذلك، يجب أن يعلن رمز المنتقي عن نطاقات OAuth الخاصة به، كما هو موضح في مثال "مرحبًا بالجميع".

يجب عليك الاتصال بـ setOrigin(google.script.host.origin) عند إنشاء PickerBuilder.

code.gs

المنتقي/الرمز

العرض على GitHub

/**
 * Creates a custom menu in Google Sheets when the spreadsheet opens.
 */
function onOpen() {
  try {
    SpreadsheetApp.getUi().createMenu('Picker')
        .addItem('Start', 'showPicker')
        .addToUi();
  } catch (e) {
    // TODO (Developer) - Handle exception
    console.log('Failed with error: %s', e.error);
  }
}

/**
 * Displays an HTML-service dialog in Google Sheets that contains client-side
 * JavaScript code for the Google Picker API.
 */
function showPicker() {
  try {
    const html = HtmlService.createHtmlOutputFromFile('dialog.html')
        .setWidth(600)
        .setHeight(425)
        .setSandboxMode(HtmlService.SandboxMode.IFRAME);
    SpreadsheetApp.getUi().showModalDialog(html, 'Select a file');
  } catch (e) {
    // TODO (Developer) - Handle exception
    console.log('Failed with error: %s', e.error);
  }
}

/**
 * Gets the user's OAuth 2.0 access token so that it can be passed to Picker.
 * This technique keeps Picker from needing to show its own authorization
 * dialog, but is only possible if the OAuth scope that Picker needs is
 * available in Apps Script. In this case, the function includes an unused call
 * to a DriveApp method to ensure that Apps Script requests access to all files
 * in the user's Drive.
 *
 * @return {string} The user's OAuth 2.0 access token.
 */
function getOAuthToken() {
  try {
    DriveApp.getRootFolder();
    return ScriptApp.getOAuthToken();
  } catch (e) {
    // TODO (Developer) - Handle exception
    console.log('Failed with error: %s', e.error);
  }
}

مربع حوار.html

منتقي/مربع حوار.html

العرض على GitHub

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="https://ssl.gstatic.com/docs/script/css/add-ons.css">
  <script>
    // IMPORTANT: Replace the value for DEVELOPER_KEY with the API key obtained
    // from the Google Developers Console.
    var DEVELOPER_KEY = 'ABC123 ... ';
    var DIALOG_DIMENSIONS = {width: 600, height: 425};
    var pickerApiLoaded = false;

    /**
     * Loads the Google Picker API.
     */
    function onApiLoad() {
      gapi.load('picker', {'callback': function() {
        pickerApiLoaded = true;
      }});
     }

    /**
     * Gets the user's OAuth 2.0 access token from the server-side script so that
     * it can be passed to Picker. This technique keeps Picker from needing to
     * show its own authorization dialog, but is only possible if the OAuth scope
     * that Picker needs is available in Apps Script. Otherwise, your Picker code
     * will need to declare its own OAuth scopes.
     */
    function getOAuthToken() {
      google.script.run.withSuccessHandler(createPicker)
          .withFailureHandler(showError).getOAuthToken();
    }

    /**
     * Creates a Picker that can access the user's spreadsheets. This function
     * uses advanced options to hide the Picker's left navigation panel and
     * default title bar.
     *
     * @param {string} token An OAuth 2.0 access token that lets Picker access the
     *     file type specified in the addView call.
     */
    function createPicker(token) {
      if (pickerApiLoaded && token) {
        var picker = new google.picker.PickerBuilder()
            // Instruct Picker to display only spreadsheets in Drive. For other
            // views, see https://developers.google.com/picker/docs/#otherviews
            .addView(google.picker.ViewId.SPREADSHEETS)
            // Hide the navigation panel so that Picker fills more of the dialog.
            .enableFeature(google.picker.Feature.NAV_HIDDEN)
            // Hide the title bar since an Apps Script dialog already has a title.
            .hideTitleBar()
            .setOAuthToken(token)
            .setDeveloperKey(DEVELOPER_KEY)
            .setCallback(pickerCallback)
            .setOrigin(google.script.host.origin)
            // Instruct Picker to fill the dialog, minus 2 pixels for the border.
            .setSize(DIALOG_DIMENSIONS.width - 2,
                DIALOG_DIMENSIONS.height - 2)
            .build();
        picker.setVisible(true);
      } else {
        showError('Unable to load the file picker.');
      }
    }

    /**
     * A callback function that extracts the chosen document's metadata from the
     * response object. For details on the response object, see
     * https://developers.google.com/picker/docs/result
     *
     * @param {object} data The response object.
     */
    function pickerCallback(data) {
      var action = data[google.picker.Response.ACTION];
      if (action == google.picker.Action.PICKED) {
        var doc = data[google.picker.Response.DOCUMENTS][0];
        var id = doc[google.picker.Document.ID];
        var url = doc[google.picker.Document.URL];
        var title = doc[google.picker.Document.NAME];
        document.getElementById('result').innerHTML =
            '<b>You chose:</b><br>Name: <a href="' + url + '">' + title +
            '</a><br>ID: ' + id;
      } else if (action == google.picker.Action.CANCEL) {
        document.getElementById('result').innerHTML = 'Picker canceled.';
      }
    }

    /**
     * Displays an error message within the #result element.
     *
     * @param {string} message The error message to display.
     */
    function showError(message) {
      document.getElementById('result').innerHTML = 'Error: ' + message;
    }
  </script>
</head>
<body>
  <div>
    <button onclick="getOAuthToken()">Select a file</button>
    <p id="result"></p>
  </div>
  <script src="https://apis.google.com/js/api.js?onload=onApiLoad"></script>
</body>
</html>