Formaty daty i liczb

W tym dokumencie opisano, jak definiować nowe wzorce formatu daty i liczby, które można uwzględnić w żądaniu do interfejsu API.

Formaty daty i godziny oraz liczb pozwalają określić sposób wyświetlania danych w arkuszu. Arkusze Google udostępniają kilka popularnych formatów do wyboru, ale możesz też zdefiniować własne formaty.

W interfejsie Arkuszy formaty liczb i dat stosuje się do komórek za pomocą menu Format > Liczba. W interfejsie Google Sheets API te formaty ustawia się za pomocą wywołania metody spreadsheets.batchUpdate, które wysyła UpdateCellsRequest lub RepeatCellRequest. W żądaniu konfigurujesz obiekt NumberFormat, określając NumberFormatType (np. NUMBER, CURRENCY, PERCENT, DATE lub TIME) i opcjonalny ciąg znaków pattern. Jeśli pominiesz parametr pattern, Arkusze użyją domyślnego wzorca formatu dla określonego parametru type na podstawie parametru locale arkusza kalkulacyjnego (na przykład $1,000.12 dla parametru CURRENCY w en_US).

Przykładowy kod Ustawianie niestandardowego formatu daty i godziny lub formatu dziesiętnego dla zakresu pokazuje, jak ustawić wzorzec formatu za pomocą interfejsu Sheets API. Pamiętaj, że rzeczywiste renderowanie formatu zależy od locale arkusza kalkulacyjnego. W tym dokumencie przyjęto, że locale to en_US. Możesz określić locale arkusza kalkulacyjnego, odczytując obiekt SpreadsheetProperties za pomocą metody spreadsheets.get zasobu spreadsheets.

Więcej przykładów znajdziesz w artykułach Formatowanie podstawowe i Formatowanie warunkowe.

Wartości daty i godziny

Arkusze, podobnie jak większość innych aplikacji do obsługi arkuszy kalkulacyjnych, traktują wartości daty i godziny jako wartości dziesiętne. Dzięki temu możesz wykonywać na nich działania arytmetyczne w formułach, np. zwiększać liczbę dni lub tygodni, dodawać lub odejmować 2 daty i godziny oraz wykonywać inne podobne operacje.

Arkusze używają formy daty epoki, która jest powszechnie używana w arkuszach kalkulacyjnych. Część całkowita wartości (po lewej stronie przecinka) to liczba dni od 30 grudnia 1899 r. Część ułamkowa (po prawej stronie przecinka) określa czas jako ułamek dnia. Na przykład 1 stycznia 1900 r. w południe to 2.5, 2, ponieważ jest to 2 dni po 30 grudnia 1899 r., i 0.5, ponieważ południe to połowa dnia. 1 lutego 1900 r. o godz. 15:00 to 33.625.

Arkusze prawidłowo traktują rok 1900 jako rok zwykły, a nie przestępny. Numery seryjne daty i godziny nie przechowują przesunięcia strefy czasowej. Zamiast tego są one oparte na timeZone arkusza kalkulacyjnego, które można odczytać z obiektu SpreadsheetProperties za pomocą metody spreadsheets.get.

Wzorce formatu daty i godziny

Wzorzec formatu daty i godziny to ciąg podłańcuchów tokenów, które Arkusze zastępują odpowiednimi elementami daty i godziny (takimi jak miesiąc lub godzina) podczas analizy.

Tokeny formatu daty i godziny

W tabeli poniżej znajdziesz podłańcuchy tokenów, których możesz używać we wzorcu formatu daty i godziny. Znak + wskazuje, że poprzedni znak może pojawić się co najmniej raz i nadal pasować do wzorca. Arkusze traktują znaki, których nie ma w tej tabeli, jako literały i wyświetlają je bez zmian.

