Class Ui

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.
const ui = SpreadsheetApp.getUi();
const 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.');
}

الخصائص

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

الطُرق

الطريقة	نوع القيمة التي تم إرجاعها	وصف قصير
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	يفتح شريطًا جانبيًا في محرِّر المستخدم يتضمّن محتوًى مخصّصًا من جهة العميل.

الطرق المتوقّفة

الطريقة	نوع القيمة التي تم إرجاعها	وصف قصير
showDialog(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');

المَعلمات

الاسم	النوع	الوصف
prompt	String	الرسالة المطلوب عرضها في مربّع الحوار

الإرجاع

‫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.
const ui = SpreadsheetApp.getUi();
const 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.',
  );
}

المَعلمات

الاسم	النوع	الوصف
prompt	String	الرسالة المطلوب عرضها في مربّع الحوار
buttons	ButtonSet	مجموعة الأزرار التي سيتم عرضها في مربّع الحوار

الإرجاع

‫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.
const ui = SpreadsheetApp.getUi();
const 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.',
  );
}

المَعلمات

الاسم	النوع	الوصف
title	String	عنوان سيتم عرضه أعلى مربّع الحوار.
prompt	String	الرسالة المطلوب عرضها في مربّع الحوار
buttons	ButtonSet	مجموعة الأزرار التي سيتم عرضها في مربّع الحوار

الإرجاع

‫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();
}

المَعلمات

الاسم	النوع	الوصف
caption	String	تمثّل هذه السمة تصنيف القائمة، مع كتابة جميع الكلمات الرئيسية بأحرف كبيرة في القائمة ذات المستوى الأعلى، أو كتابة الكلمة الأولى فقط بأحرف كبيرة في القائمة الفرعية.

الإرجاع

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.
const ui = SpreadsheetApp.getUi();
const 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.');
}

المَعلمات

الاسم	النوع	الوصف
prompt	String	الرسالة المطلوب عرضها في مربّع الحوار

الإرجاع

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.
const ui = SpreadsheetApp.getUi();
const 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.');
}

المَعلمات

الاسم	النوع	الوصف
prompt	String	الرسالة المطلوب عرضها في مربّع الحوار
buttons	ButtonSet	مجموعة الأزرار التي سيتم عرضها في مربّع الحوار

الإرجاع

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.
const ui = SpreadsheetApp.getUi();
const 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.');
}

المَعلمات

الاسم	النوع	الوصف
title	String	عنوان سيتم عرضه أعلى مربّع الحوار.
prompt	String	الرسالة المطلوب عرضها في مربّع الحوار
buttons	ButtonSet	مجموعة الأزرار التي سيتم عرضها في مربّع الحوار

الإرجاع

PromptResponse: تمثّل هذه السمة استجابة المستخدم.

---

showModalDialog(userInterface, title)

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

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

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

المَعلمات

الاسم	النوع	الوصف
userInterface	Object	تمثّل هذه السمة الواجهة المطلوب عرضها.HtmlOutput
title	String	تمثّل هذه السمة عنوان مربّع الحوار، وهي تلغي أي عنوان تم ضبطه من خلال استدعاء setTitle() على العنصر userInterface.

التفويض

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

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

---

showModelessDialog(userInterface, title)

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

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

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

المَعلمات

الاسم	النوع	الوصف
userInterface	Object	تمثّل هذه السمة الواجهة المطلوب عرضها.HtmlOutput
title	String	تمثّل هذه السمة عنوان مربّع الحوار، وهي تلغي أي عنوان تم ضبطه من خلال استدعاء setTitle() على العنصر userInterface.

التفويض

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

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

---

showSidebar(userInterface)

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

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

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

المَعلمات

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

التفويض

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

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

الطرق المتوقّفة

showDialog(userInterface)

تمّت إزالة هذا العمود. تم إيقاف هذه الطريقة نهائيًا اعتبارًا من مارس 2014. البديل المباشر هو showModelessDialog(userInterface, title)، ولكن showModalDialog(userInterface, title) هو خيار أفضل في جميع الحالات تقريبًا.

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

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

المَعلمات

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

التفويض

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

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