เอกสารนี้อธิบายวิธีกำหนดรูปแบบวันที่และตัวเลขใหม่ ซึ่งคุณสามารถรวมไว้ในคำขอ API ได้
รูปแบบวันที่-เวลาและตัวเลขช่วยให้คุณสามารถควบคุมวิธีที่ข้อมูลของคุณปรากฏในชีต Google ชีตมีรูปแบบทั่วไปให้เลือก แต่คุณกําหนดรูปแบบของคุณเองได้
ใน UI ของชีต คุณสามารถใช้รูปแบบตัวเลขและวันที่กับเซลล์ได้โดยใช้เมนูรูปแบบ > ตัวเลข ใน Google Sheets API คุณตั้งค่ารูปแบบเหล่านี้โดยใช้การเรียกใช้เมธอด spreadsheets.batchUpdate เพื่อส่ง UpdateCellsRequest หรือ RepeatCellRequest
ในคำขอ คุณจะกำหนดค่าออบเจ็กต์ NumberFormat โดยระบุ NumberFormatType (เช่น NUMBER, CURRENCY, PERCENT, DATE หรือ TIME) และสตริง pattern (ไม่บังคับ) หากคุณละเว้น pattern ชีตจะใช้รูปแบบการจัดรูปแบบเริ่มต้นสำหรับ type ที่ระบุตาม locale ของสเปรดชีต (เช่น $1,000.12 สำหรับ CURRENCY ใน en_US)
ตัวอย่างตั้งค่าวันที่และเวลาที่กำหนดเองหรือรูปแบบทศนิยมสำหรับช่วงจะแสดงวิธีตั้งค่ารูปแบบโดยใช้ Sheets API โปรดทราบว่าการแสดงผลจริงของรูปแบบจะขึ้นอยู่กับ locale ของสเปรดชีต
เอกสารนี้ถือว่า locale คือ en_US คุณสามารถกำหนด locale ของสเปรดชีตได้โดยการอ่านออบเจ็กต์ SpreadsheetProperties โดยใช้เมธอด spreadsheets.get ในทรัพยากร spreadsheets
ดูตัวอย่างเพิ่มเติมได้ที่การจัดรูปแบบพื้นฐานและการจัดรูปแบบตามเงื่อนไข
เกี่ยวกับค่าวันที่และเวลา
ชีตจะถือว่าค่าวันที่และเวลาเป็นค่าทศนิยม เช่นเดียวกับแอปพลิเคชันสเปรดชีตอื่นๆ ส่วนใหญ่ ซึ่งจะช่วยให้คุณดำเนินการทางคณิตศาสตร์กับวันที่และเวลาในสูตรได้ คุณจึงเพิ่มวันหรือสัปดาห์ บวกหรือลบวันที่และเวลา 2 รายการ และดำเนินการอื่นๆ ที่คล้ายกันได้
ชีตใช้รูปแบบวันที่เริ่มต้นที่ใช้กันโดยทั่วไปในสเปรดชีต ส่วนที่เป็นจำนวนเต็มของค่า (ทางซ้ายของทศนิยม) จะนับจำนวนวันตั้งแต่วันที่ 30 ธันวาคม 1899 ส่วนที่เป็นเศษส่วน (ทางขวาของทศนิยม) จะนับเวลาเป็นเศษส่วนของ 1 วัน เช่น วันที่ 1 มกราคม 1900 เวลาเที่ยงวันคือ 2.5, 2 เนื่องจากเป็นเวลา 2 วันหลังจากวันที่ 30 ธันวาคม 1899 และ 0.5 เนื่องจากเที่ยงวันคือครึ่งวัน วันที่ 1 กุมภาพันธ์ 1900 เวลา 15:00 น. คือ 33.625
ชีตจะถือว่าปี 1900 เป็นปีปกติ ไม่ใช่ปีอธิกสุรทิน หมายเลขซีเรียลของวันที่และเวลาไม่ได้จัดเก็บค่าชดเชยเขตเวลา แต่จะอิงตาม timeZone ของสเปรดชีต ซึ่งคุณสามารถอ่านได้จากออบเจ็กต์ SpreadsheetProperties โดยใช้เมธอด spreadsheets.get
รูปแบบของรูปแบบวันที่และเวลา
รูปแบบวันที่และเวลาคือสตริงของสตริงย่อยโทเค็นที่ชีตจะแทนที่ด้วยองค์ประกอบวันที่และเวลาที่เกี่ยวข้อง (เช่น เดือนหรือชั่วโมง) เมื่อแยกวิเคราะห์
โทเค็นรูปแบบวันที่และเวลา
ตารางต่อไปนี้จะกำหนดสตริงย่อยของโทเค็นที่คุณใช้ในรูปแบบวันที่และเวลาได้ อักขระ + บ่งชี้ว่าอักขระก่อนหน้าสามารถปรากฏอย่างน้อย 1 ครั้งและยังคงตรงกับรูปแบบ ชีตจะถือว่าอักขระที่ไม่ได้แสดงในตารางนี้เป็นค่าคงที่และแสดงผลโดยไม่มีการเปลี่ยนแปลง
| โทเค็น | คำอธิบาย |
|---|---|
h |
เวลาของวัน สลับระหว่างรูปแบบ 12 ชั่วโมงและ 24 ชั่วโมง โดยขึ้นอยู่กับว่ามีตัวบ่งชี้ AM หรือ PM อยู่ในสตริงหรือไม่ |
hh+ |
เหมือนกับก่อนหน้า แต่มี 0 นำหน้าสำหรับ 1-9 |
m |
หากโทเค็นที่ไม่ใช่ตัวอักษรก่อนหน้าเป็นชั่วโมงหรือโทเค็นถัดไปเป็นวินาที โทเค็นนี้จะแสดงนาทีในชั่วโมง (ไม่มี 0 นำหน้า) ไม่เช่นนั้นจะแสดงเดือนของปีเป็นตัวเลข (ไม่มี 0 นำหน้า) |
M |
เดือนของปีที่ไม่มี 0 นำหน้า ใช้โทเค็นนี้เพื่อระบุเดือนอย่างชัดเจนแทนนาทีในรูปแบบของคุณ |
mm |
เหมือนกับ m แต่มีเลข 0 นำหน้าสำหรับทั้ง 2 กรณี |
MM |
เดือนของปีที่มี 0 นำหน้า ใช้โทเค็นนี้เพื่อระบุเดือนอย่างชัดเจนแทนนาทีในรูปแบบของคุณ |
mmm |
ตัวย่อเดือน 3 ตัวอักษร (เช่น "Feb") |
mmmm |
ชื่อเดือนแบบเต็ม mmmmmm+ ก็ตรงกับกฎนี้เช่นกัน |
mmmmm |
ตัวอักษรแรกของเดือน (เช่น "ม" สำหรับมิถุนายน) |
s |
วินาทีในนาทีโดยไม่มี 0 นำหน้า |
ss |
วินาทีในนาทีโดยมีเลข 0 นำหน้า |
[h+] |
จำนวนชั่วโมงที่ผ่านไปในระยะเวลาหนึ่งๆ จำนวนตัวอักษรจะระบุจำนวนตัวเลขขั้นต่ำ (เพิ่ม 0 นำหน้า) |
[m+] |
จำนวนนาทีที่ผ่านไปในระยะเวลาหนึ่งๆ จำนวนตัวอักษรจะระบุจำนวนตัวเลขขั้นต่ำ (เพิ่ม 0 นำหน้า) |
[s+] |
จำนวนวินาทีที่ผ่านไปในระยะเวลาหนึ่งๆ จำนวนตัวอักษรจะระบุจำนวนตัวเลขขั้นต่ำ (เพิ่ม 0 นำหน้า) |
d |
วันที่ของเดือน โดยไม่มีเลข 0 นำหน้าสำหรับตัวเลขที่น้อยกว่า 10 |
dd |
วันที่ของเดือน โดยมีเลข 0 นำหน้าสำหรับตัวเลขที่น้อยกว่า 10 |
ddd |
วันในสัปดาห์ ตัวย่อ 3 ตัวอักษร (เช่น "Mon") |
dddd+ |
วันของสัปดาห์ ชื่อเต็ม |
y |
ปีแบบ 2 หลัก |
yy |
|
yyy |
ปีแบบ 4 หลัก |
yyyy+ |
|
a/p |
แสดง "a" สำหรับ AM และ "p" สำหรับ PM และเปลี่ยนชั่วโมงเป็นรูปแบบ 12 ชั่วโมงด้วย หากตัวอักษรโทเค็นเป็นตัวพิมพ์ใหญ่ เอาต์พุตก็จะเป็นตัวพิมพ์ใหญ่ด้วย |
am/pm |
เหมือนกับด้านบน แต่แสดง "AM" หรือ "PM" แทน และเป็นตัวพิมพ์ใหญ่เสมอ |
0 |
1 ใน 10 ของวินาที คุณสามารถเพิ่มความแม่นยำเป็น 2 หลักด้วย 00 หรือ 3 หลัก (มิลลิวินาที) ด้วย 000 |
\ |
ถือว่าอักขระถัดไปเป็นค่าลิเทอรัล ไม่ใช่ความหมายพิเศษที่อาจมี |
"text" |
แสดงข้อความที่อยู่ในเครื่องหมายคำพูดเป็นค่าตามตัวอักษร |
ตัวอย่างรูปแบบวันที่และเวลา
เมื่อระบุวันที่และเวลา Tuesday, April 5, 2016, 4:08:53.528 PM ตารางต่อไปนี้จะแสดงตัวอย่างรูปแบบและการแสดงผลวันที่และเวลาที่เกี่ยวข้อง ส่วนที่ 2 ของตารางแสดงตัวอย่างรูปแบบเวลาที่ผ่านไปสำหรับเวลาที่ผ่านไป 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." |
16: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 |
รูปแบบของรูปแบบตัวเลข
รูปแบบตัวเลขคือสตริงของสตริงย่อยโทเค็นที่ชีตจะแทนที่ด้วยการแสดงตัวเลขที่เกี่ยวข้องเมื่อแยกวิเคราะห์ รูปแบบตัวเลขประกอบด้วยส่วนต่างๆ ได้สูงสุด 4 ส่วน โดยคั่นด้วยเครื่องหมายเซมิโคลอน ซึ่งจะกำหนดรูปแบบที่แยกกันสำหรับตัวเลขบวก ตัวเลขลบ ศูนย์ และข้อความ (ตามลำดับ) ดังนี้
[POSITIVE FORMAT];[NEGATIVE FORMAT];[ZERO FORMAT];[TEXT FORMAT]
คุณไม่จำเป็นต้องใส่ทั้ง 4 ส่วนในรูปแบบเดียว หากคุณใส่เพียงส่วนเดียว ชีตจะใช้รูปแบบนั้นกับค่าทั้งหมด การใช้ 2 ส่วนจะใช้รูปแบบแรกกับเลขศูนย์และจำนวนบวก และใช้รูปแบบที่ 2 กับจำนวนลบ การใช้ 3 ส่วนจะกำหนดรูปแบบแยกกันสำหรับตัวเลขบวก ตัวเลขลบ และเลขศูนย์ เช่น
[NUMBER FORMAT] [POSITIVE/ZERO FORMAT];[NEGATIVE FORMAT] [POSITIVE FORMAT];[NEGATIVE FORMAT];[ZERO FORMAT]
อย่างไรก็ตาม หากมี 2 ส่วนขึ้นไปและส่วนสุดท้ายเป็นรูปแบบข้อความ ชีตจะถือว่าส่วนนั้นเป็นรูปแบบข้อความและส่วนอื่นๆ จะทำงานเหมือนกับว่ามีส่วนน้อยกว่า 1 ส่วน ดังนั้น การใส่รูปแบบข้อความสุดท้ายจะช่วยให้กำหนดรูปแบบต่างๆ ได้ เช่น
[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%" |
, |
หากปรากฏระหว่างอักขระ 2 หลัก (0, # หรือ ?) ระบบจะแสดงผลตัวเลขทั้งหมดพร้อมตัวคั่นการจัดกลุ่ม (จัดกลุ่มตามหลักพัน) หากอยู่หลังอักขระตัวเลข ระบบจะปรับขนาดตัวเลขเป็น 1,000 ต่อคอมมา 1 ตัว (เช่น รูปแบบ #0.0,, จะแสดงตัวเลข 12,200,000 เป็น 12.2) |
E- |
แสดงผลตัวเลขในรูปแบบทางวิทยาศาสตร์ โดยมีการจัดรูปแบบทางด้านซ้ายของ E ที่ใช้สำหรับส่วนที่ไม่ใช่เลขชี้กำลัง และการจัดรูปแบบทางด้านขวาของ E ที่ใช้สำหรับส่วนเลขชี้กำลัง E+ แสดงเครื่องหมาย + สำหรับเลขชี้กำลังที่เป็นบวก E- จะแสดงเครื่องหมายสำหรับเลขชี้กำลังที่เป็นลบเท่านั้น หากใช้ตัวพิมพ์เล็ก เอาต์พุต e จะเป็นตัวพิมพ์เล็กด้วย
เช่น รูปแบบตัวเลข ##0.00#E+## จะแสดงตัวเลข 0.0000001 เป็น "100.00E-9" |
E+ |
|
e- |
|
e+ |
|
/ |
หากปรากฏระหว่างอักขระตัวเลข 2 ตัว (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 |
ชีตจะถือว่าอักขระเหล่านี้และสัญลักษณ์สกุลเงินทั่วไป (เช่น $, €, £ และ ¥) เป็นค่าคงที่และแสดงโดยไม่มีการเปลี่ยนแปลง |
วิธีการสำหรับ Meta
นอกจากนี้ ส่วนรูปแบบแต่ละส่วนอาจมีคำสั่งเมตาที่ไม่บังคับ ซึ่งอยู่ในอักขระ [] ที่อยู่หน้าส่วนรูปแบบและให้คำสั่งเพิ่มเติม ดังนี้
| โรงเรียนฝึกอบรม | คำอธิบาย |
|---|---|
[condition] |
แทนที่การเปรียบเทียบค่าบวก ค่าลบ หรือค่าศูนย์เริ่มต้นของส่วนด้วยนิพจน์แบบมีเงื่อนไขอื่น เช่น [<100]"Low";[>1000]"High";000 จะแสดงผลคำว่า "ต่ำ" สำหรับค่าที่ต่ำกว่า 100, "สูง" สำหรับค่าที่สูงกว่า 1000 และตัวเลข 3 หลัก (มี 0 นำหน้า) สำหรับค่าที่อยู่ระหว่างนั้น คุณใช้เงื่อนไขได้เฉพาะกับรูปแบบย่อย 2 รูปแบบแรกเท่านั้น และหากตัวเลขตรงกับรูปแบบมากกว่า 1 รูปแบบ ชีตจะใช้รูปแบบแรกที่ตรงกัน หากมีรูปแบบที่ 3 ชีตจะใช้รูปแบบดังกล่าวกับ "ทุกอย่างที่เหลือ" ไม่เช่นนั้น หากตัวเลขไม่ตรงกับรูปแบบใดเลย ชีตจะแสดงผลอักขระ "#" ทั้งหมดตามความกว้างของเซลล์ หากมี รูปแบบที่ 4 จะใช้กับข้อความเสมอ |
[Color] or [Color#] |
ทำให้ค่าใดๆ ที่รูปแบบย่อยนี้แสดงผลปรากฏพร้อมกับสีข้อความที่ระบุ ค่าที่ถูกต้องสำหรับ Color ได้แก่ Black, Blue, Cyan, Green, Magenta, Red, White หรือ Yellow
ค่าที่ถูกต้องสำหรับ "#" ใน Color# คือตั้งแต่ 1 ถึง 56 สีของรูปแบบตัวเลขจะลบล้างสีที่ผู้ใช้ป้อนในเซลล์ แต่จะไม่ลบล้างสีที่ตั้งค่าโดยการจัดรูปแบบตามเงื่อนไข Color Paletteนี้แสดงรายการสีที่สอดคล้องกับตัวเลขแต่ละตัว โดยอิงตามพร็อพเพอร์ตี้ ColorIndex ใน Microsoft Excel |
[$currency] |
แสดงสัญลักษณ์หรือรหัสสกุลเงินที่ระบุเป็นค่าคงที่ (เช่น [$€]#,##0.00 หรือ [$CAD]#,##0.00) หากคุณใส่รหัสภาษาที่ไม่บังคับหลังเครื่องหมายขีดกลาง (เช่น [$CAD-1009]) ชีตจะไม่สนใจรหัสภาษานั้น |
ตัวอย่างรูปแบบตัวเลข
ตารางต่อไปนี้แสดงตัวอย่างรูปแบบและการแสดงผลตัวเลขที่จัดรูปแบบที่เกี่ยวข้อง
| ตัวเลข | รูปแบบ | ค่าที่จัดรูปแบบ |
|---|---|---|
| 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 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 |
HIGH LOW 0527 |