Token Opis
h Godzina. Przełącza między formatem 12- i 24-godzinnym w zależności od tego, czy w ciągu znaków występuje wskaźnik AM lub PM.
hh+ Tak samo jak poprzednio, ale z zerem na początku w przypadku liczb 1–9.
m Jeśli poprzedni token nieliteralny reprezentował godziny lub następny reprezentuje sekundy, ten token reprezentuje minuty w godzinie (bez zera na początku). W innym przypadku reprezentuje miesiąc roku jako liczbę (bez zera na początku).
M Miesiąc roku bez zera na początku. Użyj tego tokena, aby we wzorcu wyraźnie określić miesiąc, a nie minutę.
mm Tak samo jak m, ale z zerem na początku w obu przypadkach.
MM Miesiąc roku z zerem na początku. Użyj tego tokena, aby we wzorcu wyraźnie określić miesiąc, a nie minutę.
mmm Trzyliterowy skrót nazwy miesiąca (np. „lut”).
mmmm Pełna nazwa miesiąca. mmmmmm+ również pasuje do tego zapytania.
mmmmm Pierwsza litera miesiąca (np. „C” dla czerwca).
s Sekundy w minucie bez zera na początku.
ss Sekundy w minucie z zerem na początku.
[h+] Liczba godzin, które upłynęły w danym okresie. Liczba liter wskazuje minimalną liczbę cyfr (dodaje zera na początku).
[m+] Liczba minut, które upłynęły w danym przedziale czasu. Liczba liter wskazuje minimalną liczbę cyfr (dodaje zera na początku).
[s+] Liczba sekund, które upłynęły w danym okresie. Liczba liter wskazuje minimalną liczbę cyfr (dodaje zera na początku).
d Dzień miesiąca bez zera na początku w przypadku liczb mniejszych niż 10.
dd Dzień miesiąca z zerem na początku w przypadku liczb mniejszych niż 10.
ddd Dzień tygodnia, trzyliterowy skrót (np. „pon”).
dddd+ Dzień tygodnia, pełna nazwa.
y dwucyfrowy rok,
yy
yyy Rok w formacie 4-cyfrowym.
yyyy+
a/p Wyświetla „a” w przypadku godzin przed południem i „p” w przypadku godzin po południu. Zmienia też format godzin na 12-godzinny. Jeśli litera tokena jest wielka, dane wyjściowe też będą wielką literą.
am/pm Podobnie jak powyżej, ale wyświetla „AM” lub „PM” i zawsze jest pisane wielkimi literami.
0 Dziesiętne części sekundy. Możesz zwiększyć precyzję do 2 cyfr za pomocą 00 lub do 3 cyfr (milisekundy) za pomocą 000.
\ Traktuje następny znak jako literał, a nie jako znak specjalny.
"text" Wyświetla tekst w cudzysłowie jako literał.

Przykłady formatów daty i godziny

W tabeli poniżej znajdziesz przykładowe wzorce zapisu daty i godziny Tuesday, April 5, 2016, 4:08:53.528 PM oraz odpowiadające im dni, miesiące, lata i godziny. W drugiej sekcji tabeli znajdziesz przykłady formatów czasu, który upłynął, dla wartości 3 hours, 13 minutes, 41.255 seconds:

Wzorce daty i godziny Tuesday, April 5, 2016, 4:08:53.528 PM
h:mm:ss.00 a/p 16:08:53.53
hh:mm A/P".M." 16:08
yyyy-mm-dd 2016-04-05
mmmm d \[dddd\] 5 kwietnia [wtorek]
h PM, ddd mmm dd 16:00, wt., 5 kwietnia
dddd, m/d/yy at h:mm Wtorek, 5.04.2016 o 16:08
Wzorce czasu między zdarzeniami 3 hours, 13 minutes, 41.255 seconds
[hh] 03
[mmmm] 0193
[ss] 11621

Wzorce formatu liczb

Wzorzec formatu liczb to ciąg podłańcuchów tokenów, które Arkusze zastępują odpowiednimi reprezentacjami liczb podczas analizy. Wzorzec formatu liczb może składać się z maksymalnie 4 sekcji rozdzielonych średnikami, które definiują osobne formaty używane dla liczb dodatnich, liczb ujemnych, zera i tekstu (w tej kolejności):

[POSITIVE FORMAT];[NEGATIVE FORMAT];[ZERO FORMAT];[TEXT FORMAT]

