convertTimeZone
Converte uma data de um fuso horário para outro. Os fusos são identificados pelo nome do Windows (por exemplo, E. South America Standard Time para Brasília), não pelo nome usado em outras linguagens (America/Sao_Paulo).
Sintaxe
convertTimeZone(data, fusoOrigem, fusoDestino, [formato])
Exemplos testados
| Expressão | Resultado |
|---|---|
convertTimeZone('2026-11-02T11:30:00Z', 'UTC', 'E. South America Standard Time', 'dd/MM/yyyy HH:mm') | 02/11/2026 08:30 |
convertTimeZone('2026-07-15T12:00:00Z', 'UTC', 'E. South America Standard Time', 'HH:mm')Brasília, UTC-3 | 09:00 |
convertTimeZone('2026-07-15T12:00:00Z', 'UTC', 'Eastern Standard Time', 'HH:mm')Nova York em julho (horário de verão) | 08:00 |
convertTimeZone('2026-01-15T12:00:00Z', 'UTC', 'Eastern Standard Time', 'HH:mm')Nova York em janeiro | 07:00 |
convertTimeZone('2026-07-15T12:00:00Z', 'UTC', 'GMT Standard Time', 'HH:mm')Londres em julho | 13:00 |
convertTimeZone('2026-07-15T12:00:00Z', 'UTC', 'India Standard Time', 'HH:mm') | 17:30 |
convertTimeZone('2026-07-15T12:00:00Z', 'UTC', 'SA Western Standard Time', 'HH:mm')Manaus, UTC-4 | 08:00 |
convertTimeZone('2026-07-15T12:00:00Z', 'UTC', 'E. South America Standard Time')sem formato: ISO sem o Z | 2026-07-15T09:00:00.0000000 |
Quando usar
Use convertTimeZone quando o fluxo precisa mostrar ou comparar horários no fuso de pessoas: avisos com horário de reunião, prazos no horário de Brasília, relatórios para equipes em outros países. Guarde sempre o instante original em UTC (é o que utcNow() e a maioria dos conectores devolvem) e converta só na hora de exibir. Assim, uma mudança de horário de verão ou uma equipe em outro país não obriga a reescrever o fluxo. Para um prazo "até as 18:00 de Brasília", converta o horário atual para Brasília e compare com 18:00, em vez de somar ou subtrair três horas na mão.
Armadilhas
- Nome do Windows, não o da IANA. Um nome errado dá erro na execução.
- O resultado sem formato não traz o Z:
2026-07-15T09:00:00.0000000já é horário de Brasília, e não UTC. Não o reconverta como se fosse UTC. - O horário de verão é respeitado: Nova York está 1 hora mais perto de Brasília em julho do que em janeiro. Converta sempre com a data real.
- O Brasil tem 4 fusos (Brasília, Manaus/Cuiabá, Rio Branco), com nomes diferentes: veja o conversor abaixo.
Perguntas frequentes
Qual o nome do fuso de Brasília?
E. South America Standard Time. Fortaleza usa SA Eastern Standard Time, Salvador Bahia Standard Time, Manaus SA Western Standard Time, Cuiabá Central Brazilian Standard Time e Rio Branco SA Pacific Standard Time.
Posso usar addHours(utcNow(), -3)?
Funciona em Brasília porque não há horário de verão desde 2019, mas quebra para fusos que mudam. Prefira convertTimeZone.