במאמר הזה מוסבר איך מגדירים דפוסי פורמט חדשים של תאריכים ומספרים, שאפשר לכלול בבקשת ה-API.
הפורמטים של תאריכים, שעות ומספרים מאפשרים לקבוע איך הנתונים יופיעו בגיליון. ב-Google Sheets יש כמה פורמטים נפוצים לבחירה, אבל אתם יכולים גם להגדיר פורמטים משלכם.
בממשק המשתמש של Sheets, אפשר להחיל על תאים פורמטים של מספרים ותאריכים באמצעות התפריט פורמט > מספר. ב-Google Sheets API, מגדירים את הפורמטים האלה באמצעות הפעלת method spreadsheets.batchUpdate כדי לשלוח UpdateCellsRequest או RepeatCellRequest.
בדוגמה Set a custom datetime or decimal format for a range (הגדרת תבנית מותאמת אישית של תאריך ושעה או של מספר עשרוני לטווח) מוסבר איך להגדיר תבנית באמצעות Sheets API. חשוב לזכור שהעיבוד בפועל של הפורמט תלוי בlocale של הגיליון האלקטרוני.
במסמך הזה אנחנו מניחים ש-locale הוא en_US. אפשר לקבוע את ה-locale של גיליון אלקטרוני על ידי קריאת האובייקט SpreadsheetProperties באמצעות ה-method spreadsheets.get במשאב spreadsheets.
דוגמאות נוספות זמינות במאמרים בנושא עיצוב בסיסי ועיצוב מותנה.
מידע על ערכי תאריך ושעה
ב-Sheets, כמו ברוב אפליקציות הגיליונות האלקטרוניים האחרות, ערכי התאריך והשעה נחשבים לערכים עשרוניים. כך אפשר לבצע פעולות אריתמטיות על התאים האלה בנוסחאות, כמו הוספה של ימים או שבועות, חיבור או חיסור של שני תאריכים ושעות ופעולות דומות אחרות.
ב-Sheets נעשה שימוש בפורמט של תאריך epoch שנפוץ בגיליונות אלקטרוניים. החלק של המספר השלם בערך (מימין לנקודה העשרונית) מייצג את מספר הימים מאז 30 בדצמבר 1899. החלק השברי (משמאל לנקודה העשרונית) מייצג את הזמן כשבר של יום אחד. לדוגמה, 1 בינואר 1900 בצהריים הוא 2.5, 2 כי זה יומיים אחרי 30 בדצמבר 1899, ו-0.5 כי צהריים הם חצי יום. 1 בפברואר 1900 בשעה 15:00 הוא 33.625.
ב-Sheets, שנת 1900 נחשבת לשנה רגילה ולא לשנה מעוברת.
דפוסי פורמט של תאריך ושעה
תבנית של פורמט תאריך ושעה היא מחרוזת של תת-מחרוזות של טוקנים, שכאשר מנתחים אותן, הן מוחלפות ברכיבים התואמים של התאריך והשעה (כמו החודש או השעה).
אסימונים של פורמט תאריך ושעה
בטבלה הבאה מוגדרים מחרוזות המשנה של הטוקנים שאפשר להשתמש בהם בתבנית של תאריך ושעה. התו + מציין שהתו הקודם יכול להופיע פעם אחת או יותר ועדיין להתאים לדפוס. תווים שלא מופיעים בטבלה הזו נחשבים לתווים מילוליים, והם מופיעים בפלט ללא שינויים.
| אסימון | תיאור |
|---|---|
h |
השעה ביום. הפונקציה עוברת בין פורמט של 12 שעות לפורמט של 24 שעות בהתאם לסימן AM או PM שמופיע במחרוזת. |
hh+ |
כמו הקודם, אבל עם 0 מוביל למספרים 1-9. |
m |
אם הטוקן הקודם שאינו מילולי היה שעות או שהטוקן הבא הוא שניות, הוא מייצג דקות בשעה (ללא 0 מוביל). אחרת, הוא מייצג את החודש בשנה כמספר (ללא אפס בהתחלה). |
M |
החודש בשנה בלי אפס מוביל. אפשר להשתמש בטוקן הזה כדי לציין במפורש חודש במקום דקה בתבנית. |
mm |
בדיוק כמו m, אבל עם 0 בהתחלה בשני המקרים. |
MM |
החודש בשנה עם אפס מוביל. אפשר להשתמש בטוקן הזה כדי לציין במפורש חודש במקום דקה בתבנית. |
mmm |
קיצור של חודש בן שלוש אותיות (לדוגמה, Feb). |
mmmm |
השם המלא של החודש. גם mmmmmm+ מתאים לזה. |
mmmmm |
האות הראשונה של החודש (לדוגמה, J ליוני). |
s |
מספר השניות בדקה בלי 0 מוביל. |
ss |
מספר השניות בדקה עם 0 מוביל. |
[h+] |
מספר השעות שחלפו במשך תקופת זמן. מספר האותיות מציין את המספר המינימלי של ספרות (מוסיף אפסים מובילים). |
[m+] |
מספר הדקות שחלפו במשך תקופת זמן. מספר האותיות מציין את המספר המינימלי של ספרות (מוסיף אפסים מובילים). |
[s+] |
מספר השניות שחלפו במשך תקופת זמן. מספר האותיות מציין את המספר המינימלי של ספרות (מוסיף אפסים מובילים). |
d |
היום בחודש, ללא אפס בהתחלה למספרים קטנים מ-10. |
dd |
היום בחודש, עם אפס בהתחלה למספרים קטנים מ-10. |
ddd |
יום בשבוע, קיצור בן שלוש אותיות (לדוגמה, 'ראשון'). |
dddd+ |
היום בשבוע, השם המלא. |
y |
שנה בשתי ספרות. |
yy |
|
yyy |
שנה בארבע ספרות. |
yyyy+ |
|
a/p |
מוצגות האותיות a לציון AM ו-p לציון PM. הוא גם משנה את השעות לפורמט של 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 P.M. |
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 באפריל 2016 בשעה 16:08 |
| דוגמאות של הזמן שחלף | 3 hours, 13 minutes, 41.255 seconds |
[hh] |
03 |
[mmmm] |
0193 |
[ss] |
11621 |
דפוסים של פורמט מספרים
תבנית של פורמט מספר היא מחרוזת של תת-מחרוזות של טוקנים, שאחרי הניתוח שלהן הן מוחלפות בייצוגים התואמים של המספרים. תבנית של פורמט מספרים יכולה לכלול עד ארבעה חלקים, שמופרדים באמצעות נקודה-פסיק, שמגדירים את הפורמטים הנפרדים שמשמשים למספרים חיוביים, למספרים שליליים, לאפס ולטקסט (בסדר הזה):
[POSITIVE FORMAT];[NEGATIVE FORMAT];[ZERO FORMAT];[TEXT FORMAT]
לא צריך לכלול את כל ארבעת החלקים בפורמט. אם כוללים רק חלק אחד, הפורמט הזה ישמש לכל הערכים. שימוש בשני חלקים גורם להחלת הפורמט הראשון על אפס ומספרים חיוביים, ולהחלת הפורמט השני על מספרים שליליים. שימוש בשלושה חלקים מגדיר פורמטים נפרדים למספרים חיוביים, למספרים שליליים ולאפס. לדוגמה:
[NUMBER FORMAT] [POSITIVE/ZERO FORMAT];[NEGATIVE FORMAT] [POSITIVE FORMAT];[NEGATIVE FORMAT];[ZERO FORMAT]
עם זאת, אם יש שני חלקים או יותר והחלק האחרון הוא בפורמט טקסט, המערכת מתייחסת לחלק הזה כאל פורמט טקסט, וההתנהגות של החלקים האחרים היא כאילו יש חלק אחד פחות. לכן, אם כוללים פורמט טקסט סופי, אפשר להגדיר פורמטים כמו:
[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. המערכת מתעלמת ממנו. |
_ |
האסימון של קו תחתון מדלג על התו הבא ומציג רווח. הפורמט הזה משמש ליישור של פורמטים של מספרים שבהם הערך השלילי מוקף בסוגריים. |
\ |
התו הבא יטופל כערך מילולי ולא כמשמעות מיוחדת שיכולה להיות לו. לדוגמה, תבנית המספרים \#0
תציג את המספר 10 כ-#10. |
"text" |
הצגת הטקסט שבתוך המירכאות כטקסט מילולי. |
@ |
אם התא מכיל קלט טקסט, הפונקציה מוסיפה את הטקסט הגולמי של התא. הוא לא תואם לאף אחד מהתווים המיוחדים האחרים, והוא לא מוצג עבור ערכים מספריים (שמוצגים כפורמט כללי). |
$ - + ( ) : space |
Sheets מתייחס לתווים האלה כאל ערכים מילוליים ומציג אותם ללא שינוי. |
הוראות ל-Meta
בנוסף, כל אחד מקטעי הפורמט יכול לכלול הוראות מטא אופציונליות, שמוקפות בתווים [], שמופיעות לפני הפורמט ומספקות הוראות נוספות. יש שני סוגים של הוראות מטא, ואפשר להשתמש בשניהם בקטע נתון:
| הוראות | תיאור |
|---|---|
[condition] |
מחליפה את השוואת ברירת המחדל של החלק (חיובי, שלילי או אפס) בביטוי תנאי אחר. לדוגמה,
הפונקציה [<100]"Low";[>1000]"High";000 תציג את המילה Low לערכים מתחת ל-100, את המילה High לערכים מעל 1,000, ומספר בן שלוש ספרות (עם אפסים מובילים) לכל ערך אחר. אפשר להחיל תנאים רק על שני פורמטי המשנה הראשונים, ואם מספר תואם ליותר מפורמט אחד, המערכת משתמשת בפורמט הראשון שהוא תואם לו. אם יש פורמט שלישי, הוא משמש לכל השאר. אם מספר לא תואם לאף אחד מהפורמטים, הוא מוצג עם כל סימני ה-# שנדרשים כדי למלא את רוחב התא. אם הוא קיים, הפורמט הרביעי משמש תמיד לטקסט. |
[Color] or [Color#] |
גורם לכל ערך שמוצג בתת-הפורמט הזה להופיע בצבע הטקסט שצוין. הערכים התקינים של Color הם שחור, כחול, ציאן, ירוק, מגנטה, אדום, לבן או צהוב.
הערכים התקינים של '#' בעמודה Color# הם 1 עד 56. פורמט מספרים
צבעים מבטלים את הצבעים שהמשתמש הזין בתא, אבל לא מבטלים
צבעים שהוגדרו על ידי עיצוב מותנה. בפלטת הצבעים הזו מופיעה רשימה של צבעים שמתאימים לכל מספר. הם מבוססים על המאפיין ColorIndex ב-Microsoft Excel. |
דוגמאות לפורמטים של מספרים
בטבלה הבאה מוצגות כמה תבניות לדוגמה והמספרים המעוצבים שתואמים להן:
| מספר | דוגמת קוד | ערך מפורמט |
|---|---|---|
| 12345.125 | ####.# |
12345.1 |
| 12.34 | 000.0000 |
012.3400 |
| 12 | #.0# |
12.0 |
| 5.125 | # ???/??? |
5 1/8 |
| 12000 | #,### |
12,000 |
| 1230000 | 0.0,,"M" |
1.2 מיליון |
| 1234500000 | 0.00e+00 |
1.23e+09 |
| 123114.15115 MyText |
###0.000;"TEXT: "_(@_) |
123114.151 TEXT: 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 |