Neste documento, descrevemos como definir novos padrões de formato de data e número, que podem ser incluídos na solicitação de API.
Com os formatos de data, hora e número, você controla como seus dados aparecem em uma página. O Google Planilhas oferece alguns formatos comuns para você escolher, mas também é possível definir seus próprios formatos.
Na interface do app Planilhas, você aplica formatos de número e data às células
usando o menu Formatar > Número. Na API Google Sheets, você define esses
formatos usando uma chamada de método
spreadsheets.batchUpdate
para enviar um
UpdateCellsRequest
ou
RepeatCellRequest.
Na solicitação, configure o objeto
NumberFormat
especificando um
NumberFormatType
(como NUMBER, CURRENCY, PERCENT, DATE ou TIME) e uma string
pattern opcional. Se você omitir pattern, as Planilhas vão usar o padrão de formatação padrão para o type especificado com base na locale da planilha (por exemplo, $1,000.12 para CURRENCY em en_US).
O exemplo Definir um formato personalizado de data e hora ou decimal para um
intervalo mostra como definir
um padrão de formato usando a API Sheets. A renderização real
do formato depende da
locale da planilha.
Neste documento, consideramos que o locale é en_US. É possível determinar o locale de uma planilha lendo o objeto SpreadsheetProperties com o método spreadsheets.get no recurso spreadsheets.
Para mais exemplos, consulte Formatação básica e Formatação condicional.
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 realizar operações aritméticas com eles em fórmulas, para que você possa 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 que é usada com frequência em planilhas. A parte do número inteiro do valor (à esquerda do decimal) conta
os dias desde 30 de dezembro de 1899. A parte fracionária (à direita do decimal)
conta o tempo como uma fração de um dia. Por exemplo, 1º de janeiro de 1900 ao meio-dia
é 2.5, 2 porque é dois dias depois de 30 de dezembro de 1899, e 0.5 porque
meio-dia é metade de um dia. 1º de fevereiro de 1900 às 15h é 33.625.
O Planilhas trata corretamente o ano de 1900 como um ano comum, não um ano bissexto. Os números de série de data e hora não armazenam um ajuste de fuso horário. Em vez disso,
elas são baseadas no
timeZone
da planilha,
que pode ser lido no objeto
SpreadsheetProperties
usando o método
spreadsheets.get.
Padrões de formato de data e hora
Um padrão de formato de data e hora é uma string de substrings de token que as Planilhas substituem pelos elementos de data e hora correspondentes (como o mês ou a hora) quando analisados.
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 e hora. Um caractere + indica que o caractere anterior pode aparecer
uma ou mais vezes e ainda corresponder ao padrão. O Planilhas trata
os caracteres não listados nesta tabela como literais e os gera sem
alterações.
| Token | Descrição |
|---|---|
h |
Hora do dia. Alterna entre o formato de 12 e 24 horas, dependendo de um indicador AM ou PM estar presente na string. |
hh+ |
Igual ao anterior, mas com um 0 à esquerda para 1 a 9. |
m |
Se o token não literal anterior era de horas ou o seguinte é de segundos, ele representa minutos na hora (sem um 0 à esquerda). Caso contrário, representa o mês do ano como um número (sem um 0 à esquerda). |
M |
O mês do ano sem um 0 à esquerda. Use esse token para indicar expressamente um mês, em vez de um minuto, no seu padrão. |
mm |
Igual a m, mas com um 0 à esquerda para os dois casos. |
MM |
O mês do ano com um 0 à esquerda. 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 do 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 à esquerda. |
ss |
Segundos no minuto com um 0 à esquerda. |
[h+] |
Número de horas decorridas em uma duração. O número de letras indica o número mínimo de dígitos (adiciona zeros à esquerda). |
[m+] |
Número de minutos decorridos em uma duração. O número de letras indica o número mínimo de dígitos (adiciona zeros à 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 zeros à esquerda). |
d |
Dia do mês, sem um zero à esquerda para números menores que 10. |
dd |
Dia do mês, com um zero à esquerda para números menores que 10. |
ddd |
Dia da semana, abreviação de três letras (por exemplo, "Mon"). |
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 estiver em maiúscula, a saída também estará. |
am/pm |
Como acima, mas exibe "AM" ou "PM" e está sempre em letras maiúsculas. |
0 |
Décimos 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 como qualquer significado especial que ele possa ter. |
"text" |
Mostra o texto entre aspas como um literal. |
Exemplos de formato de data e hora
Considerando a data e hora Tuesday, April 5, 2016, 4:08:53.528 PM, a
tabela a seguir mostra alguns exemplos de padrões e a respectiva renderização de data e
hora. A segunda seção da tabela mostra exemplos de formatos de tempo decorrido
para um 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., 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] |
03 |
[mmmm] |
0193 |
[ss] |
11621 |
Padrões de formato de número
Um padrão de formatação de número é uma string de substrings de token que as Planilhas substituem pelas representações numéricas correspondentes quando analisadas. Um padrão de formato de número 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]
Não é necessário incluir as quatro seções em um formato. Se você incluir apenas uma seção, as Planilhas vão usar esse formato para todos os valores. O uso de duas seções aplica o primeiro formato a números zero e positivos e o segundo formato 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, as Planilhas vão tratar essa seção 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 outras análises, então é possível incluir um formato de data ou hora como uma das seções (embora isso seja de 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 é usado com frequência para alinhar o marcador 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 marcador decimal no número. Os períodos
subsequentes são renderizados como literais. Se você incluir um marcador decimal no
formato, ele será sempre 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 existentes 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 ele aparecer entre caracteres de dois dígitos (0,
# ou ?), ele renderiza o número inteiro
com separadores de agrupamento (agrupamento por milhares). Se ela seguir
os caracteres de dígito, vai dimensionar 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 em formato científico, com a
formatação à esquerda do E usada para a parte não exponencial
e a formatação à direita do E usada para a parte
exponencial. E+ mostra um sinal de + para expoentes
positivos. E- só mostra um sinal para expoentes negativos. Se
letras minúsculas forem usadas, a saída e também será em letras 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 ele aparecer entre caracteres de dois dígitos (0,
# ou ?), esses grupos de dígitos serão tratados 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 aplica esse número inteiro como
o denominador. O formato de número 0 #/8
mostra 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 de número 0 #/3 é renderizado como
23 (porque 0,1 é arredondado para 0/3). / não é
compatível com o formato científico ou com um formato que tenha um marcador
decimal. |
* |
Incluído para compatibilidade com os formatos de número do Microsoft Excel. O app Planilhas ignora esse token. |
_ |
Ignora o próximo caractere e renderiza um espaço. Use esse token para alinhar formatos de número em que os parênteses cercam o valor negativo. |
\ |
Trata o próximo caractere como um valor literal, e não como 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 entre aspas como um literal. |
@ |
Se a célula tiver entrada de texto, ela vai inserir o texto bruto da célula. 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 e símbolos de moeda comuns (como $, €, £ e ¥) 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,
entre caracteres [], que precedem o formato e fornecem outras
instruções:
| Instrução | Descrição |
|---|---|
[condition] |
Substitui a comparação padrão positiva, negativa ou zero da
seção por outra expressão condicional. Por exemplo,
[<100]"Low";[>1000]"High";000 renderiza a palavra
"Baixo" para valores abaixo de 100, "Alto" para valores acima de 1.000 e um número de três dígitos (com zeros à esquerda) para qualquer valor intermediário. Só é possível aplicar
condições aos dois primeiros subformatos. Se um número corresponder a mais de
um, as Planilhas vão usar a primeira correspondência. Se houver um terceiro
formato, o Planilhas vai usá-lo para "todo o resto". Caso contrário, se
um número não corresponder a nenhum dos formatos, o Planilhas vai renderizar todos os caracteres "#"
na largura da célula. Se existir, o
quarto formato será sempre usado para texto. |
[Color] or [Color#] |
Faz com que qualquer valor renderizado por esse subformato apareça com a
cor de texto especificada. Os valores válidos para Color são Black,
Blue, Cyan, Green, Magenta, Red, White ou Yellow.
Os valores válidos para "#" em Color# são de 1 a 56. As cores do formato de número
substituem as cores inseridas pelo usuário na célula, mas não as
definidas pela formatação condicional. Essa
paleta de cores
mostra uma lista de cores que correspondem a cada número. Eles são baseados na propriedade ColorIndex no Microsoft Excel. |
[$currency] |
Mostra o símbolo ou código da moeda especificada como um literal (por
exemplo, [$€]#,##0.00 ou [$CAD]#,##0.00). Se você
incluir um código de localidade opcional após um hífen (como
[$CAD-1009]), as Planilhas vão ignorar o código
de localidade. |
Exemplos de formato de número
A tabela a seguir mostra alguns exemplos de padrões e a respectiva renderização de números formatados:
| Número | Padrão | Valor formatado |
|---|---|---|
| 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) |
US$ 1.234,56 (US$ 1.234,56) |
| 1230000 | 0.0,,"M" |
1,2 milhão |
| 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 |
ALTA BAIXA 0527 |