במאמר הזה מוסבר איך להגדיר תבניות חדשות של פורמטים לתאריכים ולמספרים, שאפשר לכלול בבקשת ה-API.
הפורמטים של תאריך, שעה ומספרים מאפשרים לקבוע איך הנתונים שלכם יופיעו בגיליון. ב-Google Sheets יש כמה פורמטים נפוצים לבחירה, אבל אתם יכולים גם להגדיר פורמטים משלכם.
בממשק המשתמש של Sheets, אפשר להחיל פורמטים של מספרים ותאריכים על תאים באמצעות התפריט עיצוב > מספר. ב-Google Sheets API, מגדירים את הפורמטים האלה באמצעות הפעלת method של spreadsheets.batchUpdate כדי לשלוח UpdateCellsRequest או RepeatCellRequest.
בבקשה, מגדירים את האובייקט NumberFormat על ידי ציון NumberFormatType (כמו NUMBER, CURRENCY, PERCENT, DATE או TIME) ומחרוזת pattern אופציונלית. אם משמיטים את pattern, המערכת של Sheets משתמשת בתבנית ברירת המחדל של הפורמט לערך type שצוין, על סמך locale של הגיליון האלקטרוני (לדוגמה, $1,000.12 לערך CURRENCY ב-en_US).
בדוגמה הזו אפשר לראות איך מגדירים תבנית של פורמט באמצעות Sheets API. חשוב לדעת שהעיבוד בפועל של הפורמט תלוי ב-locale של הגיליון האלקטרוני.
במסמך הזה אנחנו מניחים שהערך של locale הוא en_US. כדי לזהות את ה-locale של גיליון אלקטרוני, קוראים את האובייקט SpreadsheetProperties באמצעות ה-method spreadsheets.get במשאב spreadsheets.
לדוגמאות נוספות, ראו עיצוב בסיסי ועיצוב מותנה.
מידע על ערכי תאריך ושעה
ב-Sheets, כמו ברוב האפליקציות האחרות של גיליונות אלקטרוניים, ערכי תאריך ושעה נחשבים לערכים עשרוניים. כך אפשר לבצע עליהם פעולות אריתמטיות בנוסחאות, למשל להוסיף ימים או שבועות, להוסיף או להחסיר שני תאריכים ושעות ולבצע פעולות דומות אחרות.
ב-Sheets נעשה שימוש בפורמט של תאריך התחלה שנפוץ בגיליונות אלקטרוניים. החלק של המספר השלם בערך (משמאל לנקודה העשרונית) סופר את הימים מ-30 בדצמבר 1899. החלק השברי (מימין לנקודה העשרונית) סופר את הזמן כשבר של יום אחד. לדוגמה, 1 בינואר 1900 בצהריים הוא 2.5, 2 כי זה יומיים אחרי 30 בדצמבר 1899, ו-0.5 כי הצהריים הם חצי יום. 1 בפברואר 1900 בשעה 15:00 הוא 33.625.
ב-Sheets, השנה 1900 נחשבת לשנה רגילה ולא לשנה מעוברת. המספרים הסידוריים של התאריך והשעה לא כוללים את ההפרש מאזור הזמן. במקום זאת, הם מבוססים על timeZone של הגיליון האלקטרוני, שאפשר לקרוא מהאובייקט SpreadsheetProperties באמצעות השיטה spreadsheets.get.
תבניות של פורמטים לתאריך ולשעה
תבנית עיצוב של תאריך ושעה היא מחרוזת של מחרוזות משנה של אסימונים, ש-Sheets מחליף ברכיבי התאריך והשעה המתאימים (כמו החודש או השעה) כשהוא מנתח אותם.
אסימונים של פורמט תאריך ושעה
בטבלה הבאה מוגדרות מחרוזות המשנה של הטוקנים שאפשר להשתמש בהן בתבנית של פורמט תאריך ושעה. התו + מציין שהתו הקודם יכול להופיע פעם אחת או יותר ועדיין להתאים לתבנית. תווים שלא מופיעים בטבלה הזו נחשבים ב-Sheets לתווים מילוליים, והם מוצגים ללא שינויים.
| אסימון | תיאור |
|---|---|
h |
השעה ביום. מעבר בין פורמט של 12 שעות לפורמט של 24 שעות, בהתאם לנוכחות של אינדיקטור AM או PM במחרוזת. |
hh+ |
זהה לאפשרות הקודמת, אבל עם 0 בהתחלה למספרים 1-9. |
m |
אם האסימון הקודם שאינו מילולי היה שעות או שהאסימון הבא הוא שניות, הוא מייצג דקות בשעה (ללא 0 בתחילת המספר). אחרת, הוא מייצג את החודש בשנה כמספר (ללא 0 בהתחלה). |
M |
החודש בשנה בלי 0 בהתחלה. משתמשים בטוקן הזה כדי לציין במפורש חודש, במקום דקה, בתבנית. |
mm |
כמו m, אבל עם 0 בהתחלה בשני המקרים. |
MM |
החודש בשנה עם 0 בהתחלה. משתמשים בטוקן הזה כדי לציין במפורש חודש, במקום דקה, בתבנית. |
mmm |
קיצור של שם החודש בשלוש אותיות (לדוגמה, "Feb"). |
mmmm |
שם החודש המלא. גם mmmmmm+ תואם לזה. |
mmmmm |
האות הראשונה של החודש (לדוגמה, "J" ל-June). |
s |
השניות בדקה בלי 0 בהתחלה. |
ss |
השניות בדקה, עם 0 בהתחלה. |
[h+] |
מספר השעות שחלפו במשך זמן מסוים. מספר האותיות מציין את מספר הספרות המינימלי (מוסיף אפסים בתחילת המספר). |
[m+] |
מספר הדקות שחלפו במשך זמן מסוים. מספר האותיות מציין את מספר הספרות המינימלי (מוסיף אפסים בתחילת המספר). |
[s+] |
מספר השניות שחלפו במשך זמן מסוים. מספר האותיות מציין את מספר הספרות המינימלי (מוסיף אפסים בתחילת המספר). |
d |
היום בחודש, בלי אפס בהתחלה למספרים קטנים מ-10. |
dd |
היום בחודש, עם 0 בהתחלה למספרים קטנים מ-10. |
ddd |
יום בשבוע, קיצור של שלוש אותיות (לדוגמה, "Mon"). |
dddd+ |
היום בשבוע, שם מלא. |
y |
שנה בשתי ספרות. |
yy |
|
yyy |
שנה בפורמט 4 ספרות. |
yyyy+ |
|
a/p |
הצגת "a" לציון לפני הצהריים ו-"p" לציון אחרי הצהריים. השעות משתנות גם לפורמט של 12 שעות. אם האות של הטוקן היא אות רישית, גם הפלט יהיה אות רישית. |
am/pm |
כמו למעלה, אבל מוצג "AM" או "PM" במקום זאת, ותמיד באותיות רישיות. |
0 |
עשיריות השנייה. אפשר להגדיל את הדיוק לשתי ספרות באמצעות 00 או לשלוש ספרות (אלפיות השנייה) באמצעות 000. |
\ |
התו הבא נחשב לליטרל, ולא למשמעות המיוחדת שעשויה להיות לו. |
"text" |
הצגת הטקסט שבתוך המירכאות כליטרל. |
דוגמאות לפורמטים של תאריך ושעה
בהתאם לתאריך ולשעה Tuesday, April 5, 2016, 4:08:53.528 PM, בטבלה הבאה מוצגות כמה תבניות לדוגמה והתאריך והשעה המקבילים להן. בחלק השני של הטבלה מוצגות דוגמאות לפורמטים של זמן שחלף, עבור זמן שחלף של 3 hours, 13 minutes, 41.255 seconds:
| תבניות של תאריך ושעה | Tuesday, April 5, 2016, 4:08:53.528 PM |
|---|---|
h:mm:ss.00 a/p |
4:08:53.53 p |
hh:mm A/P".M." |
04:08 |
yyyy-mm-dd |
2016-04-05 |
mmmm d \[dddd\] |
5 באפריל [יום שלישי] |
h PM, ddd mmm dd |
16:00, יום שלישי, 5 באפריל |
dddd, m/d/yy at h:mm |
יום שלישי, 5.4.16 בשעה 16:08 |
| תבניות של זמן שחלף | 3 hours, 13 minutes, 41.255 seconds |
[hh] |
03 |
[mmmm] |
0193 |
[ss] |
11621 |
תבניות של פורמט מספרים
תבנית של פורמט מספר היא מחרוזת של תת-מחרוזות של אסימונים, שמוחלפות ב-Sheets בייצוגים המתאימים של המספרים כשהן מנותחות. תבנית של פורמט מספרים יכולה לכלול עד ארבעה חלקים, שמופרדים באמצעות נקודה-פסיק. החלקים האלה מגדירים את הפורמטים הנפרדים שמשמשים למספרים חיוביים, למספרים שליליים, לאפס ולטקסט (בסדר הזה):
[POSITIVE FORMAT];[NEGATIVE FORMAT];[ZERO FORMAT];[TEXT FORMAT]
לא חייבים לכלול את כל ארבעת החלקים בפורמט. אם כוללים רק קטע אחד, Sheets משתמש בפורמט הזה לכל הערכים. אם משתמשים בשני חלקים, הפורמט הראשון חל על אפס ועל מספרים חיוביים, והפורמט השני חל על מספרים שליליים. אם משתמשים בשלושה חלקים, מגדירים פורמטים נפרדים למספרים חיוביים, שליליים ואפס. לדוגמה:
[NUMBER FORMAT] [POSITIVE/ZERO FORMAT];[NEGATIVE FORMAT] [POSITIVE FORMAT];[NEGATIVE FORMAT];[ZERO FORMAT]
עם זאת, אם יש שני חלקים או יותר והחלק האחרון הוא בפורמט טקסט, Sheets מתייחס לחלק הזה כפורמט טקסט, והחלקים האחרים מתנהגים כאילו יש חלק אחד פחות. לכן, אם כוללים פורמט טקסט סופי, אפשר להגדיר פורמטים כמו:
[POSITIVE/ZERO FORMAT];[NEGATIVE FORMAT];[TEXT FORMAT] [NUMBER FORMAT];[TEXT FORMAT]
הניתוח של פורמט לקטעים מתרחש לפני ניתוח אחר, כך שאפשר לכלול פורמט של תאריך או שעה כאחד מהקטעים (אם כי זה לא מאוד שימושי).
טוקנים של פורמט מספרים
בטבלה הבאה מוגדרות מחרוזות המשנה של האסימונים שאפשר להשתמש בהן בקטע של פורמט כדי להגדיר איך לייצג את הערכים של אותו קטע.
| אסימון | תיאור |
|---|---|
0 |
מייצג ספרה במספר. אם הספרה היא 0 לא מובהק,
היא מוצגת כ-0. לדוגמה, פורמט המספר 00.0 מציג את המספר 3 בתור 03.0. |
# |
מייצג ספרה במספר. אם הספרה היא 0 לא מובהק,
היא לא מוצגת. לדוגמה, פורמט המספר ##0
מציג את המספר 12 בתור "12". |
? |
מייצג ספרה במספר. אם הספרה היא 0 לא מובהק,
היא מוצגת כרווח. האפשרות הזו משמשת לעיתים קרובות ליישור הנקודה העשרונית בעמודה כשמשתמשים בגופנים ברוחב קבוע. לדוגמה, פורמט המספר ???.??? מציג את המספר 12.4 כך: " 12.4 ". |
. |
הנקודה הראשונה מייצגת את הנקודה העשרונית במספר. הנקודות הבאות מוצגות כמחרוזות מילוליות. אם כוללים נקודה עשרונית בפורמט, היא תמיד מוצגת, גם במספרים שלמים. לדוגמה,
#0.# מציג את המספר 3 בתור "3.". |
% |
מופיע כערך מילולי, אבל גם גורם להכפלת המספרים הקיימים ב-100 לפני העיבוד, כדי שיהיה קל יותר לקרוא את האחוזים. לדוגמה, פורמט המספר #%
מציג את המספר 0.25 בתור "25%". |
, |
אם הוא מופיע בין שני תווים של ספרות (0, # או ?), הוא מציג את המספר כולו עם מפרידי קבוצות (קיבוץ לפי אלפים). אם הוא מופיע אחרי תווי הספרות, הוא משנה את קנה המידה של הספרות באלף לכל פסיק (לדוגמה, הפורמט #0.0,, מציג את המספר 12,200,000 בתור 12.2). |
E- |
המספר מוצג בפורמט מדעי, כשהעיצוב משמאל ל-E משמש לחלק שאינו מעריך, והעיצוב מימין ל-E משמש לחלק של המעריך. הפונקציה E+ מציגה את הסימן + למעריכים חיוביים. ב-E- מוצג סימן רק למעריכים שליליים. אם
משתמשים באותיות קטנות, גם הפלט e יהיה באותיות קטנות.
לדוגמה, פורמט המספר ##0.00#E+##
מציג את המספר 0.0000001 בתור "100.00E-9". |
E+ |
|
e- |
|
e+ |
|
/ |
אם הוא מופיע בין שתי קבוצות של ספרות (0, # או ?), הוא מתייחס לקבוצות הספרות האלה כפורמט של שבר. לדוגמה, פורמט המספר 0 #/# מציג את המספר 23.25 בתור 23 1/4. המכנה יכול להיות גם מספר שלם מילולי, ובמקרה כזה הוא אוכף את המספר השלם הזה כמכנה. פורמט המספר 0 #/8
מציג את המספר 23.25 בתור 23 2/8. אם המונה הוא 0, החלק של השבר לא מוצג. המספר 23.1 בפורמט המספרים 0 #/3 מוצג כ-23 (כי 0.1 מעוגל ל-0/3). הפונקציה / לא תואמת לפורמט מדעי או לפורמט עם נקודה עשרונית. |
* |
האפשרות הזו נכללת כדי לאפשר תאימות לפורמטים של מספרים ב-Microsoft Excel. Sheets מתעלם מהאסימון הזה. |
_ |
דילוג על התו הבא והצגת רווח. האסימון הזה משמש ליישור פורמטים של מספרים שבהם סוגריים מקיפים את הערך השלילי. |
\ |
התו הבא נחשב לליטרל, ולא למשמעות המיוחדת שעשויה להיות לו. לדוגמה, פורמט המספר \#0
מציג את המספר 10 בתור "#10". |
"text" |
הצגת הטקסט שבתוך המירכאות כליטרל. |
@ |
אם בתא יש קלט טקסט, הוא מוסיף את הטקסט הגולמי לתא. לא תואם לאף אחד מהתווים המיוחדים האחרים, ולא מוצג בערכים מספריים (שמוצגים בפורמט כללי). |
$ - + ( ) : space |
ב-Sheets, התווים האלה וסמלי מטבעות נפוצים (כמו $, €, £ ו-¥) נחשבים לליטרלים ומוצגים ללא שינוי. |
הוראות למטא
בנוסף, כל אחד מהקטעים של הפורמט יכול לכלול הוראות מטא אופציונליות, שמוקפות בתווים [], שמופיעות לפני הפורמט ומספקות הוראות נוספות:
| הוראות | תיאור |
|---|---|
[condition] |
מחליף את ההשוואה שמוגדרת כברירת מחדל (חיובי, שלילי או אפס) של הקטע בביטוי מותנה אחר. לדוגמה,
[<100]"Low";[>1000]"High";000 מציג את המילה
"Low" לערכים מתחת ל-100, "High" לערכים מעל 1,000, ומספר בן שלוש ספרות (עם אפסים מובילים) לכל מה שביניהם. אפשר להחיל תנאים רק על שני תת-הפורמטים הראשונים, ואם מספר תואם ליותר מאחד, Sheets משתמש בהתאמה הראשונה. אם יש פורמט שלישי, Sheets משתמש בו ל"כל השאר". אחרת, אם מספר לא תואם לאף אחד מהפורמטים, Sheets מציג את כל התווים "#" לרוחב התא. אם הוא קיים, הפורמט הרביעי תמיד משמש לטקסט. |
[Color] or [Color#] |
גורם לכל ערך שהפורמט המשני הזה מעבד להופיע בצבע הטקסט שצוין. הערכים החוקיים של Color הם Black, Blue, Cyan, Green, Magenta, Red, White או Yellow.
הערכים התקינים של "#" ב-Color# הם בין 1 ל-56. צבעים של פורמט מספרים מבטלים את הצבעים שהמשתמשים הזינו בתא, אבל לא מבטלים את הצבעים שהוגדרו על ידי עיצוב מותנה. פלטת הצבעים הזו מציגה רשימה של צבעים שמתאימים לכל מספר. הם מבוססים על המאפיין ColorIndex ב-Microsoft Excel. |
[$currency] |
מציגה את סמל המטבע או את קוד המטבע שצוין כמחרוזת (לדוגמה, [$€]#,##0.00 או [$CAD]#,##0.00). אם מוסיפים קוד לוקאל אופציונלי אחרי מקף (כמו [$CAD-1009]), המערכת מתעלמת מקוד הלוקאל ב-Sheets. |
דוגמאות לפורמטים של מספרים
בטבלה הבאה מוצגות כמה תבניות לדוגמה והמספר המעוצב המקביל להן:
| מספר | דוגמת קוד | ערך בפורמט פתוח |
|---|---|---|
| 12345.125 | ####.# |
12345.1 |
| 12.34 | 000.0000 |
012.3400 |
| 12 | #.0# |
12.0 |
| 5.125 | # ???/??? |
5 1/8 |
| 12000 | #,### |
12,000 |
| 1234.56 -1234.56 |
$#,##0.00;($#,##0.00) |
$1,234.56 ($1,234.56) |
| 1230000 | 0.0,,"M" |
1.2 מיליון |
| 1234500000 | 0.00e+00 |
1.23e+09 |
| 123114.15115 MyText |
###0.000;"TEXT: "_(@_) |
123114.151 טקסט: MyText |
| 1234 -1234 0 MyText |
[Blue]#,##0;[Red]#,##0;[Green]0.0;[Magenta]_(@_) |
1,234 1,234 0.0 MyText |
| 1005 32 527 |
[>1000]"HIGH";[Color43][<=200]"LOW";0000 |
גבוהה נמוכה 0527 |