Class Ui

واجهة المستخدم

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

// Display a dialog box with a title, message, input field, and "Yes" and "No" buttons. The
// user can also close the dialog by clicking the close button in its title bar.
var ui = SpreadsheetApp.getUi();
var response = ui.prompt('Getting to know you', 'May I know your name?', ui.ButtonSet.YES_NO);

// Process the user's response.
if (response.getSelectedButton() == ui.Button.YES) {
  Logger.log('The user\'s name is %s.', response.getResponseText());
} else if (response.getSelectedButton() == ui.Button.NO) {
  Logger.log('The user didn\'t want to provide a name.');
} else {
  Logger.log('The user clicked the close button in the dialog\'s title bar.');
}

أماكن إقامة

الموقعTypeالوصف
ButtonButtonتعداد يمثّل أزرار مربّع حوار مترجَمة محدّدة مسبقًا يعرضها تنبيه أو PromptResponse.getSelectedButton() للإشارة إلى الزرّ الذي نقر عليه المستخدم في مربّع الحوار.
ButtonSetButtonSetيشير هذا المصطلح إلى تعداد يمثّل مجموعات مترجَمة ومحددة مسبقًا لأزرار مربّع حوار واحدة أو أكثر يمكن إضافتها إلى تنبيه أو رسالة مطالبة.

الطُرق

الطريقةنوع القيمة التي يتم إرجاعهاوصف قصير
alert(prompt)Buttonيتم فتح مربع حوار في أداة تعديل المستخدم يتضمّن الرسالة المعنيّة والزر "حسنًا".
alert(prompt, buttons)Buttonيتم فتح مربّع حوار في أداة تعديل المستخدم يتضمّن الرسالة المحدّدة ومجموعة الأزرار.
alert(title, prompt, buttons)Buttonيفتح مربع حوار في أداة تعديل المستخدم يحتوي على العنوان والرسالة ومجموعة الأزرار المحددة.
createAddonMenu()Menuتنشئ أداة إنشاء يمكن استخدامها لإدراج قائمة فرعية في قائمة "الإضافات" بالمحرر.
createMenu(caption)Menuتنشئ أداة إنشاء يمكن استخدامها لإضافة قائمة إلى واجهة مستخدم المحرر.
prompt(prompt)PromptResponseلفتح مربع حوار إدخال في أداة تعديل المستخدم يحتوي على الرسالة المحددة والزر "حسنًا".
prompt(prompt, buttons)PromptResponseيتم فتح مربع حوار إدخال في أداة تعديل المستخدم يحتوي على الرسالة المحدّدة ومجموعة الأزرار.
prompt(title, prompt, buttons)PromptResponseلفتح مربع حوار إدخال في محرر المستخدم مع العنوان والرسالة ومجموعة الأزرار المعينة.
showModalDialog(userInterface, title)voidيفتح مربع حوار نمطي في محرِّر المستخدم مع محتوى مخصَّص من جهة العميل.
showModelessDialog(userInterface, title)voidيتم فتح مربع حوار بلا نمط في محرِّر المستخدم ويتضمّن محتوى مخصّصًا من جهة العميل.
showSidebar(userInterface)voidيفتح هذا الزر شريطًا جانبيًا في محرّر المستخدم يضم محتوى مخصّصًا من جهة العميل.

الوثائق التفصيلية

alert(prompt)

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

// Display "Hello, world" in a dialog box with an "OK" button. The user can also close the
// dialog by clicking the close button in its title bar.
SpreadsheetApp.getUi().alert('Hello, world');

المَعلمات

الاسمTypeالوصف
promptStringالرسالة التي سيتم عرضها في مربّع الحوار.

استرجاع الكرة

Button - الزر الذي نقر عليه المستخدم


alert(prompt, buttons)

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

// Display a dialog box with a message and "Yes" and "No" buttons. The user can also close the
// dialog by clicking the close button in its title bar.
var ui = SpreadsheetApp.getUi();
var response = ui.alert('Are you sure you want to continue?', ui.ButtonSet.YES_NO);

