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');

المعلمات

الاسمالنوعالوصف
nameStringقيمة سمة اسم العلامة الوصفية
contentStringقيمة سمة محتوى العلامة الوصفية

الإرجاع

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

المعلمات

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

الإرجاع

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

عمليات الرمي

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

انظر أيضًا

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

المعلمات

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

الإرجاع

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

عمليات الرمي

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

انظر أيضًا

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 التي تم إنشاؤها حديثًا مؤقتًا لحدود قياسية أكثر صرامة.

المعلمات

الاسمالنوعالوصف
contentTypeStringنوع 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>');

المعلمات

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

الإرجاع

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');

المعلمات

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

الإرجاع

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

setHeight(height)

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

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

المعلمات

الاسمالنوعالوصف
heightIntegerالارتفاع الجديد بالبكسل. يؤدي إدخال 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>

المعلمات

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

الإرجاع

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

setTitle(title)

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

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

المعلمات

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

الإرجاع

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

setWidth(width)

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

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

المعلمات

الاسمالنوعالوصف
widthIntegerالعرض الجديد بالبكسل. يؤدي إدخال 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);

المعلمات

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

الإرجاع

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