Os formatos de número e data/hora permitem controlar como seus dados aparecem em uma página. O Planilhas Google oferece alguns formatos comuns para escolher, mas você também pode definir seus próprios formatos.
Na IU do Planilhas, aplique formatos de número e data às células usando o menu Formato > Número. Na API Sheets, você define esses formatos usando uma chamada de método spreadsheets.batchUpdate para enviar um UpdateCellsRequest ou RepeatCellRequest.
Nesta página, descrevemos como definir novos padrões de formato de data e número que você pode incluir na sua solicitação de API. O exemplo em Definir um formato personalizado de data/hora ou decimal para um intervalo mostra como definir um padrão de formato usando a API. A renderização real do formato depende do locale da planilha. Neste guia, pressupomos que
locale seja en_US. Você pode determinar o locale de uma planilha lendo o SpreadsheetProperties com uma solicitação spreadsheets.get.
Sobre os valores de data e hora
O Planilhas, como a maioria dos outros aplicativos de planilha, trata os valores de data e hora como valores decimais. Isso permite que você realize operações aritméticas nelas em fórmulas. Assim, é possível incrementar dias ou semanas, adicionar ou subtrair duas datas e horas e realizar outras operações semelhantes.
O Planilhas usa uma forma de
data de época
(em inglês) comumente usada em planilhas. A parte numérica inteira do valor (à esquerda do decimal) conta os dias desde 30 de dezembro de 1899. A parte fracionária (à direita do separador decimal) conta o tempo como uma fração de um dia. Por
exemplo, 1o de janeiro de 1900 ao meio-dia é 2.5, 2 por ser 2 dias depois de
30 de dezembro de 1899 e 0.5 porque meio-dia equivale a metade de um dia. 1o de fevereiro de 1900, às 15h,
é 33.625.
O Planilhas Google trata o ano de 1900 como um ano comum, não bissexto.
Padrões de formato de data e hora
Um padrão de formato de data-hora é uma string de substrings de token que, quando analisadas, são substituídas pelos elementos de data-hora correspondentes (como o mês ou a hora).
Tokens de formato de data e hora
A tabela a seguir define as substrings de token que podem ser usadas em um padrão de formato de data-hora. Um caractere + indica que o caractere anterior pode aparecer
uma ou mais vezes e ainda corresponder ao padrão. Os caracteres não listados na tabela abaixo são tratados como literais e exibidos sem alterações.
| Token | Descrição |
|---|---|
h |
Hora do dia. Alterna entre o formato de 12 e 24 horas, dependendo da presença de um indicador AM ou PM na string. |
hh+ |
O mesmo que antes, mas com um 0 no início de 1 a 9. |
m |
Se o token não literal anterior for horas ou o seguinte for segundos, ele representará os minutos da hora (sem um 0 no início). Caso contrário, ele representará o mês do ano como um número (sem 0 no início). |
M |
O mês do ano sem um 0 no início. Use esse token para indicar expressamente um mês, em vez de um minuto, no seu padrão. |
mm |
O mesmo que m, mas com um 0 à esquerda para os dois casos. |
MM |
O mês do ano com um 0 na frente. Use esse token para indicar expressamente um mês, em vez de um minuto, no seu padrão. |
mmm |
Abreviação de três letras para o mês (por exemplo, "Fev"). |
mmmm |
Nome completo do mês. mmmmmm+ também corresponde a isso. |
mmmmm |
Primeira letra do mês (por exemplo, "J" para junho). |
s |
Segundos no minuto sem um 0 no início. |
ss |
Segundos no minuto com um 0 à esquerda. |
[h+] |
Número de horas decorridas em um período. O número de letras indica o número mínimo de dígitos (adiciona 0s à esquerda). |
[m+] |
Número de minutos decorridos em um período. O número de letras indica o número mínimo de dígitos (adiciona 0s à esquerda). |
[s+] |
Número de segundos decorridos em um período. O número de letras indica o número mínimo de dígitos (adiciona 0s à esquerda). |
d |
Dia do mês, sem 0 no início para números inferiores a 10. |
dd |
Dia do mês, com um 0 no início para números inferiores a 10. |
ddd |
Abreviação de três letras do dia da semana (por exemplo, "Seg"). |
dddd+ |
Dia da semana, nome completo. |
y |
Ano com 2 dígitos. |
yy |
|
yyy |
Ano com 4 dígitos. |
yyyy+ |
|
a/p |
Mostra "a" para AM e "p" para PM. Também muda as horas para o formato de 12 horas. Se a letra do token for maiúscula, o resultado também será. |
am/pm |
Igual ao anterior, mas exibe "AM" ou "PM" sempre em maiúsculas. |
0 |
Dezenas de segundos. É possível aumentar a precisão para dois dígitos com
00 ou três dígitos (milissegundos) com 000. |
\ |
Trata o próximo caractere como um valor literal e não qualquer significado especial que ele possa ter. |
"text" |
Mostra o texto dentro das aspas como literal. |
Exemplos de formato de data e hora
Considerando a data e a hora Tuesday, April 5, 2016, 4:08:53.528 PM, a tabela a seguir mostra alguns exemplos de padrões e a renderização correspondente de data-hora. A segunda seção da tabela mostra exemplos de formatos de tempo decorrido de 3 hours, 13 minutes, 41.255 seconds:
| Padrões de data e hora | Tuesday, April 5, 2016, 4:08:53.528 PM |
|---|---|
h:mm:ss.00 a/p |
16:08:53.53 p |
hh:mm A/P".M." |
16h08 |
yyyy-mm-dd |
2016-04-05 |
mmmm d \[dddd\] |
5 de abril [terça-feira] |
h PM, ddd mmm dd |
16h, terça-feira, 5 de abril |
dddd, m/d/yy at h:mm |
Terça-feira, 05/04/16 às 16h08 |
| Padrões de tempo decorrido | 3 hours, 13 minutes, 41.255 seconds |
[hh]:[mm]:[ss].000 |
03:13:41.255 |
[mmmm]:[ss].000 |
0193:41.255 |
Padrões de formato de número
Um padrão de formato de número é uma string de substrings de token que, quando analisadas, são substituídas pelas representações numéricas correspondentes. Um padrão de formato numérico pode consistir em até quatro seções, separadas por ponto e vírgula, que definem os formatos separados usados para números positivos, números negativos, zero e texto (nessa ordem):
[POSITIVE FORMAT];[NEGATIVE FORMAT];[ZERO FORMAT];[TEXT FORMAT]
Você não precisa incluir todas as quatro seções em um formato. Se você incluir apenas uma seção, esse formato será usado para todos os valores. O uso de duas seções faz com que o primeiro formato seja aplicado a zero e números positivos e o segundo a números negativos. O uso de três seções define formatos separados para números positivos, negativos e zero. Exemplo:
[NUMBER FORMAT] [POSITIVE/ZERO FORMAT];[NEGATIVE FORMAT] [POSITIVE FORMAT];[NEGATIVE FORMAT];[ZERO FORMAT]
No entanto, se houver duas ou mais seções e a última for um formato de texto, ela será tratada como o formato de texto, e as outras vão se comportar como se houvesse uma seção a menos. Assim, ao incluir um formato de texto final, é possível definir formatos como:
[POSITIVE/ZERO FORMAT];[NEGATIVE FORMAT];[TEXT FORMAT] [NUMBER FORMAT];[TEXT FORMAT]
A análise de um formato em seções ocorre antes de outra análise. Portanto, é possível incluir um formato de data ou hora como uma das seções (embora isso tenha utilidade limitada).
Tokens de formato de número
A tabela a seguir define as substrings de token que podem ser usadas em uma seção de formato para definir como representar os valores dessa seção.
| Token | Descrição |
|---|---|
0 |
Representa um dígito no número. Se o dígito for um 0 insignificante, ele será renderizado como 0. Por exemplo, o formato de número
00.0 renderiza o número 3 como "03.0". |
# |
Representa um dígito no número. Se o dígito for um 0 insignificante,
ele não será renderizado. Por exemplo, o formato de número ##0 renderiza o número 12 como "12". |
? |
Representa um dígito no número. Se o dígito for um 0 insignificante, ele será renderizado como um espaço. Isso é frequentemente usado para alinhar o ponto decimal em
uma coluna ao usar fontes de largura fixa. Por exemplo, o formato de número ???.??? renderiza o número 12.4 como: " 12.4 ". |
. |
O primeiro ponto representa o separador decimal do número. Os pontos
subsequentes são renderizados como literais. Se você incluir um ponto decimal no
formato, ele sempre será renderizado, mesmo para números inteiros. Por exemplo, #0.# renderiza o número 3 como "3.". |
% |
Aparece como um literal, mas também faz com que os números atuais sejam multiplicados por 100 antes de serem renderizados para tornar as porcentagens mais legíveis. Por exemplo, o formato de número #% renderiza o número 0,25 como "25%". |
, |
Se aparecer entre caracteres de dois dígitos (0, # ou ?), ele vai renderizar o número inteiro com separadores de agrupamento (agrupamento por milhares). Se ela seguir os caracteres de dígito, eles dimensionarão os dígitos em mil por vírgula (por exemplo, o formato #0.0,, renderiza o número 12.200.000 como 12.2). |
E- |
Renderiza o número no formato científico, com a formatação à esquerda do E usado para a parte não expoente e a formatação à direita do E usado para a parte expoente. E+ mostra um sinal + para expoentes positivos. E- mostra apenas um sinal para expoentes negativos. Se
minúsculas forem usadas, a saída e também será em minúsculas.
Por exemplo, o formato de número ##0.00#E+## renderiza o número 0,0000001 como "100.00E-9". |
E+ |
|
e- |
|
e+ |
|
/ |
Se aparecer entre caracteres de dois dígitos (0, # ou ?), ele tratará esses grupos de dígitos como um formato fracionário. Por exemplo, o formato de número 0 #/# renderiza
o número 23.25 como 23 1/4. O denominador também pode ser um número inteiro literal. Nesse caso, ele impõe esse número inteiro como o denominador. O formato de número 0 #/8
exibe o número 23.25 como 23 2/8. A parte da fração não será renderizada se o numerador se tornar 0. O número 23,1 com o formato numérico 0 #/3 é renderizado como 23, porque 0,1 é arredondado para 0/3. / não é compatível com o formato científico ou um formato com um ponto decimal. |
* |
Isso é incluído para compatibilidade com formatos de número do Microsoft Excel. No momento, ele é ignorado. |
_ |
O token de sublinhado ignora o próximo caractere e renderiza um espaço. É usado para alinhar formatos de número em que o valor negativo está entre parênteses. |
\ |
Trata o próximo caractere como um valor literal e não qualquer significado especial que ele possa ter. Por exemplo, o formato de número \#0 renderiza o número 10 como "#10". |
"text" |
Mostra o texto dentro das aspas como literal. |
@ |
Se a célula tiver entrada de texto, o texto bruto será inserido. Não é compatível com nenhum dos outros caracteres especiais e não é exibido para valores numéricos (que são exibidos como formato geral). |
$ - + ( ) : space |
O Planilhas trata esses caracteres como literais e os exibe sem alterações. |
Metainstruções
Além disso, cada uma das seções de formato pode ter metainstruções opcionais,
incluídas em caracteres [], que precedem o formato e fornecem
outras instruções. Há dois tipos de metainstrução, e uma determinada
seção pode usar ambos:
| Instrução | Descrição |
|---|---|
[condition] |
Substitui a comparação padrão positiva, negativa ou de zero da seção por outra expressão condicional. Por exemplo, [<100]”Low”;[>1000]”High”;000 renderiza a palavra "Low" para valores abaixo de 100, "High" para valores acima de 1.000 e um número de três dígitos (com 0s à esquerda) para qualquer valor intermediário. As condições só podem ser aplicadas aos dois primeiros subformatos e, se um número corresponder a mais de um, ele usará o primeiro correspondente. Se houver um terceiro formato, ele será usado para "todo o resto". Caso contrário, se um número não corresponder a nenhum dos formatos, ele será renderizado como todos os "#" preenchendo a largura da célula. Se existir, o
quarto formato será sempre usado para texto. |
[Color] or [Color#] |
Faz com que todos os valores renderizados por este subformato apareçam com a cor de texto especificada. Os valores válidos para Color são Preto, Azul, Ciano, Verde, Magenta, Vermelho, Branco ou Amarelo. Os valores válidos para "#" em Color# são 0&ndash1;56. Esta paleta de cores mostra uma lista das cores que correspondem a cada número. As cores do formato de número substituem as cores inseridas pelo usuário na célula, mas não as cores definidas por formatação condicional. |
Exemplos de formato de número
A tabela a seguir mostra alguns exemplos de padrões e a renderização de números formatados correspondente:
| Número | Padrão | Valor formatado |
|---|---|---|
| 12345,125 | ####.# |
12.345,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 milhão |
| 1234500000 | 0.00e+00 |
1,23e+09 |
| 123114.15115 MeuTexto |
###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 |
| 1.005 32 527 |
[>1000]"HIGH";[Color43][<=200]"LOW";0000 |
ALTA MENOR 0527 |