Class HtmlOutput

Htmlالإخراج

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

function doGet() {
  return HtmlService.createHtmlOutput('<b>Hello, world!</b>');
}

يمكن أن يتضمّن الرمز في HtmlOutput JavaScript وCSS مضمّنين. (هذه هي لغة JavaScript العادية من جهة العميل التي تتعامل مع DOM، وليس "برمجة التطبيقات"). ويتم وضع كل هذا المحتوى في بيئة معزولة باستخدام وضع بيئة معزولة في إطار iframe. لمزيد من المعلومات، يُرجى الاطّلاع على دليل القيود المفروضة على خدمة HTML.

الطُرق

الطريقة	نوع القيمة التي يتم عرضها	وصف قصير
addMetaTag(name, content)	HtmlOutput	تُضيف علامة وصفية إلى الصفحة.
append(addedContent)	HtmlOutput	إلحاق محتوى جديد بمحتوى هذا HtmlOutput
appendUntrusted(addedContent)	HtmlOutput	تُلحق محتوى جديدًا بمحتوى هذا العنصر HtmlOutput باستخدام علامات الهروب السياقية.
asTemplate()	HtmlTemplate	عرض HtmlTemplate مستندة إلى هذا HtmlOutput
clear()	HtmlOutput	يؤدي إلى محو المحتوى الحالي.
getAs(contentType)	Blob	عرض البيانات داخل هذا العنصر كبيانات ثنائية كبيرة تم تحويلها إلى نوع المحتوى المحدّد
getBlob()	Blob	عرض البيانات داخل هذا الكائن ككتلة بيانات
getContent()	String	تحصل على محتوى هذا HtmlOutput.
getFaviconUrl()	String	تحصل على عنوان URL لعلامة رابط رمز مفضّل تمت إضافتها إلى الصفحة من خلال استدعاء setFaviconUrl(iconUrl).
getHeight()	Integer	تحصل على الارتفاع الأولي للمربّع الحوار المخصّص في "مستندات Google" أو "جداول بيانات Google" أو "نماذج Google".
getMetaTags()	HtmlOutputMetaTag[]	تحصل على صفيف من العناصر التي تمثّل العلامات الوصفية التي تمت إضافتها إلى الصفحة من خلال استدعاء addMetaTag(name, content).
getTitle()	String	تحصل على عنوان صفحة الإخراج.
getWidth()	Integer	تحصل على العرض الأولي للمربّع الحوار المخصّص في "مستندات Google" أو "جداول بيانات Google" أو "نماذج Google".
setContent(content)	HtmlOutput	لضبط محتوى هذا HtmlOutput.
setFaviconUrl(iconUrl)	HtmlOutput	تُضيف علامة رابط لرمز favicon إلى الصفحة.
setHeight(height)	HtmlOutput	لضبط الارتفاع الأولي لحوار مخصّص في "مستندات Google" أو "جداول بيانات Google" أو "نماذج Google"
setSandboxMode(mode)	HtmlOutput	لا تؤثّر هذه الطريقة الآن، فقد كانت في السابق تضبط sandbox mode المستخدَم للنصوص البرمجية من جهة العميل.
setTitle(title)	HtmlOutput	تُستخدَم لضبط عنوان صفحة الإخراج.
setWidth(width)	HtmlOutput	لضبط العرض الأولي لحوار مخصّص في "مستندات Google" أو "جداول بيانات Google" أو "نماذج Google"
setXFrameOptionsMode(mode)	HtmlOutput	تُحدِّد حالة عنوان X-Frame-Options للصفحة، والذي يتحكّم في منع هجمات التلاعب بالنقر.

مستندات تفصيلية

addMetaTag(name, content)

تُضيف علامة وصفية إلى الصفحة. يتم تجاهل العلامات الوصفية المضمّنة مباشرةً في ملف HTML في "برمجة تطبيقات Google". يُسمح فقط بالعلامات الوصفية التالية:

<meta name="apple-mobile-web-app-capable" content="..."/>
<meta name="google-site-verification" content="..."/>
<meta name="mobile-web-app-capable" content="..."/>
<meta name="viewport" content="..."/>

const output = HtmlService.createHtmlOutput('<b>Hello, world!</b>');
output.addMetaTag('viewport', 'width=device-width, initial-scale=1');

المعلمات

