Formati di data e numero

Questo documento descrive come definire nuovi pattern di formato di data e numero, che puoi includere nella richiesta API.

I formati di data/ora e numero consentono di controllare in che modo i tuoi dati vengono visualizzati in un foglio. Fogli Google fornisce alcuni formati comuni tra cui scegliere, ma puoi anche definire formati personalizzati.

Nella UI di Fogli, i formati di numeri e date vengono applicati alle celle utilizzando il menu Formato > Numero. Nell'API Google Sheets, imposti questi formati utilizzando una chiamata al metodo spreadsheets.batchUpdate per inviare un UpdateCellsRequest o RepeatCellRequest. Nella richiesta, configuri l'oggetto NumberFormat specificando un NumberFormatType (ad esempio NUMBER, CURRENCY, PERCENT, DATE o TIME) e una stringa pattern facoltativa. Se ometti pattern, Fogli utilizza il pattern di formato predefinito per il valore type specificato in base alla locale del foglio di lavoro (ad esempio, $1,000.12 per CURRENCY in en_US).

L'esempio Imposta un formato data/ora o decimale personalizzato per un intervallo mostra come impostare un pattern di formato utilizzando l'API Sheets. Tieni presente che il rendering effettivo del formato dipende dalle locale del foglio di lavoro. Questo documento presuppone che locale sia en_US. Puoi determinare il locale di un foglio di lavoro leggendo l'oggetto SpreadsheetProperties utilizzando il metodo spreadsheets.get sulla risorsa spreadsheets.

Per altri esempi, consulta Formattazione di base e Formattazione condizionale.

Informazioni sui valori di data e ora

Fogli, come la maggior parte delle altre applicazioni per fogli di lavoro, tratta i valori di data e ora come valori decimali. In questo modo puoi eseguire operazioni aritmetiche su questi valori nelle formule, ad esempio incrementare giorni o settimane, aggiungere o sottrarre due date e ore ed eseguire altre operazioni simili.

Fogli utilizza una forma di data epoch di uso comune nei fogli di lavoro. La parte intera del valore (a sinistra del separatore decimale) conta i giorni dal 30 dicembre 1899. La parte frazionaria (a destra del decimale) conteggia l'ora come una frazione di un giorno. Ad esempio, il 1° gennaio 1900 a mezzogiorno è 2.5, 2 perché sono trascorsi 2 giorni dal 30 dicembre 1899 e 0.5 perché mezzogiorno è mezza giornata. Il 1° febbraio 1900 alle 15:00 è 33.625.

Fogli considera correttamente l'anno 1900 come un anno comune, non un anno bisestile. I numeri di serie di data e ora non memorizzano un offset del fuso orario. Si basano invece sulla proprietà timeZone del foglio di lavoro, che puoi leggere dall'oggetto SpreadsheetProperties utilizzando il metodo spreadsheets.get.

Pattern dei formati di data e ora

