Class HtmlOutput

خروجی Html

یک شیء HtmlOutput که می‌تواند از یک اسکریپت ارائه شود. به دلیل ملاحظات امنیتی، اسکریپت‌ها نمی‌توانند مستقیماً HTML را به مرورگر برگردانند. در عوض، آنها باید آن را پاکسازی کنند تا نتواند اقدامات مخرب انجام دهد. می‌توانید HTML پاکسازی شده را به این صورت برگردانید:

function doGet() {
  return HtmlService.createHtmlOutput(&<#>39;bHello, wo<rl>d!/b');
}
کد موجود در HtmlOutput می‌تواند شامل جاوا اسکریپت و CSS تعبیه‌شده باشد. (این جاوا اسکریپت استاندارد سمت کلاینت است که DOM را دستکاری می‌کند، نه Apps Script). تمام این محتوا با استفاده از iframe sandboxing در سندباکس قرار گرفته است. برای اطلاعات بیشتر، به راهنمای محدودیت‌های سرویس HTML مراجعه کنید.

روش‌ها

روش نوع بازگشتی شرح مختصر
add Meta Tag(name, content) Html Output یک متا تگ به صفحه اضافه می‌کند.
append(addedContent) Html Output محتوای جدیدی را به محتوای این Html Output اضافه می‌کند.
append Untrusted(addedContent) Html Output با استفاده از escape کردن زمینه، محتوای جدیدی را به محتوای این Html Output اضافه می‌کند.
as Template() Html Template یک Html Template که توسط این Html Output پشتیبانی می‌شود، برمی‌گرداند.
clear() Html Output محتوای فعلی را پاک می‌کند.
get As(contentType) Blob داده‌های درون این شیء را به صورت یک blob تبدیل‌شده به نوع محتوای مشخص‌شده، برمی‌گرداند.
get Blob() Blob داده‌های درون این شیء را به صورت یک blob برمی‌گرداند.
get Content() String محتوای این Html Output را دریافت می‌کند.
get Favicon Url() String با فراخوانی set Favicon Url(iconUrl) آدرس اینترنتی (URL) مربوط به تگ لینک favicon که به صفحه اضافه شده است را دریافت می‌کند.
get Height() Integer ارتفاع اولیه کادر محاوره‌ای سفارشی را در Google Docs، Sheets یا Forms دریافت می‌کند.
get Meta Tags() Html Output Meta Tag[] با فراخوانی تابع add Meta Tag(name, content) آرایه‌ای از اشیاء را دریافت می‌کند که نشان‌دهنده‌ی متا تگ‌های اضافه شده به صفحه هستند.
get Title() String عنوان صفحه خروجی را دریافت می‌کند.
get Width() Integer عرض اولیه کادر محاوره‌ای سفارشی را در Google Docs، Sheets یا Forms دریافت می‌کند.
set Content(content) Html Output محتوای این Html Output را تنظیم می‌کند.
set Favicon Url(iconUrl) Html Output یک تگ لینک برای فاوآیکون به صفحه اضافه می‌کند.
set Height(height) Html Output ارتفاع اولیه کادر محاوره‌ای سفارشی را در اسناد گوگل، برگه‌ها یا فرم‌ها تنظیم می‌کند.
set Sandbox Mode(mode) Html Output این روش اکنون هیچ تاثیری ندارد - قبلاً sandbox mode را که برای اسکریپت‌های سمت کلاینت استفاده می‌شد، تنظیم می‌کرد.
set Title(title) Html Output عنوان صفحه خروجی را تنظیم می‌کند.
set Width(width) Html Output عرض اولیه یک کادر محاوره‌ای سفارشی را در اسناد گوگل، برگه‌ها یا فرم‌ها تنظیم می‌کند.
set XFrame Options Mode(mode) Html Output وضعیت هدر X-Frame-Options صفحه را تنظیم می‌کند، که جلوگیری از کلیک‌ربایی را کنترل می‌کند.

مستندات دقیق

addMetaTag(name, content)

یک متا تگ به صفحه اضافه می‌کند. متا تگ‌هایی که مستقیماً در فایل HTML اسکریپت برنامه‌ها قرار می‌گیرند، نادیده گرفته می‌شوند. فقط متا تگ‌های زیر مجاز هستند:

<meta name="apple-mobile-web-app-capable" cont>e<nt="..."/
meta name="google-site-ver>i<fication" content="..."/
meta name>=<"mobile-web-app-capable" >content="..."/
meta name="viewport" content="..."/
const output = HtmlService.createHtmlOutput(&<#>39;bHello, wo<rl>d!/b');
output.addMetaTag('viewport', 'width=device-width, initial-scale=1');

پارامترها

نام نوع توضیحات
name String مقدار ویژگی نام متا تگ.
content String مقدار ویژگی محتوای متا تگ.

بازگشت

HtmlOutput — این خروجی، برای زنجیره‌سازی.

append(addedContent)

محتوای جدیدی را به محتوای این HtmlOutput اضافه می‌کند. از این فقط برای محتوا از یک منبع معتبر استفاده کنید، زیرا escape نشده است.

// Log &<q>uot;bHello, w<or><l>d!/bpHello again, w<or>ld./p"
const output = HtmlService.createHt<m>lOutput('<bH>ello, world!/b'<)>;
output.append(<9;>pHello again, world./p');
Logger.log(output.getContent());

پارامترها

نام نوع توضیحات
added Content String محتوایی که باید اضافه شود.

بازگشت

HtmlOutput — این خروجی، برای زنجیره‌سازی.

پرتاب‌ها

Error - اگر HTML ناقص باشد

همچنین ببینید

appendUntrusted(addedContent)

با استفاده از escape کردن زمینه، محتوای جدیدی را به محتوای این HtmlOutput اضافه می‌کند.

این متد به درستی محتوا را بر اساس وضعیت فعلی HtmlOutput می‌پوشاند، به طوری که نتیجه یک رشته امن بدون هیچ نشانه‌گذاری یا عوارض جانبی است. هر زمان که محتوا را از یک منبع غیرقابل اعتماد، مانند یک کاربر، اضافه می‌کنید، از این به جای استفاده از append استفاده کنید تا از بروز خطای اسکریپت‌نویسی بین سایتی (XSS) که در آن محتوا یا نشانه‌گذاری که اضافه می‌کنید باعث اجرای کد غیرمنتظره می‌شود، جلوگیری شود.

// Log &<q>uot;bHello, w<or>&ld!/&blt;pgt;Hello again, w&orld.&lt;/pgt;"
const output = HtmlService.createHt<m>lOutput('<bH>ello, world!/b');
output<.>appendUntrusted(<9;>pHello again, world./p');
Logger.log(output.getContent());

پارامترها

نام نوع توضیحات
added Content String محتوایی که باید اضافه شود.

بازگشت

HtmlOutput — این خروجی، برای زنجیره‌سازی.

پرتاب‌ها

Error - اگر HTML بسیار ناقص باشد

همچنین ببینید

asTemplate()

یک HtmlTemplate که توسط این HtmlOutput پشتیبانی می‌شود، برمی‌گرداند. این متد می‌تواند برای ساخت تدریجی یک قالب استفاده شود. تغییرات آینده در HtmlOutput بر محتوای HtmlTemplate نیز تأثیر می‌گذارد.

const output = HtmlService.createHtmlOutput(&<#>39;bHello, wo<rl>d!/b');
const template = output.asTemplate();

بازگشت

HtmlTemplate - HtmlTemplate جدید.

clear()

محتوای فعلی را پاک می‌کند.

const output = HtmlService.createHtmlOutput(&<#>39;bHello, wo<rl>d!/b');
output.clear();

بازگشت

HtmlOutput — این خروجی، برای زنجیره‌سازی.

getAs(contentType)

داده‌های درون این شیء را به صورت یک blob تبدیل‌شده به نوع محتوای مشخص‌شده برمی‌گرداند. این متد پسوند مناسب را به نام فایل اضافه می‌کند - برای مثال، "myfile.pdf". با این حال، فرض می‌کند که بخشی از نام فایل که پس از آخرین نقطه (در صورت وجود) می‌آید، یک پسوند موجود است که باید جایگزین شود. در نتیجه، "ShoppingList.12.25.2014" به "ShoppingList.12.25.pdf" تبدیل می‌شود.

برای مشاهده سهمیه‌های روزانه برای تبدیل‌ها، به سهمیه‌های سرویس‌های گوگل مراجعه کنید. دامنه‌های جدید Google Workspace ممکن است موقتاً مشمول سهمیه‌های سختگیرانه‌تری باشند.

پارامترها

نام نوع توضیحات
content Type String نوع MIME برای تبدیل. برای اکثر blobها، 'application/pdf' تنها گزینه معتبر است. برای تصاویر با فرمت BMP، GIF، JPEG یا PNG، هر یک از 'image/bmp' ، 'image/gif' ، 'image/jpeg' یا 'image/png' نیز معتبر هستند. برای یک سند Google Docs، 'text/markdown' نیز معتبر است.

بازگشت

Blob - داده‌ها به عنوان یک حباب.

getBlob()

داده‌های درون این شیء را به صورت یک blob برمی‌گرداند.

بازگشت

Blob - داده‌ها به عنوان یک حباب.

getContent()

محتوای این HtmlOutput را دریافت می‌کند.

// Log &<q>uot;bHello, w<or>ld!/b"
const output = HtmlService.createHt<m>lOutput('<bH>ello, world!/b');
Logger.log(output.getContent());

بازگشت

String - محتوایی که ارائه می‌شود.

getFaviconUrl()

با فراخوانی تابع setFaviconUrl(iconUrl) آدرس اینترنتی (URL) مربوط به تگ لینک favicon که به صفحه اضافه شده است را دریافت می‌کند. تگ‌های لینک Favicon که مستقیماً در یک فایل HTML اسکریپت برنامه‌ها (Apps Script) قرار می‌گیرند، نادیده گرفته می‌شوند.

const output = HtmlService.createHtmlOutput(&<#>39;bHello, wo<rl>d!/b');
output.setFaviconUrl('http://www.example.com/image.png');
Logger.log(output.getFaviconUrl());

بازگشت

String - آدرس اینترنتی تصویر فاوآیکون.

getHeight()

ارتفاع اولیه کادر محاوره‌ای سفارشی را در Google Docs، Sheets یا Forms دریافت می‌کند. اگر HtmlOutput به عنوان یک برنامه وب منتشر شده باشد، این متد null را برمی‌گرداند. برای تغییر اندازه کادر محاوره‌ای که از قبل باز است، google.script.host.setHeight(height) را در کد سمت کلاینت فراخوانی کنید. 

const output = HtmlService.createHtmlOutput(&<#>39;bHello, wo<rl>d!/b');
output.setHeight(200);
Logger.log(output.getHeight());

بازگشت

Integer - ارتفاع، بر حسب پیکسل.

getMetaTags()

با فراخوانی تابع addMetaTag(name, content) آرایه‌ای از اشیاء را دریافت می‌کند که نشان‌دهنده‌ی متا تگ‌های اضافه شده به صفحه هستند. متا تگ‌هایی که مستقیماً در یک فایل HTML اسکریپت برنامه‌ها قرار می‌گیرند، نادیده گرفته می‌شوند. 

const output = HtmlService.createHtmlOutput(&<#>39;bHello, wo<rl>d!/b');
output.addMetaTag('viewport', 'width=device-width, initial-scale=1');

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

بازگشت

HtmlOutputMetaTag[] — آرایه‌ای از اشیاء که متا تگ‌های اضافه شده به صفحه را با فراخوانی addMetaTag(name, content) نشان می‌دهند.

getTitle()

عنوان صفحه خروجی را برمی‌گرداند. توجه داشته باشید که عنصر <title> در HTML نادیده گرفته می‌شود. 

const output = HtmlService.createHtmlOutput(&<#>39;bHello, wo<rl>d!/b');
Logger.log(output.getTitle());

بازگشت

String - عنوان صفحه.

getWidth()

عرض اولیه کادر محاوره‌ای سفارشی را در Google Docs، Sheets یا Forms دریافت می‌کند. اگر HtmlOutput به عنوان یک برنامه وب منتشر شده باشد، این متد null را برمی‌گرداند. برای تغییر اندازه کادر محاوره‌ای که از قبل باز است، google.script.host.setWidth(width) را در کد سمت کلاینت فراخوانی کنید. 

const output = HtmlService.createHtmlOutput(&<#>39;bHello, wo<rl>d!/b');
output.setWidth(200);
Logger.log(output.getWidth());

بازگشت

Integer - عرض بر حسب پیکسل.

setContent(content)

محتوای این HtmlOutput را تنظیم می‌کند. 

const output = HtmlService.createHtmlOutput();
output.setContent(&<#>39;bHello, wo<rl>d!/b');

پارامترها

نام نوع توضیحات
content String محتوایی که قرار است ارائه شود.

بازگشت

HtmlOutput — این خروجی، برای زنجیره‌سازی.

پرتاب‌ها

Error - اگر HTML ناقص باشد

setFaviconUrl(iconUrl)

یک تگ لینک برای فاوآیکون به صفحه اضافه می‌کند. تگ‌های لینک فاوآیکون که مستقیماً در فایل HTML اسکریپت برنامه‌ها قرار می‌گیرند، نادیده گرفته می‌شوند. 

const output = HtmlService.createHtmlOutput(&<#>39;bHello, wo<rl>d!/b');
output.setFaviconUrl('http://www.example.com/image.png');

پارامترها

نام نوع توضیحات
icon Url String آدرس اینترنتی تصویر فاوآیکون، به همراه پسوند تصویر که نوع تصویر را نشان می‌دهد.

بازگشت

HtmlOutput — این خروجی، برای زنجیره‌سازی.

setHeight(height)

ارتفاع اولیه کادر محاوره‌ای سفارشی را در Google Docs، Sheets یا Forms تنظیم می‌کند. اگر HtmlOutput به عنوان یک برنامه وب منتشر شده باشد، این متد هیچ تاثیری ندارد. برای تغییر اندازه کادر محاوره‌ای که از قبل باز است، google.script.host.setHeight(height) را در کد سمت کلاینت فراخوانی کنید. 

const output = HtmlService.createHtmlOutput(&<#>39;bHello, wo<rl>d!/b');
output.setHeight(200);

پارامترها

نام نوع توضیحات
height Integer ارتفاع جدید بر حسب پیکسل؛ null منجر به مقدار پیش‌فرض می‌شود.

بازگشت

HtmlOutput — این خروجی، برای زنجیره‌سازی.

setSandboxMode(mode)

این روش اکنون هیچ تاثیری ندارد - قبلاً sandbox mode برای اسکریپت‌های سمت کلاینت تنظیم می‌کرد. برای محافظت از کاربران در برابر دریافت HTML یا جاوا اسکریپت مخرب، کد سمت کلاینت که از سرویس HTML ارائه می‌شود، در یک sandbox امنیتی اجرا می‌شود که محدودیت‌هایی را بر روی کد اعمال می‌کند. در ابتدا این روش به نویسندگان اسکریپت اجازه می‌داد تا بین نسخه‌های مختلف sandbox یکی را انتخاب کنند، اما اکنون همه اسکریپت‌ها صرف نظر از حالت sandbox تنظیم شده، از حالت IFRAME استفاده می‌کنند. برای اطلاعات بیشتر، به راهنمای محدودیت‌ها در سرویس HTML مراجعه کنید.

حالت IFRAME محدودیت‌های بسیار کمتری نسبت به سایر حالت‌های sandbox اعمال می‌کند و سریع‌تر اجرا می‌شود، اما در برخی مرورگرهای قدیمی‌تر، از جمله Internet Explorer 9، به هیچ وجه کار نمی‌کند. حالت sandbox را می‌توان با بررسی google.script.sandbox.mode در یک اسکریپت سمت کلاینت خواند. توجه داشته باشید که این ویژگی حالت واقعی را در کلاینت برمی‌گرداند، که اگر حالت درخواستی در مرورگر کاربر پشتیبانی نشود، ممکن است با حالت درخواستی در سرور متفاوت باشد. 

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

پارامترها

نام نوع توضیحات
mode Sandbox Mode حالت سندباکس برای استفاده.

بازگشت

HtmlOutput — این خروجی، برای زنجیره‌سازی.

setTitle(title)

عنوان صفحه خروجی را تنظیم می‌کند. برای برنامه‌های وب، این عنوان کل صفحه است، در حالی که برای HtmlOutput نشان داده شده در Google Sheets، این عنوان کادر محاوره‌ای است. 

const output = HtmlService.createHtmlOutput(&<#>39;bHello, wo<rl>d!/b');
output.setTitle('My First Page');

پارامترها

نام نوع توضیحات
title String عنوان جدید.

بازگشت

HtmlOutput — این خروجی، برای زنجیره‌سازی.

setWidth(width)

عرض اولیه یک کادر محاوره‌ای سفارشی را در Google Docs، Sheets یا Forms تنظیم می‌کند. اگر HtmlOutput به عنوان یک برنامه وب منتشر شده باشد، این متد هیچ تاثیری ندارد. برای تغییر اندازه کادر محاوره‌ای که از قبل باز است، google.script.host.setWidth(width) را در کد سمت کلاینت فراخوانی کنید. 

const output = HtmlService.createHtmlOutput(&<#>39;bHello, wo<rl>d!/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(&<#>39;bHello, wo<rl>d!/b');
output.setXFrameOptionsMode(HtmlService.XFrameOptionsMode.ALLOWALL);

پارامترها

نام نوع توضیحات
mode XFrameOptionsMode حالت گزینه‌های XFrame برای تنظیم.

بازگشت

HtmlOutput — این خروجی، برای زنجیره‌سازی.