Class HtmlOutput

HtmlOutput

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

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

שיטות

שיטהסוג הערך שמוחזרתיאור קצר
addMetaTag(name, content)HtmlOutputהוספת מטא תג לדף.
append(addedContent)HtmlOutputצירוף תוכן חדש לתוכן של HtmlOutput.
appendUntrusted(addedContent)HtmlOutputמצרף תוכן חדש לתוכן של HtmlOutput זה, באמצעות escape לפי הקשר.
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 בדף, ששולטת במניעת חטיפת קליקים.

תיעוד מפורט

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="..."/>
var output = HtmlService.createHtmlOutput('<b>Hello, world!</b>');
output.addMetaTag('viewport', 'width=device-width, initial-scale=1');

פרמטרים

שםתיאורהתיאור
nameStringהערך של מאפיין השם של המטא תג.
contentStringהערך של מאפיין התוכן של המטא תג.

החזרות

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

append(addedContent)

צירוף תוכן חדש לתוכן של HtmlOutput. השתמשו באפשרות הזו רק עבור תוכן ממקור מהימן, כי לא מתבצעת בו escape. 

// Log "<b>Hello, world!</b><p>Hello again, world.</p>"
var 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 זה, באמצעות escape לפי הקשר.

השיטה הזו מסמנים כראוי תוכן בהתאם למצב הנוכחי של HtmlOutput, כך שהתוצאה היא מחרוזת בטוחה ללא תגי עיצוב או שינויים צדדיים. כדאי להשתמש באפשרות הזו במקום להשתמש בהוספה בכל פעם שאתם מוסיפים תוכן ממקור לא מהימן, למשל תוכן ממשתמש, כדי למנוע בטעות הבאג של סקריפטים חוצי-אתרים (XSS) שבו תוכן או תגי עיצוב שאתם מוסיפים גורמים לביצוע קוד באופן בלתי צפוי. 

// Log "<b>Hello, world!</b>&lt;p&gt;Hello again, world.&lt;/p&gt;"
var 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. 

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

החזרות

HtmlTemplate – HtmlTemplate החדש.

clear()

ניקוי התוכן הנוכחי. 

var 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'.

החזרות

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

getBlob()

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

החזרות

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

getContent()

הפונקציה מקבלת את התוכן של HtmlOutput. 

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

החזרות

String - התוכן שמוצג.

getFaviconUrl()

הפונקציה מקבלת את כתובת ה-URL של תג קישור של סמל אתר שנוסף לדף באמצעות קריאה ל-setFaviconUrl(iconUrl). המערכת תתעלם מתגי קישור של סמל אתר שנכללים ישירות בקובץ HTML של Apps Script. 

var 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) בקוד בצד הלקוח. 

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

החזרות

Integer – הגובה, בפיקסלים.

getMetaTags()

הפונקציה מקבלת מערך של אובייקטים שמייצגים מטא תגים שנוספו לדף על ידי קריאה ל-addMetaTag(name, content). המערכת תתעלם ממטא תגים שכלולים ישירות בקובץ HTML של Apps Script. 

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

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

החזרות

HtmlOutputMetaTag[] - מערך אובייקטים שמייצגים מטא תגים שנוספו לדף על ידי קריאה ל-addMetaTag(name, content).

getTitle()

הפונקציה מקבלת את הכותרת של דף הפלט. לתשומת ליבכם: המערכת מתעלמת מהרכיב <title> של ה-HTML. 

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

החזרות

String - כותרת הדף.

getWidth()

הפונקציה מקבלת את הרוחב ההתחלתי של תיבת הדו-שיח המותאמת אישית ב-Google Docs, Sheets או Forms. אם השדה HtmlOutput מתפרסם כאפליקציית אינטרנט, השיטה הזו מחזירה את הערך null. כדי לשנות את הגודל של תיבת דו-שיח שכבר פתוחה, צריך לבצע קריאה ל- google.script.host.setWidth(width) בקוד בצד הלקוח. 

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

החזרות

Integer – הרוחב בפיקסלים.

setContent(content)

מגדיר את התוכן של HtmlOutput. 

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

פרמטרים

שםתיאורהתיאור
contentStringהתוכן להצגה.

החזרות

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

קליעות

Error - אם פורמט ה-HTML שגוי

setFaviconUrl(iconUrl)

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

var 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) בקוד בצד הלקוח. 

var 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. ניתן לקרוא את מצב ה-Sandbox בסקריפט בצד הלקוח על ידי בדיקת 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 זו הכותרת של תיבת הדו-שיח. 

var 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) בקוד בצד הלקוח. 

var 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).
var output = HtmlService.createHtmlOutput('<b>Hello, world!</b>');
output.setXFrameOptionsMode(HtmlService.XFrameOptionsMode.ALLOWALL);

פרמטרים

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

החזרות

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