Nie musisz uwzględniać wszystkich 4 sekcji w formacie. Jeśli uwzględnisz tylko jedną sekcję, Arkusze będą używać tego formatu dla wszystkich wartości. Jeśli użyjesz 2 sekcji, pierwszy format zostanie zastosowany do zera i liczb dodatnich, a drugi do liczb ujemnych. Użycie 3 sekcji pozwala zdefiniować osobne formaty dla liczb dodatnich, ujemnych i zer. Na przykład:

[NUMBER FORMAT]
[POSITIVE/ZERO FORMAT];[NEGATIVE FORMAT]
[POSITIVE FORMAT];[NEGATIVE FORMAT];[ZERO FORMAT]

Jeśli jednak są co najmniej 2 sekcje, a ostatnia sekcja jest formatem tekstowym, Arkusze traktują tę sekcję jako format tekstowy, a pozostałe zachowują się tak, jakby było o 1 sekcję mniej. Dzięki temu, dodając końcowy format tekstowy, można zdefiniować formaty takie jak:

[POSITIVE/ZERO FORMAT];[NEGATIVE FORMAT];[TEXT FORMAT]
[NUMBER FORMAT];[TEXT FORMAT]

Analiza formatu pod kątem sekcji odbywa się przed innymi analizami, więc możliwe jest uwzględnienie formatu daty lub godziny jako jednej z sekcji (choć jest to mało przydatne).

Tokeny formatu liczb

W tabeli poniżej znajdziesz podłańcuchy tokenów, których możesz używać w sekcji formatu, aby określić, jak mają być reprezentowane wartości w tej sekcji.