Un pattern di formato data/ora è una stringa di sottostringhe di token che Fogli sostituisce con gli elementi di data/ora corrispondenti (ad esempio il mese o l'ora) quando viene analizzata.

Token di formato di data e ora

La tabella seguente definisce le sottostringhe dei token che puoi utilizzare in un pattern di formato data/ora. Un carattere + indica che il carattere precedente può apparire una o più volte e corrispondere comunque al pattern. Fogli tratta i caratteri non elencati in questa tabella come valori letterali e li restituisce senza modifiche.

Token Descrizione
h Ora del giorno. Passa dal formato 12 ore a quello 24 ore a seconda che nella stringa sia presente un indicatore AM o PM.
hh+ Come sopra, ma con uno 0 iniziale per i numeri da 1 a 9.
m Se il token non letterale precedente era ore o quello successivo è secondi, rappresenta i minuti nell'ora (senza uno 0 iniziale). In caso contrario, rappresenta il mese dell'anno sotto forma di numero (senza uno 0 iniziale).
M Il mese dell'anno senza uno 0 iniziale. Utilizza questo token per indicare espressamente un mese, anziché un minuto, nel pattern.
mm Uguale a m, ma con uno 0 iniziale per entrambi i casi.
MM Il mese dell'anno con uno 0 iniziale. Utilizza questo token per indicare espressamente un mese, anziché un minuto, nel pattern.
mmm Abbreviazione del mese di tre lettere (ad esempio, "Feb").
mmmm Nome completo del mese. Anche mmmmmm+ corrisponde a questo.
mmmmm Prima lettera del mese (ad esempio, "G" per giugno).
s Secondi nel minuto senza uno 0 iniziale.
ss Secondi nel minuto con uno 0 iniziale.
[h+] Numero di ore trascorse in un periodo di tempo. Il numero di lettere indica il numero minimo di cifre (aggiunge gli 0 iniziali).
[m+] Numero di minuti trascorsi in un periodo di tempo. Il numero di lettere indica il numero minimo di cifre (aggiunge gli 0 iniziali).
[s+] Numero di secondi trascorsi in un periodo di tempo. Il numero di lettere indica il numero minimo di cifre (aggiunge gli 0 iniziali).
d Giorno del mese, senza lo 0 iniziale per i numeri inferiori a 10.
dd Giorno del mese, con uno 0 iniziale per i numeri inferiori a 10.
ddd Giorno della settimana, abbreviazione di tre lettere (ad esempio, "Mon").
dddd+ Giorno della settimana, nome completo.
y Anno a 2 cifre.
yy
yyy Anno a 4 cifre.
yyyy+
a/p Visualizza "a" per AM e "p" per PM. Inoltre, cambia l'ora nel formato a 12 ore. Se la lettera del token è in maiuscolo, lo è anche l'output.
am/pm Come sopra, ma visualizza "AM" o "PM" ed è sempre in lettere maiuscole.
0 Decimi di secondo. Puoi aumentare la precisione a due cifre con 00 o a tre cifre (millisecondi) con 000.
\ Tratta il carattere successivo come un valore letterale e non come un significato speciale che potrebbe avere.
"text" Visualizza il testo tra virgolette come valore letterale.

Esempi di formati di data e ora

Data la data e l'ora Tuesday, April 5, 2016, 4:08:53.528 PM, la tabella seguente mostra alcuni pattern di esempio e il rendering di data e ora corrispondente. La seconda sezione della tabella mostra esempi di formati di tempo trascorso per un tempo trascorso di 3 hours, 13 minutes, 41.255 seconds:

Pattern di data e ora 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 aprile [Tuesday]
h PM, ddd mmm dd 16:00, mar 5 apr
dddd, m/d/yy at h:mm Martedì 5/4/16 alle 16:08
Pattern di tempo trascorso 3 hours, 13 minutes, 41.255 seconds
[hh] 03
[mmmm] 0193
[ss] 11621

Pattern di formato numerico

Un pattern di formato numerico è una stringa di sottostringhe di token che Fogli sostituisce con le rappresentazioni numeriche corrispondenti quando viene analizzata. Un pattern di formato numerico può essere composto da un massimo di quattro sezioni, separate da punti e virgola, che definiscono i formati separati utilizzati per i numeri positivi, i numeri negativi, lo zero e il testo (in questo ordine):

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

Non è necessario includere tutte e quattro le sezioni in un formato. Se includi una sola sezione, Fogli utilizza quel formato per tutti i valori. Se utilizzi due sezioni, il primo formato viene applicato ai numeri positivi e allo zero, mentre il secondo formato viene applicato ai numeri negativi. L'utilizzo di tre sezioni definisce formati separati per i numeri positivi, negativi e zero. Ad esempio:

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

Tuttavia, se sono presenti due o più sezioni e l'ultima è un formato di testo, Fogli la tratta come formato di testo e le altre si comportano come se ci fosse una sezione in meno. Pertanto, includendo un formato di testo finale, è possibile definire formati come:

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

L'analisi di un formato in sezioni avviene prima di altre analisi, quindi è possibile includere un formato di data o ora come una delle sezioni (anche se l'utilità è limitata).

Token di formato numerico

La tabella seguente definisce le sottostringhe dei token che puoi utilizzare in una sezione di formato per definire come rappresentare i valori per quella sezione.

