פורמטים של תאריכים ומספרים

במסמך הזה מוסבר איך מגדירים דפוסים חדשים של פורמטים של תאריכים ומספרים, שאפשר לכלול בבקשת ה-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+`	אותו דבר כמו קודם, אבל עם אפס מוביל למספרים 1-9.
`m`	אם הטוקן הקודם שאינו מילולי היה שעות או שהטוקן הבא הוא שניות, הוא מייצג דקות בשעה (ללא 0 מוביל). אחרת, הוא מייצג את החודש בשנה כמספר (ללא 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
`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, התווים האלה נחשבים כתווים מילוליים ומוצגים ללא שינוי.

הוראות למטא

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

הוראות תיאור

[condition] מחליפה את השוואת ברירת המחדל של החלק עם ערך חיובי, שלילי או אפס בביטוי תנאי אחר. לדוגמה, הפונקציה [<100]"Low";[>1000]"High";000 תציג את המילה Low (נמוך) לערכים מתחת ל-100, את המילה High (גבוה) לערכים מעל 1,000, ומספר בן שלוש ספרות (עם אפסים מובילים) לכל ערך אחר. אפשר להחיל תנאים רק על שני פורמטי המשנה הראשונים, ואם מספר תואם ליותר מפורמט אחד, המערכת משתמשת בפורמט הראשון שהוא תואם לו. אם יש פורמט שלישי, הוא משמש לכל השאר. אחרת, אם מספר לא תואם לאף אחד מהפורמטים, הוא מוצג עם כל התווים '#' שנדרשים כדי למלא את רוחב התא. אם הוא קיים, הפורמט הרביעי משמש תמיד לטקסט.

[Color] or [Color#] גורם לכל ערך שמוצג בפורמט המשנה הזה להופיע עם צבע הטקסט שצוין. הערכים התקינים של Color הם שחור, כחול, ציאן, ירוק, מגנטה, אדום, לבן או צהוב. הערכים התקפים של '#' ב-Color# הם 1 עד 56. פורמט מספרים צבעים מבטל את הצבעים שהמשתמש הזין בתא, אבל לא מבטל צבעים שהוגדרו על ידי עיצוב מותנה. בפלטת הצבעים הזו מופיעה רשימה של צבעים שמתאימים לכל מספר. הם מבוססים על המאפיין ColorIndex ב-Microsoft Excel.

הוראות	תיאור
`[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.2M
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

סקירה כללית של דוגמאות