Token Opis
0 Reprezentuje cyfrę w liczbie. Jeśli cyfra jest nieistotnym zerem, jest renderowana jako 0. Na przykład format liczby 00.0 wyświetla liczbę 3 jako „03.0”.
# Reprezentuje cyfrę w liczbie. Jeśli cyfra jest nieznaczącym zerem, nie jest renderowana. Na przykład format liczbowy ##0 wyświetla liczbę 12 jako „12”.
? Reprezentuje cyfrę w liczbie. Jeśli cyfra jest nieuwzględnianym zerem, jest wyświetlana jako spacja. Jest to często używane do wyrównywania separatora dziesiętnego w kolumnie, gdy używane są czcionki o stałej szerokości. Na przykład format liczb ???.??? wyświetla liczbę 12, 4 jako: „12.4”.
. Pierwsza kropka reprezentuje separator dziesiętny w liczbie. Kolejne kropki są renderowane jako literały. Jeśli w formacie uwzględnisz separator dziesiętny, będzie on zawsze wyświetlany, nawet w przypadku liczb całkowitych. Na przykład #0.# renderuje liczbę 3 jako „3.”.
% Wyświetla się jako literał, ale powoduje też, że istniejące liczby są mnożone przez 100 przed renderowaniem, aby wartości procentowe były bardziej czytelne. Na przykład format liczb #% wyświetla liczbę 0, 25 jako „25%”.
, Jeśli pojawia się między dwoma znakami cyfrowymi (0, # lub ?), cała liczba jest renderowana z separatorami grupowania (grupowanie według tysięcy). Jeśli występuje po cyfrach, skaluje je o tysiąc na każdy przecinek (np. format #0.0,, wyświetla liczbę 12 200 000 jako 12.2).
E- Wyświetla liczbę w formacie naukowym, przy czym formatowanie po lewej stronie znaku E jest używane dla części bez wykładnika, a formatowanie po prawej stronie znaku E jest używane dla części z wykładnikiem. E+ wyświetla znak + w przypadku wykładników dodatnich. E- pokazuje znak tylko w przypadku wykładników ujemnych. Jeśli użyjesz małych liter, dane wyjściowe e również będą zapisane małymi literami. Na przykład format liczby ##0.00#E+## powoduje, że liczba 0,0000001 jest wyświetlana jako „100.00E-9”.
E+
e-
e+
/ Jeśli pojawia się między dwoma znakami cyfrowymi (0, # lub ?), traktuje te grupy cyfr jako format ułamkowy. Na przykład format liczbowy 0 #/# wyświetla liczbę 23, 25 jako 23 1/4. Mianownik może też być liczbą całkowitą, która jest wtedy wymuszana jako mianownik. Format liczb 0 #/8 wyświetla liczbę 23,25 jako 23 2/8. Część ułamkowa nie jest renderowana, jeśli licznik wynosi 0. Liczba 23,1 z formatem liczb 0 #/3 jest wyświetlana jako 23 (ponieważ 0,1 jest zaokrąglane do 0/3). / nie jest zgodny z formatem naukowym ani formatem z separatorem dziesiętnym.
* Uwzględniono ze względu na zgodność z formatami liczb w programie Microsoft Excel. Arkusze ignorują ten token.
_ Pomija następny znak i wyświetla spację. Użyj tego tokena, aby wyrównać formaty liczb, w których wartość ujemna jest ujęta w nawiasy.
\ Traktuje następny znak jako literał, a nie jako znak specjalny. Na przykład format liczbowy \#0 wyświetla liczbę 10 jako „#10”.
"text" Wyświetla tekst w cudzysłowie jako literał.
@ Jeśli komórka zawiera tekst, wstawia nieprzetworzony tekst z komórki. Nie jest zgodny z żadnymi innymi znakami specjalnymi i nie jest wyświetlany w przypadku wartości liczbowych (które są wyświetlane w formacie ogólnym).
$ - + ( ) : space Arkusze traktują te znaki i typowe symbole walut (takie jak $, €, £ i ¥) jako literały i wyświetlają je bez zmian.

Metainstrukcje

Dodatkowo każda sekcja formatu może zawierać opcjonalne instrukcje meta, ujęte w znaki [], które poprzedzają format i zawierają dodatkowe instrukcje:

Instrukcja Opis
[condition] Zastępuje domyślne porównanie dodatnie, ujemne lub zerowe sekcji innym wyrażeniem warunkowym. Na przykład [<100]"Low";[>1000]"High";000 wyświetla słowo „Niski” w przypadku wartości poniżej 100, „Wysoki” w przypadku wartości powyżej 1000 i liczbę 3-cyfrową (z zerami na początku) w przypadku wartości pomiędzy. Warunki możesz stosować tylko do pierwszych 2 podformatów. Jeśli liczba pasuje do więcej niż jednego podformatu, Arkusze używają pierwszego dopasowania. Jeśli istnieje trzeci format, Arkusze używają go do „wszystkiego innego”. W przeciwnym razie, jeśli liczba nie pasuje do żadnego formatu, Arkusze wyświetlają znaki „#” na całej szerokości komórki. Jeśli istnieje, czwarty format jest zawsze używany do tekstu.
[Color] or [Color#] Powoduje, że każda wartość renderowana przez ten podformat jest wyświetlana z określonym kolorem tekstu. Prawidłowe wartości parametru Color to: Black (czarny), Blue (niebieski), Cyan (błękitny), Green (zielony), Magenta (purpurowy), Red (czerwony), White (biały) lub Yellow (żółty). Prawidłowe wartości „#” w Color# to liczby od 1 do 56. Kolory formatu liczb zastępują wszystkie kolory wprowadzone przez użytkownika w komórce, ale nie zastępują kolorów ustawionych przez formatowanie warunkowe. Ta paleta kolorów zawiera listę kolorów odpowiadających poszczególnym liczbom. Są one oparte na właściwości ColorIndex w programie Microsoft Excel.
[$currency] Wyświetla określony symbol lub kod waluty jako literał (np. [$€]#,##0.00 lub [$CAD]#,##0.00). Jeśli po łączniku dodasz opcjonalny kod języka (np. [$CAD-1009]), Arkusze go zignorują.

Przykładowe formaty liczb

W tabeli poniżej znajdziesz przykładowe wzorce oraz odpowiadające im sformatowane liczby:

Liczba Wzór Wartość sformatowana
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) 1234,56 PLN
(1234,56 PLN)
1230000 0.0,,"M" 1,2 mln
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 WYSOKA
NISKA
0527