// Process the user's response.
if (response == ui.Button.YES) {
  Logger.log('The user clicked "Yes."');
} else {
  Logger.log('The user clicked "No" or the close button in the dialog\'s title bar.');
}

المَعلمات

الاسمTypeالوصف
promptStringالرسالة التي سيتم عرضها في مربّع الحوار.
buttonsButtonSetالزر الذي يتم عرضه في مربع الحوار.

استرجاع الكرة

Button - الزر الذي نقر عليه المستخدم


alert(title, prompt, buttons)

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

// Display a dialog box with a title, message, and "Yes" and "No" buttons. The user can also
// close the dialog by clicking the close button in its title bar.
var ui = SpreadsheetApp.getUi();
var response = ui.alert('Confirm', 'Are you sure you want to continue?', ui.ButtonSet.YES_NO);

// Process the user's response.
if (response == ui.Button.YES) {
  Logger.log('The user clicked "Yes."');
} else {
  Logger.log('The user clicked "No" or the close button in the dialog\'s title bar.');
}

المَعلمات

الاسمTypeالوصف
titleStringالعنوان الذي سيتم عرضه أعلى مربع الحوار.
promptStringالرسالة التي سيتم عرضها في مربّع الحوار.
buttonsButtonSetالزر الذي يتم عرضه في مربع الحوار.

استرجاع الكرة

Button - الزر الذي نقر عليه المستخدم


createAddonMenu()

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

// Add an item to the Add-on menu, under a sub-menu whose name is set automatically.
function onOpen(e) {
  SpreadsheetApp.getUi()
      .createAddonMenu()
      .addItem('Show', 'showSidebar')
      .addToUi();
}

استرجاع الكرة

Menu — أداة إنشاء القوائم الجديدة


createMenu(caption)

تنشئ أداة إنشاء يمكن استخدامها لإضافة قائمة إلى واجهة مستخدم المحرر. لن تتم إضافة القائمة في الواقع حتى يتم استدعاء Menu.addToUi(). لمزيد من المعلومات، اطّلِع على دليل استخدام القوائم. يجب أن تكون تسمية قائمة المستوى الأعلى في العنوان الرئيسي (جميع الكلمات الرئيسية مكتوبة بأحرف كبيرة)، على الرغم من أن تسمية القائمة الفرعية يجب أن تكون في حالة جملة (فقط الكلمة الأولى بأحرف كبيرة). إذا تم نشر النص البرمجي كإضافة، يتم تجاهل المعلَمة caption وتتم إضافة القائمة كقائمة فرعية من قائمة "الإضافات"، تعادل createAddonMenu().

// Add a custom menu to the active document, including a separator and a sub-menu.
function onOpen(e) {
  SpreadsheetApp.getUi()
      .createMenu('My Menu')
      .addItem('My menu item', 'myFunction')
      .addSeparator()
      .addSubMenu(SpreadsheetApp.getUi().createMenu('My sub-menu')
          .addItem('One sub-menu item', 'mySecondFunction')
          .addItem('Another sub-menu item', 'myThirdFunction'))
      .addToUi();
}

المَعلمات

الاسمTypeالوصف
captionStringتصنيف القائمة، مع كتابة جميع الكلمات الرئيسية بأحرف كبيرة في قائمة الطعام ذات المستوى الأعلى، أو كتابة الكلمة الأولى فقط بأحرف كبيرة لقائمة فرعية

استرجاع الكرة

Menu — أداة إنشاء القوائم الجديدة


prompt(prompt)

لفتح مربع حوار إدخال في أداة تعديل المستخدم يحتوي على الرسالة المحددة والزر "حسنًا". تعلِّق هذه الطريقة النص البرمجي من جهة الخادم عندما يكون مربّع الحوار مفتوحًا. ويتم استئناف النص البرمجي بعد أن يغلق المستخدم مربّع الحوار، ولكن لن تظلّ الاتصالات Jdbc وأقفال LockService تستمرّ خلال فترة التعليق. لمزيد من المعلومات، اطّلِع على دليل إلى مربّعات الحوار والأشرطة الجانبية.