الاسم	النوع	الوصف
name	String	قيمة سمة اسم العلامة الوصفية
content	String	قيمة سمة محتوى العلامة الوصفية

الإرجاع

HtmlOutput - هذا الناتج، لإنشاء سلاسل.

---

append(addedContent)

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

// Log "<b>Hello, world!</b><p>Hello again, world.</p>"
const output = HtmlService.createHtmlOutput('<b>Hello, world!</b>');
output.append('<p>Hello again, world.</p>');
Logger.log(output.getContent());

المعلمات

الاسم	النوع	الوصف
addedContent	String	المحتوى الذي تريد إلحاقه

الإرجاع

HtmlOutput - هذا الناتج، لإنشاء سلاسل.

عمليات الرمي

Error - إذا كان تنسيق HTML غير صحيح

انظر أيضًا

• appendUntrusted(addedContent)

---

appendUntrusted(addedContent)

تُلحق محتوى جديدًا بمحتوى هذا العنصر HtmlOutput باستخدام علامات الهروب السياقية.

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

// Log "<b>Hello, world!</b>&lt;p&gt;Hello again, world.&lt;/p&gt;"
const output = HtmlService.createHtmlOutput('<b>Hello, world!</b>');
output.appendUntrusted('<p>Hello again, world.</p>');
Logger.log(output.getContent());

المعلمات

الاسم	النوع	الوصف
addedContent	String	المحتوى الذي تريد إلحاقه

الإرجاع

HtmlOutput - هذا الناتج، لإنشاء سلاسل.

عمليات الرمي

Error - إذا كان تنسيق HTML غير صحيح على الإطلاق

انظر أيضًا

• append(addedContent)

---

asTemplate()

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

const output = HtmlService.createHtmlOutput('<b>Hello, world!</b>');
const template = output.asTemplate();

الإرجاع

HtmlTemplate — HtmlTemplate الجديدة

---

clear()

يؤدي إلى محو المحتوى الحالي.

const output = HtmlService.createHtmlOutput('<b>Hello, world!</b>');
output.clear();

الإرجاع

HtmlOutput - هذا الناتج، لإنشاء سلاسل.

---

getAs(contentType)

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

للاطّلاع على الحصص اليومية للإحالات الناجحة، يُرجى الاطّلاع على الحصص لخدمات Google. قد تخضع نطاقات Google Workspace التي تم إنشاؤها حديثًا مؤقتًا لحدود قياسية أكثر صرامة.

المعلمات

الاسم	النوع	الوصف
contentType	String	نوع MIME المطلوب التحويل إليه بالنسبة إلى معظم العناصر المصغّرة، يكون 'application/pdf' هو الخيار الوحيد الصالح. بالنسبة إلى الصور بتنسيق BMP أو GIF أو JPEG أو PNG، يمكن استخدام أي من 'image/bmp' أو 'image/gif' أو 'image/jpeg' أو 'image/png' أيضًا. بالنسبة إلى مستند "مستندات Google"، يكون 'text/markdown' صالحًا أيضًا.

الإرجاع

‫Blob: البيانات بتنسيق ملف نصي

---

getBlob()

عرض البيانات داخل هذا الكائن ككتلة بيانات

الإرجاع

‫Blob: البيانات بتنسيق ملف نصي

---

getContent()

تحصل على محتوى هذا HtmlOutput.

// Log "<b>Hello, world!</b>"
const output = HtmlService.createHtmlOutput('<b>Hello, world!</b>');
Logger.log(output.getContent());

الإرجاع

String: المحتوى الذي يتم عرضه

---

getFaviconUrl()

تحصل على عنوان URL لعلامة رابط رمز مفضّل تمت إضافتها إلى الصفحة من خلال استدعاء setFaviconUrl(iconUrl). يتم تجاهل علامات روابط الرموز المفضّلة المضمّنة مباشرةً في ملف HTML في Apps Script.

const output = HtmlService.createHtmlOutput('<b>Hello, world!</b>');
output.setFaviconUrl('http://www.example.com/image.png');
Logger.log(output.getFaviconUrl());

الإرجاع

‫String: عنوان URL لصورة الرمز المفضّل

---

getHeight()

