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

פרמטרים

שם	סוג	תיאור
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 במקום ב-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());

פרמטרים

שם	סוג	תיאור
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)

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

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

פרמטרים

שם	סוג	תיאור
contentType	String	סוג ה-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>');

פרמטרים

שם	סוג	תיאור
content	String	התוכן שרוצים להציג.

חזרה

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

זריקות

Error – אם ה-HTML ערוך בצורה שגויה

---

setFaviconUrl(iconUrl)

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

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

פרמטרים

שם	סוג	תיאור
iconUrl	String	כתובת ה-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);

פרמטרים

שם	סוג	תיאור
height	Integer	הגובה החדש בפיקסלים. הערך 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>

פרמטרים

שם	סוג	תיאור
mode	SandboxMode	מצב ארגז החול שבו רוצים להשתמש.

חזרה

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

---

setTitle(title)

הגדרת הכותרת של דף הפלט. באפליקציות אינטרנט, זהו שם הדף כולו, ואילו ב-HtmlOutput שמוצג ב-Google Sheets, זהו שם תיבת הדו-שיח.

const output = HtmlService.createHtmlOutput('<b>Hello, world!</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('<b>Hello, world!</b>');
output.setWidth(200);

פרמטרים

שם	סוג	תיאור
width	Integer	הרוחב החדש בפיקסלים. הערך 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);

פרמטרים

שם	סוג	תיאור
mode	XFrameOptionsMode	מצב האפשרויות של XFrame שרוצים להגדיר.

חזרה

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