// Display a dialog box with a message, input field, and an "OK" button. The user can also
// close the dialog by clicking the close button in its title bar.
var ui = SpreadsheetApp.getUi();
var response = ui.prompt('Enter your name:');

// Process the user's response.
if (response.getSelectedButton() == ui.Button.OK) {
  Logger.log('The user\'s name is %s.', response.getResponseText());
} else {
  Logger.log('The user clicked the close button in the dialog\'s title bar.');
}

المَعلمات

الاسمTypeالوصف
promptStringالرسالة التي سيتم عرضها في مربّع الحوار.

استرجاع الكرة

PromptResponse - تمثيل لردّ المستخدم


prompt(prompt, buttons)

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

// Display a dialog box with a message, input field, and "Yes" and "No" buttons. The user can
// also close the dialog by clicking the close button in its title bar.
var ui = SpreadsheetApp.getUi();
var response = ui.prompt('May I know your name?', ui.ButtonSet.YES_NO);

// Process the user's response.
if (response.getSelectedButton() == ui.Button.YES) {
  Logger.log('The user\'s name is %s.', response.getResponseText());
} else if (response.getSelectedButton() == ui.Button.NO) {
  Logger.log('The user didn\'t want to provide a name.');
} else {
  Logger.log('The user clicked the close button in the dialog\'s title bar.');
}

المَعلمات

الاسمTypeالوصف
promptStringالرسالة التي سيتم عرضها في مربّع الحوار.
buttonsButtonSetالزر الذي يتم عرضه في مربع الحوار.

استرجاع الكرة

PromptResponse - تمثيل لردّ المستخدم


prompt(title, prompt, buttons)

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

// Display a dialog box with a title, message, input field, and "Yes" and "No" buttons. The
// user can also close the dialog by clicking the close button in its title bar.
var ui = SpreadsheetApp.getUi();
var response = ui.prompt('Getting to know you', 'May I know your name?', ui.ButtonSet.YES_NO);

// Process the user's response.
if (response.getSelectedButton() == ui.Button.YES) {
  Logger.log('The user\'s name is %s.', response.getResponseText());
} else if (response.getSelectedButton() == ui.Button.NO) {
  Logger.log('The user didn\'t want to provide a name.');
} else {
  Logger.log('The user clicked the close button in the dialog\'s title bar.');
}

المَعلمات

الاسمTypeالوصف
titleStringالعنوان الذي سيتم عرضه أعلى مربع الحوار.
promptStringالرسالة التي سيتم عرضها في مربّع الحوار.
buttonsButtonSetالزر الذي يتم عرضه في مربع الحوار.

استرجاع الكرة

PromptResponse - تمثيل لردّ المستخدم


showModalDialog(userInterface, title)

يفتح مربع حوار نمطي في محرِّر المستخدم مع محتوى مخصَّص من جهة العميل. لا تعلِّق هذه الطريقة النص البرمجي من جهة الخادم عندما يكون مربّع الحوار مفتوحًا. للاتصال بالنص البرمجي من جهة الخادم، يجب أن يجري المكوّن من جهة العميل عمليات استدعاء غير متزامنة باستخدام google.script API لـ HtmlService. لإغلاق مربّع الحوار بشكل آلي، اتّصِل بـ google.script.host.close() من جهة العميل لتطبيق الويب HtmlService. لمزيد من المعلومات، يمكنك الاطّلاع على دليل مربّعات الحوار والأشرطة الجانبية.

تمنع مربّعات الحوار المشروطة المستخدم من التفاعل مع أي شيء آخر غير مربّع الحوار. على النقيض من ذلك، تسمح مربعات الحوار غير المنتظمة والأشرطة الجانبية للمستخدم بالتفاعل مع المحرر. في جميع الحالات تقريبًا، يعد مربع الحوار المشروط أو الشريط الجانبي خيارًا أفضل من مربع الحوار بلا نمط.

// Display a modal dialog box with custom HtmlService content.
var htmlOutput = HtmlService
    .createHtmlOutput('<p>A change of speed, a change of style...</p>')
    .setWidth(250)
    .setHeight(300);
SpreadsheetApp.getUi().showModalDialog(htmlOutput, 'My add-on');