Token Descrizione
0 Rappresenta una cifra nel numero. Se la cifra è uno 0 non significativo, viene visualizzato come 0. Ad esempio, il formato numerico 00.0 visualizza il numero 3 come "03.0".
# Rappresenta una cifra nel numero. Se la cifra è uno 0 non significativo, non viene visualizzata. Ad esempio, il formato numerico ##0 visualizza il numero 12 come "12".
? Rappresenta una cifra nel numero. Se la cifra è uno 0 non significativo, viene visualizzata come uno spazio. Questo viene spesso utilizzato per allineare il separatore decimale in una colonna quando si utilizzano caratteri a larghezza fissa. Ad esempio, il formato numerico ???.??? mostra il numero 12,4 come: " 12.4 ".
. Il primo punto rappresenta il separatore decimale nel numero. I punti successivi vengono visualizzati come valori letterali. Se includi un separatore decimale nel formato, questo viene sempre visualizzato, anche per i numeri interi. Ad esempio, #0.# visualizza il numero 3 come "3.".
% Viene visualizzato come valore letterale, ma fa anche sì che i numeri esistenti vengano moltiplicati per 100 prima di essere visualizzati per rendere le percentuali più leggibili. Ad esempio, il formato numerico #% restituisce il numero 0,25 come "25%".
, Se viene visualizzato tra due caratteri numerici (0, # o ?), l'intero numero viene visualizzato con i separatori di raggruppamento (raggruppamento per migliaia). Se segue i caratteri numerici, scala le cifre di mille per virgola (ad esempio, il formato #0.0,, visualizza il numero 12.200.000 come 12.2).
E- Visualizza il numero in formato scientifico, con la formattazione a sinistra di E utilizzata per la parte non esponenziale e la formattazione a destra di E utilizzata per la parte esponenziale. E+ mostra un segno + per gli esponenti positivi. E- mostra un segno solo per gli esponenti negativi. Se utilizzi lettere minuscole, anche l'output e sarà in minuscolo. Ad esempio, il formato numerico ##0.00#E+## restituisce il numero 0,0000001 come "100.00E-9".
E+
e-
e+
/ Se appare tra due caratteri numerici (0, # o ?), tratta questi gruppi di cifre come un formato frazionario. Ad esempio, il formato numerico 0 #/# visualizza il numero 23,25 come 23 1/4. Il denominatore può anche essere un numero intero letterale, nel qual caso impone quel numero intero come denominatore. Il formato numerico 0 #/8 visualizza il numero 23,25 come 23 2/8. La parte della frazione non viene visualizzata se il numeratore diventa 0. Il numero 23,1 con il formato numerico 0 #/3 viene visualizzato come 23 (perché 0,1 viene arrotondato a 0/3). / non è compatibile con il formato scientifico o con un formato con un separatore decimale.
* Incluso per la compatibilità con i formati numerici di Microsoft Excel. Fogli ignora questo token.
_ Salta il carattere successivo e visualizza uno spazio. Utilizza questo token per allineare i formati numerici in cui il valore negativo è racchiuso tra parentesi.
\ Tratta il carattere successivo come un valore letterale e non come un significato speciale che potrebbe avere. Ad esempio, il formato numerico \#0 mostra il numero 10 come "#10".
"text" Visualizza il testo tra virgolette come valore letterale.
@ Se la cella contiene testo, inserisce il testo non elaborato della cella. Non è compatibile con nessuno degli altri caratteri speciali e non viene visualizzato per i valori numerici (che vengono visualizzati nel formato generale).
$ - + ( ) : space Fogli tratta questi caratteri e i simboli di valuta comuni (come $, €, £ e ¥) come valori letterali e li visualizza invariati.

Meta istruzioni

Inoltre, ciascuna delle sezioni del formato può avere metaistruzioni facoltative, racchiuse tra i caratteri [], che precedono il formato e forniscono istruzioni aggiuntive:

Istruzione Descrizione
[condition] Sostituisce il confronto predefinito positivo, negativo o zero della sezione con un'altra espressione condizionale. Ad esempio, [<100]"Low";[>1000]"High";000 visualizza la parola "Basso" per i valori inferiori a 100, "Alto" per i valori superiori a 1000 e un numero di tre cifre (con 0 iniziali) per i valori intermedi. Puoi applicare condizioni solo ai primi due formati secondari e, se un numero corrisponde a più di uno, Fogli utilizza la prima corrispondenza. Se esiste un terzo formato, Fogli lo utilizza per "tutto il resto"; in caso contrario, se un numero non corrisponde a nessuno dei due formati, Fogli visualizza tutti i caratteri "#" per tutta la larghezza della cella. Se esiste, il quarto formato viene sempre utilizzato per il testo.
[Color] or [Color#] Fa sì che qualsiasi valore visualizzato da questo formato secondario venga visualizzato con il colore del testo specificato. I valori validi per Color sono Black, Blue, Cyan, Green, Magenta, Red, White o Yellow. I valori validi per "#" in Color# sono compresi tra 1 e 56. I colori del formato numerico sostituiscono i colori inseriti dall'utente nella cella, ma non i colori impostati dalla formattazione condizionale. Questa tavolozza dei colori mostra un elenco di colori che corrispondono a ciascun numero. Si basano sulla proprietà ColorIndex in Microsoft Excel.
[$currency] Visualizza il simbolo o il codice della valuta specificato come valore letterale (ad esempio, [$€]#,##0.00 o [$CAD]#,##0.00). Se includi un codice locale facoltativo dopo un trattino (ad esempio, [$CAD-1009]), Fogli ignora il codice locale.

Esempi di formati numerici

La seguente tabella mostra alcuni pattern di esempio e il rendering del numero formattato corrispondente:

Numero Pattern Valore formattato
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 $
(1234,56 $)
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 ALTO
BASSO
0527