تحصل على الارتفاع الأولي للمربّع الحوار المخصّص في "مستندات Google" أو "جداول بيانات Google" أو "نماذج Google". إذا تم نشر HtmlOutput كتطبيق ويب بدلاً من ذلك، تعرض هذه المحاولةnull. لتغيير حجم مربّع حوار مفتوح، استخدِم google.script.host.setHeight(height) في الرمز البرمجي من جهة العميل.

const output = HtmlService.createHtmlOutput('<b>Hello, world!</b>');
output.setHeight(200);
Logger.log(output.getHeight());

الإرجاع

‫Integer: الارتفاع بالبكسل

---

getMetaTags()

تحصل على صفيف من العناصر التي تمثّل العلامات الوصفية التي تمت إضافتها إلى الصفحة من خلال استدعاء addMetaTag(name, content). يتم تجاهل العلامات الوصفية المضمّنة مباشرةً في ملف HTML في "برمجة تطبيقات Google".

const output = HtmlService.createHtmlOutput('<b>Hello, world!</b>');
output.addMetaTag('viewport', 'width=device-width, initial-scale=1');

const tags = output.getMetaTags();
Logger.log(
    '<meta name="%s" content="%s"/>',
    tags[0].getName(),
    tags[0].getContent(),
);

الإرجاع

HtmlOutputMetaTag[]: مصفوفة من العناصر التي تمثّل العلامات الوصفية التي تمت إضافتها إلى الصفحة من خلال استدعاء addMetaTag(name, content).

---

getTitle()

تحصل على عنوان صفحة الإخراج. يُرجى العلم أنّه يتم تجاهل عنصر HTML‏ <title>.

const output = HtmlService.createHtmlOutput('<b>Hello, world!</b>');
Logger.log(output.getTitle());

الإرجاع

String: عنوان الصفحة.

---

getWidth()

تحصل على العرض الأولي للمربّع الحوار المخصّص في "مستندات Google" أو "جداول بيانات Google" أو "نماذج Google". إذا تم نشر HtmlOutput كتطبيق ويب بدلاً من ذلك، تعرض هذه المحاولةnull. لتغيير حجم مربّع حوار مفتوح، استخدِم google.script.host.setWidth(width) في الرمز البرمجي من جهة العميل.

const output = HtmlService.createHtmlOutput('<b>Hello, world!</b>');
output.setWidth(200);
Logger.log(output.getWidth());

الإرجاع

‫Integer: العرض بالبكسل

---

setContent(content)

لضبط محتوى هذا HtmlOutput.

const output = HtmlService.createHtmlOutput();
output.setContent('<b>Hello, world!</b>');

المعلمات

الاسم	النوع	الوصف
content	String	المحتوى المطلوب عرضه

الإرجاع

HtmlOutput - هذا الناتج، لإنشاء سلاسل.

عمليات الرمي

Error - إذا كان تنسيق HTML غير صحيح

---

setFaviconUrl(iconUrl)

تُضيف علامة رابط لرمز favicon إلى الصفحة. يتم تجاهل علامات روابط رمز التطبيقات المضمّنة مباشرةً في ملف HTML لتطبيق Apps Script.

const output = HtmlService.createHtmlOutput('<b>Hello, world!</b>');
output.setFaviconUrl('http://www.example.com/image.png');

المعلمات

الاسم	النوع	الوصف
iconUrl	String	عنوان URL لصورة الرمز المفضّل، مع إضافة الصورة التي تشير إلى نوع الصورة

الإرجاع

HtmlOutput - هذا الناتج، لإنشاء سلاسل.

---

setHeight(height)

لضبط الارتفاع الأولي لحوار مخصّص في "مستندات Google" أو "جداول بيانات Google" أو "نماذج Google" في حال نشر HtmlOutput كتطبيق ويب بدلاً من ذلك، لن يكون لهذه الطريقة أي تأثير. لتغيير حجم مربّع حوار مفتوح، استخدِم google.script.host.setHeight(height) في الرمز البرمجي من جهة العميل.

const output = HtmlService.createHtmlOutput('<b>Hello, world!</b>');
output.setHeight(200);

المعلمات

الاسم	النوع	الوصف
height	Integer	الارتفاع الجديد بالبكسل. يؤدي إدخال null إلى عرض قيمة تلقائية.

الإرجاع

HtmlOutput - هذا الناتج، لإنشاء سلاسل.

---

setSandboxMode(mode)