المَعلمات

الاسمTypeالوصف
userInterfaceObjectتمثّل هذه السمة HtmlOutput الواجهة المطلوب عرضها.
titleStringعنوان مربّع الحوار، ويؤدي إلى إلغاء أي عنوان تم ضبطه من خلال استدعاء setTitle() على الكائن userInterface.

التفويض

تتطلب النصوص البرمجية التي تستخدم هذه الطريقة الحصول على تفويض باستخدام واحد أو أكثر من النطاقات التالية:

  • https://www.googleapis.com/auth/script.container.ui

showModelessDialog(userInterface, title)

يتم فتح مربع حوار بلا نمط في محرِّر المستخدم ويتضمّن محتوى مخصّصًا من جهة العميل. لا تعلّق هذه الطريقة النص البرمجي من جهة الخادم عندما يكون مربّع الحوار مفتوحًا. للاتصال بالنص البرمجي من جهة الخادم، يجب أن يجري المكوِّن من جهة العميل عمليات استدعاء غير متزامنة باستخدام google.script API لـ HtmlService. لإغلاق مربّع الحوار بشكل آلي، اتّصِل بـ google.script.host.close() من جهة العميل لتطبيق الويب HtmlService. لمزيد من المعلومات، يمكنك الاطّلاع على دليل مربّعات الحوار والأشرطة الجانبية.

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

// Display a modeless dialog box with custom HtmlService content.
var htmlOutput = HtmlService
    .createHtmlOutput('<p>A change of speed, a change of style...</p>')
    .setWidth(250)
    .setHeight(300);
SpreadsheetApp.getUi().showModelessDialog(htmlOutput, 'My add-on');

المَعلمات

الاسمTypeالوصف
userInterfaceObjectتمثّل هذه السمة HtmlOutput الواجهة المطلوب عرضها.
titleStringعنوان مربّع الحوار، ويؤدي إلى إلغاء أي عنوان تم ضبطه من خلال استدعاء setTitle() على الكائن userInterface.

التفويض

تتطلب النصوص البرمجية التي تستخدم هذه الطريقة الحصول على تفويض باستخدام واحد أو أكثر من النطاقات التالية:

  • https://www.googleapis.com/auth/script.container.ui

showSidebar(userInterface)

يفتح هذا الزر شريطًا جانبيًا في محرّر المستخدم يضم محتوى مخصّصًا من جهة العميل. لا تعلّق هذه الطريقة النص البرمجي من جهة الخادم عندما يكون الشريط الجانبي مفتوحًا. للاتصال بالنص البرمجي من جهة الخادم، يجب أن يجري المكوّن من جهة العميل عمليات استدعاء غير متزامنة باستخدام google.script API لـ HtmlService. لإغلاق الشريط الجانبي آليًا، يمكنك استدعاء الدالة google.script.host.close() من جهة العميل لتطبيق الويب HtmlService. لمزيد من المعلومات، يمكنك الاطّلاع على دليل مربّعات الحوار والأشرطة الجانبية.

يظهر الشريط الجانبي على يمين المحرر للمستخدمين الذين تستخدم بيئاتهم لغة من اليسار إلى اليمين، وعلى الجانب الأيسر من المحرّر للغات التي تُكتب من اليمين إلى اليسار. يبلغ عرض جميع الأشرطة الجانبية التي تظهر من خلال النصوص البرمجية 300 بكسل.

// Display a sidebar with custom HtmlService content.
var htmlOutput = HtmlService
    .createHtmlOutput('<p>A change of speed, a change of style...</p>')
    .setTitle('My add-on');
SpreadsheetApp.getUi().showSidebar(htmlOutput);

المَعلمات

الاسمTypeالوصف
userInterfaceObjectتمثّل هذه السمة HtmlOutput الواجهة المطلوب عرضها.

التفويض

تتطلب النصوص البرمجية التي تستخدم هذه الطريقة الحصول على تفويض باستخدام واحد أو أكثر من النطاقات التالية:

  • https://www.googleapis.com/auth/script.container.ui

الطرق المتوقّفة نهائيًا