Class HtmlOutput

HtmlOutput

אובייקט HtmlOutput שאפשר להציג מסקריפט. מטעמי אבטחה, סקריפטים לא יכולים להחזיר HTML ישירות לדפדפן. במקום זאת, הם צריכים לנקות אותו כדי שלא יוכל לבצע פעולות זדוניות. אפשר להחזיר HTML שעבר ניקוי באופן הבא: 

function doGet() {
  return HtmlService.createHtmlOutput('<b>Hello, world!</b>');
}
 הקוד ב-HtmlOutput יכול לכלול JavaScript ו-CSS מוטמעים. (זוהי קוד JavaScript רגיל בצד הלקוח שמפעיל שינויים ב-DOM, ולא Apps Script). כל התוכן הזה מועבר לארגז חול באמצעות ארגז חול של iframe. מידע נוסף זמין במדריך בנושא הגבלות בשירות HTML.

Methods

שיטהסוג הערך המוחזרתיאור קצר
addMetaTag(name, content)HtmlOutputהוספת מטא תג לדף.
append(addedContent)HtmlOutputהוספת תוכן חדש לתוכן של HtmlOutput הזה.
appendUntrusted(addedContent)HtmlOutputהוספת תוכן חדש לתוכן של HtmlOutput הזה, באמצעות בריחה לפי הקשר.
asTemplate()HtmlTemplateהפונקציה מחזירה HtmlTemplate שמגובים על ידי HtmlOutput הזה.
clear()HtmlOutputניקוי התוכן הנוכחי.
getAs(contentType)Blobהחזרת הנתונים שבתוך האובייקט הזה כ-blob שהומר לסוג התוכן שצוין.
getBlob()Blobהחזרת הנתונים שבתוך האובייקט הזה כ-blob.
getContent()Stringהפונקציה מקבלת את התוכן של ה-HtmlOutput הזה.
getFaviconUrl()Stringהפונקציה מקבלת את כתובת ה-URL של תג קישור לסמל אתר שנוסף לדף באמצעות קריאה ל-setFaviconUrl(iconUrl).
getHeight()Integerהפונקציה מקבלת את הגובה הראשוני של תיבת הדו-שיח בהתאמה אישית ב-Google Docs,‏ Sheets או Forms.
getMetaTags()HtmlOutputMetaTag[]הפונקציה מקבלת מערך של אובייקטים שמייצגים מטא תגים שנוספו לדף באמצעות קריאה ל-addMetaTag(name, content).
getTitle()Stringהפונקציה מקבלת את הכותרת של דף הפלט.
getWidth()Integerהפונקציה מקבלת את הרוחב הראשוני של תיבת הדו-שיח בהתאמה אישית ב-Google Docs,‏ Sheets או Forms.
setContent(content)HtmlOutputהגדרת התוכן של HtmlOutput הזה.
setFaviconUrl(iconUrl)HtmlOutputהוספת תג קישור של סמל דף לדף.
setHeight(height)HtmlOutputהגדרת הגובה הראשוני של תיבת הדו-שיח בהתאמה אישית ב-Google Docs,‏ Sheets או Forms.
setSandboxMode(mode)HtmlOutputהשיטה הזו לא משפיעה עכשיו – בעבר היא הגדירה את sandbox mode ששימש לסקריפטים מצד הלקוח.
setTitle(title)HtmlOutputהגדרת הכותרת של דף הפלט.
setWidth(width)HtmlOutputהגדרת הרוחב הראשוני של תיבת דו-שיח מותאמת אישית ב-Google Docs,‏ Sheets או Forms.
setXFrameOptionsMode(mode)HtmlOutputמגדיר את המצב של הכותרת X-Frame-Options בדף, שמאפשרת לשלוט במניעת clickjacking.

מסמכים מפורטים

addMetaTag(name, content)

הוספת מטא תג לדף. מטא תגים שכלולים ישירות בקובץ HTML של Apps Script מתעלמים. מותר להשתמש רק במטא תגים מהסוגים הבאים: 

<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 במקום ב-append בכל פעם שמוסיפים תוכן ממקור לא מהימן, כמו משתמש, כדי למנוע מקרה שבו יתרחש בטעות באג של פרצת אבטחה XSS (cross-site scripting), שבו תוכן או סימון שמוסיפים גורמים להרצת קוד בלתי צפויה. 

// 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)

החזרת הנתונים שבתוך האובייקט הזה כ-blob שהומר לסוג התוכן שצוין. השיטה הזו מוסיפה את הסיומת המתאימה לשם הקובץ – לדוגמה, 'myfile.pdf'. עם זאת, ההנחה היא שחלק משם הקובץ שמופיע אחרי הנקודה האחרונה (אם יש כזו) הוא סיומת קיימת שצריך להחליף. כתוצאה מכך, הקובץ ShoppingList.12.25.2014 הופך לקובץ ShoppingList.12.25.pdf.

כדי לראות את המכסות היומיות להמרות, אפשר לעיין במאמר מכסות לשירותי Google. יכול להיות שדומיינים חדשים של Google Workspace יהיו כפופים באופן זמני למכסות מחמירות יותר.

פרמטרים

שםסוגתיאור
contentTypeStringסוג ה-MIME שאליו רוצים להמיר. ברוב ה-blobs, 'application/pdf' היא האפשרות היחידה התקפה. בתמונות בפורמט BMP,‏ GIF,‏ JPEG או PNG, אפשר להשתמש גם ב-'image/bmp',‏ 'image/gif',‏ 'image/jpeg' או 'image/png'. במסמך ב-Google Docs, גם הערך 'text/markdown' תקף.

חזרה

Blob – הנתונים כ-blob.

getBlob()

החזרת הנתונים שבתוך האובייקט הזה כ-blob.

חזרה

Blob – הנתונים כ-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 Docs,‏ Sheets או Forms. אם 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 של Apps Script מתעלמים. 

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 Docs,‏ Sheets או Forms. אם 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 של סקריפט של אפליקציה. 

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

פרמטרים

שםסוגתיאור
iconUrlStringכתובת ה-URL של תמונת הסמל של האתר, עם סיומת התמונה שמציינת את סוג התמונה.

חזרה

HtmlOutput – הפלט הזה, לצורך שרשור.

setHeight(height)

הגדרת הגובה הראשוני של תיבת הדו-שיח בהתאמה אישית ב-Google Docs,‏ Sheets או Forms. אם ה-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 יש הרבה פחות הגבלות מאשר במצבי Sandbox אחרים, והוא פועל במהירות הגבוהה ביותר, אבל הוא לא פועל בכלל בדפדפנים ישנים מסוימים, כולל 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 Sheets, זהו שם תיבת הדו-שיח. 

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

פרמטרים

שםסוגתיאור
titleStringהשם החדש.

חזרה

HtmlOutput – הפלט הזה, לצורך שרשור.

setWidth(width)

הגדרת הרוחב הראשוני של תיבת דו-שיח מותאמת אישית ב-Google Docs,‏ Sheets או Forms. אם ה-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 בדף, שמאפשרת לשלוט במניעת clickjacking.

ההגדרה XFrameOptionsMode.ALLOWALL מאפשרת לכל אתר להציג את הדף ב-iframe, ולכן המפתח צריך להטמיע הגנה משלו מפני clickjacking.

אם לא מגדירים במסגרת סקריפט מצב 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 – הפלט הזה, לצורך שרשור.