لا تؤثّر هذه الطريقة الآن، فقد كانت في السابق تضبط sandbox mode المستخدَم للنصوص البرمجية من جهة العميل. لحماية المستخدمين من عرض محتوى HTML أو JavaScript ضار، يتم تنفيذ الرمز البرمجي من جهة العميل الذي يتم عرضه من خدمة HTML في بيئة اختبار آمن تفرض بدورها قيودًا على الرمز البرمجي. في الأصل، كانت هذه الطريقة تسمح لمؤلفي النصوص البرمجية بالاختيار بين إصدارات مختلفة من وضع الحماية، ولكن الآن تستخدم جميع النصوص البرمجية وضع IFRAME بغض النظر عن وضع الحماية الذي تم ضبطه. لمزيد من المعلومات، يُرجى الاطّلاع على دليل القيود المفروضة على خدمة HTML.

يفرض وضع IFRAME قيودًا أقل بكثير من أوضاع وضع الحماية الأخرى ويشغّل الاختبار بشكل أسرع، ولكنه لا يعمل على الإطلاق في بعض المتصفحات القديمة، بما في ذلك Internet Explorer 9. يمكن قراءة وضع "منطقة اختبار التطبيقات" في نص برمجي من جهة العميل من خلال فحص google.script.sandbox.mode. تجدر الإشارة إلى أنّ هذه السمة تعرض الوضع الفعلي على العميل، والذي قد يختلف عن الوضع المطلوب على الخادم إذا لم يكن الوضع المطلوب متوافقًا في متصفّح المستخدم.

<!-- Read the sandbox mode (in a client-side script). -->
<script>
  alert(google.script.sandbox.mode);
</script>

المعلمات

الاسم	النوع	الوصف
mode	SandboxMode	وضع الحماية الذي تريد استخدامه

الإرجاع

HtmlOutput - هذا الناتج، لإنشاء سلاسل.

---

setTitle(title)

تُستخدَم لضبط عنوان صفحة الإخراج. بالنسبة إلى تطبيقات الويب، هذا هو عنوان الصفحة بأكملها، في حين أنّه بالنسبة إلى HtmlOutput المعروض في "جداول بيانات Google"، هذا هو عنوان مربّع الحوار.

const output = HtmlService.createHtmlOutput('<b>Hello, world!</b>');
output.setTitle('My First Page');

المعلمات

الاسم	النوع	الوصف
title	String	العنوان الجديد.

الإرجاع

HtmlOutput - هذا الناتج، لإنشاء سلاسل.

---

setWidth(width)

لضبط العرض الأولي لحوار مخصّص في "مستندات Google" أو "جداول بيانات Google" أو "نماذج Google" في حال نشر HtmlOutput كتطبيق ويب بدلاً من ذلك، لن يكون لهذه الطريقة أي تأثير. لتغيير حجم مربّع حوار مفتوح، استخدِم google.script.host.setWidth(width) في الرمز البرمجي من جهة العميل.

const output = HtmlService.createHtmlOutput('<b>Hello, world!</b>');
output.setWidth(200);

المعلمات

الاسم	النوع	الوصف
width	Integer	العرض الجديد بالبكسل. يؤدي إدخال null إلى عرض قيمة تلقائية.

الإرجاع

HtmlOutput - هذا الناتج، لإنشاء سلاسل.

---

setXFrameOptionsMode(mode)

تُحدِّد حالة عنوان X-Frame-Options للصفحة، والذي يتحكّم في منع هجمات التلاعب بالنقر.

يسمح الإعداد XFrameOptionsMode.ALLOWALL لأي موقع إلكتروني باستخدام إطار iframe للصفحة، لذا على المطوّر تنفيذ الحماية الخاصة به ضد خدعة النقر.

إذا لم يضبط نص برمجي وضع X-Frame-Options، يستخدم Apps Script وضع XFrameOptionsMode.DEFAULT كوضع تلقائي.

// Serve HTML with no X-Frame-Options header (in Apps Script server-side code).
const output = HtmlService.createHtmlOutput('<b>Hello, world!</b>');
output.setXFrameOptionsMode(HtmlService.XFrameOptionsMode.ALLOWALL);

المعلمات

الاسم	النوع	الوصف
mode	XFrameOptionsMode	وضع خيارات XFrame المطلوب ضبطه

الإرجاع

HtmlOutput - هذا الناتج، لإنشاء سلاسل.