Cadeias de caracteres de formato de data e hora padrão

Uma cadeia de caracteres de formato de data e hora padrão usa um único caractere como especificador de formato para definir a representação de texto de um valor de data e hora. Qualquer cadeia de caracteres de formato de data e hora que contenha mais de um caractere, incluindo espaço em branco, é interpretada como uma cadeia de caracteres de formato de data e hora personalizada. Uma cadeia de caracteres de formato padrão ou personalizado pode ser usada para definir a representação de texto que resulta de uma operação de formatação.

Tabela de especificadores de formato

A tabela a seguir descreve os especificadores de formato de data e hora padrão.

Como funcionam as cadeias de caracteres de formato padrão

Em uma operação de formatação, uma cadeia de caracteres de formato padrão é simplesmente um alias para uma cadeia de caracteres de formato personalizado. A vantagem de usar um alias para se referir a uma cadeia de caracteres de formato personalizado é que, embora o alias permaneça invariante, a própria cadeia de caracteres de formato personalizado pode variar. Isso é importante porque as representações de cadeia de caracteres de valores de data e hora normalmente variam de acordo com a cultura. Por exemplo, a cadeia de caracteres de formato padrão "d" indica que um valor de data e hora deve ser exibido usando um padrão de data curto. Para a cultura invariante, este padrão é "MM/dd/aaaa". Para a cultura fr-FR, é "dd/MM/aaaa". Para a cultura ja-JP, é "yyyy/MM/dd".

Se uma cadeia de caracteres de formato padrão em uma operação de formatação for mapeada para a cadeia de caracteres de formato personalizado de uma cultura específica, seu aplicativo poderá definir a cultura específica cujas cadeias de caracteres de formato personalizado serão usadas de uma destas maneiras:

• Você pode usar a cultura padrão (ou atual). O exemplo a seguir exibe uma data usando o formato de data abreviada da cultura atual. Neste caso, a cultura atual é en-US.

  let
      Source =
      {
          Date.ToText(#date(2024, 3, 15), [Format = "d"])
          //Displays 3/15/2024
      }
  in
      Source
  

• Você pode passar uma cultura usada para formatar a data de acordo com as regras dessa cultura específica. O exemplo a seguir exibe uma data usando o formato de data abreviada da cultura pt-BR.

  let
      Source =
      {
          Date.ToText(#date(2024, 3, 15), [Format = "d", Culture = "pt-BR"])
          //Displays 15/03/2024
     }
  in
      Source
  

Em alguns casos, a cadeia de caracteres de formato padrão serve como uma abreviação conveniente para uma cadeia de caracteres de formato personalizado mais longa que é invariante. Quatro cadeias de caracteres de formato padrão se enquadram nesta categoria: "O" (ou "o"), "R" (ou "r"), "s" e "u". Essas cadeias de caracteres correspondem a cadeias de caracteres de formato personalizado definidas pela cultura invariante. Eles produzem representações de cadeia de caracteres de valores de data e hora que se destinam a ser idênticos entre culturas. A tabela a seguir fornece informações sobre essas quatro cadeias de caracteres de formato de data e hora padrão.

Cadeias de caracteres de formato padrão também podem ser usadas em operações de análise, que exigem uma cadeia de caracteres de entrada para estar exatamente em conformidade com um padrão específico para que a operação de análise seja bem-sucedida. Muitas cadeias de caracteres de formato padrão são mapeadas para várias cadeias de caracteres de formato personalizado, de modo que um valor de data e hora pode ser representado em uma variedade de formatos e a operação de análise ainda é bem-sucedida.

As seções a seguir descrevem os especificadores de formato padrão para os valores Date, DateTime, DateTimeZone e Time .

Formatos de data

Este grupo inclui os seguintes formatos:

• O especificador de formato de data curta ("d")
• O especificador de formato de data longa ("D")

O especificador de formato de data curta ("d")

O especificador de formato padrão "d" representa um formato de data personalizado definido por uma cultura específica. Por exemplo, o texto de formato personalizado retornado pela cultura invariante é "MM/dd/aaaa".

O exemplo a seguir usa o especificador de formato "d" para exibir um valor de data.

let
    Source =
    {
        Date.ToText(#date(2024, 4, 10), [Format = "d", Culture = ""]),
        // Displays 04/10/2024

        Date.ToText(#date(2024, 4, 10), [Format = "d", Culture = "en-US"]),
        // Displays 4/10/2024

        Date.ToText(#date(2024, 4, 10), [Format = "d", Culture = "en-NZ"]),
        // Displays 10/4/2024

        Date.ToText(#date(2024, 4, 10), [Format = "d", Culture = "de-DE"])
        // Displays 10.4.2024
    }
in
    Source

Voltar à mesa

O especificador de formato de data longa ("D")

O especificador de formato padrão "D" representa um formato de data personalizado definido por uma cultura específica. Por exemplo, a cadeia de caracteres de formato personalizado para a cultura invariante é "dddd, dd MMMM aa".

O exemplo a seguir usa o especificador de formato "D" para exibir um valor de data e hora.

let
    Source =
    {
        Date.ToText(#date(2024, 4, 10), [Format = "D", Culture = ""]),
        // Displays Wednesday, 10 April, 2024

        Date.ToText(#date(2024, 4, 10), [Format = "D", Culture = "en-US"]),
        // Displays Wednesday, April 10, 2024

        Date.ToText(#date(2024, 4, 10), [Format = "D", Culture = "pt-BR"]),
        // Displays quarta-feira, 10 de abril de 2024

        Date.ToText(#date(2024, 4, 10), [Format = "D", Culture = "es-MX"])
        // Displays miércoles, 10 de abril de 2024
    }
in
    Source

Voltar à mesa

Formatos de data e hora

Este grupo inclui os seguintes formatos:

• O especificador de formato de data completa e hora curta ("f")
• O especificador de formato de data longa ("F") completo
• O especificador de formato de data abreviada (g) geral
• O especificador de formato de data longa ("G") geral
• O especificador de formato de ida e volta ("O", "o")
• O especificador de formato RFC1123 ("R", "r")
• O especificador de formato classificável ("s")
• O especificador de formato universal classificável ("u")

O especificador de formato de data completa e hora curta ("f")

O especificador de formato padrão "f" representa uma combinação dos padrões de data longa ("D") e tempo curto ("t"), separados por um espaço.

A cadeia de caracteres de resultado é afetada pelas informações de formatação de uma cultura específica.

O exemplo a seguir usa o especificador de formato "f" para exibir um valor de data e hora.

let
    Source =
    {
        DateTime.ToText(#datetime(2024, 4, 10, 6, 30, 0), [Format = "f", Culture = "en-US"]),
        // Displays Wednesday, April 10, 2024 6:30 AM

        DateTime.ToText(#datetime(2024, 4, 10, 6, 30, 0), [Format = "f", Culture = "fr-FR"])
        // Displays mercredi 10 avril 2024 06:30
    }
in
    Source

Voltar à mesa

O especificador de formato de data longa ("F") completo

O especificador de formato padrão "F" representa um formato de data e hora personalizado definido por uma cultura específica. Por exemplo, a cadeia de caracteres de formato personalizado para a cultura invariante é "dddd, dd MMMM aaaa HH:mm:ss".

A cadeia de caracteres de resultado é afetada pelas informações de formatação de uma cultura específica.

O exemplo a seguir usa o especificador de formato "F" para exibir um valor de data e hora.

let
    Source =
    {
        DateTime.ToText(#datetime(2024, 4, 10, 6, 30, 0), [Format = "F", Culture = ""]),
        // Displays Wednesday, 10 April, 2024 06:30:00

        DateTime.ToText(#datetime(2024, 4, 10, 6, 30, 0), [Format = "F", Culture = "en-US"]),
        // Displays Wednesday, April 10, 2024 6:30:00 AM

        DateTime.ToText(#datetime(2024, 4, 10, 6, 30, 0), [Format = "F", Culture = "fr-FR"])
        // Displays mercredi 10 avril 2024 06:30:00
    }
in
    Source

Voltar à mesa

O especificador de formato de data abreviada (g) geral

O especificador de formato padrão "g" representa uma combinação dos padrões de data curta ("d") e tempo curto ("t"), separados por um espaço. O texto resultante é afetado pelas informações de formatação de uma cultura específica.

A cadeia de caracteres de resultado é afetada pelas informações de formatação de uma cultura específica.

O exemplo a seguir usa o especificador de formato "g" para exibir um valor de data e hora.

let
    Source =
    {
        DateTime.ToText(#datetime(2024, 4, 10, 6, 30, 0), [Format = "g", Culture = ""]),
        // Displays 04/10/2024 06:30

        DateTime.ToText(#datetime(2024, 4, 10, 6, 30, 0), [Format = "g", Culture = "en-US"]),
        // Displays 4/10/2024 6:30 AM

        DateTime.ToText(#datetime(2024, 4, 10, 6, 30, 0), [Format = "g", Culture = "fr-BE"])
        // Displays 10-04-24 06:30
    }
in
    Source

Voltar à mesa

O especificador de formato de data longa ("G") geral

O especificador de formato padrão "G" representa uma combinação dos padrões de data curta ("d") e tempo longo ("T"), separados por um espaço. O texto resultante é afetado pelas informações de formatação de uma cultura específica.

A cadeia de caracteres de resultado é afetada pelas informações de formatação de uma cultura específica.

O exemplo a seguir usa o especificador de formato "G" para exibir um valor de data e hora.

let
    Source =
    {
        DateTime.ToText(#datetime(2024, 4, 10, 6, 30, 0), [Format = "G", Culture = ""]),
        // Displays 04/10/2024 06:30:00

        DateTime.ToText(#datetime(2024, 4, 10, 6, 30, 0), [Format = "G", Culture = "en-US"]),
        // Displays 4/10/2024 6:30:00 AM

        DateTime.ToText(#datetime(2024, 4, 10, 6, 30, 0), [Format = "G", Culture = "nl-BE"])
        // Displays 10/04/2024 6:30:00
    }
in
    Source

Voltar à mesa

O especificador de formato de ida e volta ("O", "o")

O especificador de formato padrão "O" ou "o" representa uma cadeia de caracteres de formato de data e hora personalizada usando um padrão que preserva as informações de fuso horário e emite uma cadeia de caracteres de resultado que está em conformidade com a ISO 8601. Para valores DateTimeZone , esse especificador de formato foi projetado para preservar valores de data, hora e fuso horário no texto.

O especificador de formato padrão "O" ou "o" corresponde ao "aaaa'-'MM'-'dd'T'HH':'mm':'ss'.' fffffffxxx" cadeia de caracteres de formato personalizado para valores DateTimeZone . Neste texto, os pares de aspas simples que delimitam caracteres individuais, como o hífenes, os dois pontos e a letra "T", indicam que o caractere individual é um literal que não pode ser alterado. Os apóstrofos não aparecem na cadeia de caracteres de saída.

O especificador de formato padrão "O" ou "o" (e o "aaaa'-'MM'-'dd'T'HH':'mm':'ss'.' fffffffxxx" custom format) aproveita as maneiras como a ISO 8601 representa as informações de fuso horário para preservar os valores de DateTimeZone:

• O componente de fuso horário de DateTimeZone.ToLocal valores de data e hora é um deslocamento do UTC (por exemplo, +01:00, -07:00).

• O componente de fuso horário de DateTimeZone.ToUtc valores de data e hora usa +00.00 para representar UTC.

Como o especificador de formato padrão "O" ou "o" está em conformidade com um padrão internacional, a operação de formatação ou análise que usa o especificador sempre usa a cultura invariante e o calendário gregoriano.

O exemplo a seguir usa o especificador de formato "o" para exibir uma série de valores DateTimeZone em um sistema no fuso horário do Pacífico dos EUA.

let
    date1 = #datetimezone(2024, 6, 15, 13, 45, 30, 0, 0),
    Source =
    {
        Text.Format("#{0} (Unspecified) --> #{1}", {date1, DateTimeZone.ToText(date1, [Format = "O"])}),
        Text.Format("#{0} (Utc) --> #{1}", {date1, DateTimeZone.ToText(DateTimeZone.ToUtc(date1), [Format = "O"])}),
        Text.Format("#{0} (Local) --> #{1}", {date1, DateTimeZone.ToText(DateTimeZone.ToLocal(date1), [Format = "O"])})
    }
in
    Source

// The example displays the following output:
//    6/15/2024 1:45:30 PM +00:00 (Unspecified) --> 2024-06-15T13:45:30.0000000+00:00
//    6/15/2024 1:45:30 PM +00:00 (Utc) --> 2024-06-15T13:45:30.0000000+00:00
//    6/15/2024 1:45:30 PM +00:00 (Local) --> 2024-06-15T08:45:30.0000000-07:00

O exemplo a seguir usa o especificador de formato "o" para criar uma cadeia de caracteres formatada e, em seguida, restaura o valor de data e hora original chamando uma rotina de análise de data e hora.

let
    // Round-trip a local time
    #"Origin Local Date" = DateTimeZone.ToLocal(
        #datetimezone(2024, 4, 10, 6, 30, 0, 0, 0)
    ),
    #"Local Date Text" = DateTimeZone.ToText(
        #"Origin Local Date", [Format = "o"]
    ),
    #"New Local Date" = DateTimeZone.FromText(#"Local Date Text"),
    #"Local Round Trip" = Text.Format(
        "Round-tripped #{0} Local to #{1} Local.", 
        {
            DateTimeZone.ToText(#"Origin Local Date"), 
            DateTimeZone.ToText(#"New Local Date")
        }
    ),

    // Round-trip a UTC time
    #"Origin UTC Date" = DateTimeZone.ToUtc(
        #datetimezone(2024, 4, 12, 9, 30, 0, 0, 0)
    ),
    #"UTC Date Text" = DateTimeZone.ToText(
        #"Origin UTC Date", [Format = "o"]
    ),
    #"New UTC Date" = DateTimeZone.FromText(#"UTC Date Text"),
    #"UTC Round Trip" = Text.Format(
        "Round-tripped #{0} UTC to #{1} UTC.", 
        {
            DateTimeZone.ToText(#"Origin UTC Date"), 
            DateTimeZone.ToText(#"New UTC Date")
        }
    ),

    // Round-trip an 18 hour offset time
    #"Origin Offset Date" = DateTimeZone.ToLocal(
        #datetimezone(2024, 4, 10, 6, 30, 0, 0, 0) + #duration(0, 18, 0, 0)
    ),
    #"Offset Date Text" = DateTimeZone.ToText(
        #"Origin Offset Date", [Format = "o"]
    ),
    #"New Offset Date" = DateTimeZone.FromText(#"Offset Date Text"),
    #"Offset Round Trip" = Text.Format(
        "Round-tripped #{0} to #{1}.", 
        {
            DateTimeZone.ToText(#"Origin Offset Date"), 
            DateTimeZone.ToText(#"New Offset Date")
        }
    ),

    #"Round Trip Results" = 
        {#"Local Round Trip", #"UTC Round Trip", #"Offset Round Trip"}
in
    #"Round Trip Results"

// The example displays the following output in Power Query Desktop:
//    Round-tripped 4/9/2024 11:30:00 PM -07:00 Local to 4/9/2024 11:30:00 PM -07:00 Local.
//    Round-tripped 4/12/2024 9:30:00 AM +00:00 UTC to 4/12/2024 9:30:00 AM +00:00 UTC.
//    Round-tripped 4/10/2024 5:30:00 PM -07:00 to 4/10/2024 5:30:00 PM -07:00.

// The example displays the following output in Power Query Online:
//    Round-tripped 4/10/2024 6:30:00 AM +00:00 Local to 4/10/2024 6:30:00 AM +00:00 Local.
//    Round-tripped 4/12/2024 9:30:00 AM +00:00 UTC to 4/12/2024 9:30:00 AM +00:00 UTC.
//    Round-tripped 4/11/2024 12:30:00 AM +00:00 to 4/11/2024 12:30:00 AM +00:00.

Voltar à mesa

O especificador de formato RFC1123 ("R", "r")

O especificador de formato padrão "R" ou "r" representa uma cadeia de caracteres de formato de data e hora personalizada que não é definida por uma cultura específica. É sempre o mesmo, independentemente da cultura utilizada ou do fornecedor de formato fornecido. A string de formato personalizado é "ddd, dd MMM aaaa HH':'mm':'ss 'GMT'". Quando esse especificador de formato padrão é usado, a operação de formatação ou análise sempre usa a cultura invariante.

Embora o padrão RFC 1123 expresse uma hora como Tempo Universal Coordenado (UTC), a operação de formatação não modifica o valor da data e hora que está sendo formatada. Portanto, você deve converter o valor DateTime para UTC chamando o método de função DateTimeZone.ToUtc antes de executar a operação de formatação.

O exemplo a seguir usa o especificador de formato "r" para exibir um valor de hora e data em um sistema no fuso horário do Pacífico dos EUA (sete horas atrás do UTC).

let
    date1 = #datetimezone(2024, 4, 10, 6, 30, 0, -7, 0),
    dateOffset = DateTimeZone.ToUtc(date1),
    Source = 
    {
        DateTimeZone.ToText(date1, [Format = "r"]),
        // Displays Wed, 10 Apr 2024 13:30:00 GMT

        DateTimeZone.ToText(dateOffset, [Format = "r"])
        // Displays Wed, 10 Apr 2024 13:30:00 GMT
    }
in
    Source

Voltar à mesa

O especificador de formato classificável ("s")

O especificador de formato padrão "s" representa uma cadeia de caracteres de formato de data e hora personalizada que reflete um padrão definido (ISO 8601) e é somente leitura. Portanto, é sempre o mesmo, independentemente da cultura usada ou do provedor de formato fornecido. A cadeia de caracteres de formato personalizado é "aaaa'-'MM'-'dd'T'HH':'mm':'ss". O objetivo do especificador de formato "s" é produzir cadeias de resultados que classificam consistentemente em ordem crescente ou decrescente com base em valores de data e hora.

Quando esse especificador de formato padrão é usado, a operação de formatação ou análise sempre usa a cultura invariante.

O exemplo a seguir usa o especificador de formato "s" para exibir um valor de data e hora em um sistema no fuso horário do Pacífico dos EUA.

let
    Source =
    {
        DateTime.ToText(#datetime(2024, 4, 10, 6, 30, 0), [Format = "s", Culture = "en-US"])
        // Displays 2024-04-10T06:30:00
    }
in
    Source

Voltar à mesa

O especificador de formato universal classificável ("u")

O especificador de formato padrão "u" representa uma cadeia de caracteres de formato de data e hora personalizada que é sempre a mesma, independentemente da cultura usada ou do provedor de formato fornecido. A cadeia de caracteres de formato personalizado é "aaaa'-'MM'-'dd HH':'mm':'ss'Z'". O padrão reflete um padrão definido e a propriedade é somente leitura. Quando esse especificador de formato padrão é usado, a operação de formatação ou análise sempre usa a cultura invariante.

Embora a cadeia de caracteres de resultado deva expressar uma hora como Tempo Universal Coordenado (UTC), nenhuma conversão do valor DateTimeZone original é executada durante a operação de formatação. Portanto, você deve converter um valor de DateTimeZone para UTC chamando a função DateTimeZone.ToUtc antes de formatá-la.

O exemplo a seguir usa o especificador de formato "u" para exibir um valor de data e hora.

let
    date1 = #datetimezone(2024, 4, 10, 6, 30, 0, -7, 0),
    dateOffset = DateTimeZone.ToUtc(date1),
    Source =
    {
        DateTimeZone.ToText(dateOffset, [Format = "u"]),
        // Displays 2024-04-10 13:30:00Z
    }
in
    Source

Voltar à mesa

Formatos de hora

Este grupo inclui os seguintes formatos:

• O especificador de formato de tempo curto ("t")
• O especificador de formato de longa duração ("T")

O especificador de formato de tempo curto ("t")

O especificador de formato padrão "t" representa uma cadeia de caracteres de formato de data e hora personalizada que é definida pela cultura especificada. Por exemplo, a cadeia de caracteres de formato personalizado para a cultura invariante é "HH:mm".

A cadeia de caracteres de resultado é afetada pelas informações de formatação de uma cultura específica.

O exemplo a seguir usa o especificador de formato "t" para exibir um valor de data e hora.

let
    Source =
    {
        DateTime.ToText(#datetime(2024, 4, 10, 6, 30, 0), [Format = "t", Culture = ""]),
        // Displays 06:30
        
        DateTime.ToText(#datetime(2024, 4, 10, 6, 30, 0), [Format = "t", Culture = "en-US"]),
        // Displays 6:30 AM

        DateTime.ToText(#datetime(2024, 4, 10, 6, 30, 0), [Format = "t", Culture = "es-ES"])
        // Displays 6:30
    }
in
    Source

Voltar à mesa

O especificador de formato de longa duração ("T")

O especificador de formato padrão "T" representa uma cadeia de caracteres de formato de data e hora personalizada que é definida pela cultura específica. Por exemplo, a cadeia de caracteres de formato personalizado para a cultura invariante é "HH:mm:ss".

O exemplo a seguir usa o especificador de formato "T" para exibir um valor de data e hora.

let
    Source =
    {
        DateTime.ToText(#datetime(2024, 4, 10, 6, 30, 0), [Format = "T", Culture = ""]),
        // Displays 06:30:00
        
        DateTime.ToText(#datetime(2024, 4, 10, 6, 30, 0), [Format = "T", Culture = "en-US"]),
        // Displays 6:30:00 AM

        DateTime.ToText(#datetime(2024, 4, 10, 6, 30, 0), [Format = "T", Culture = "es-ES"])
        // Displays 6:30:00
    }
in
    Source

Voltar à mesa

Formatos parciais de data

Este grupo inclui os seguintes formatos:

• O especificador de formato do mês ("M", "m")
• O especificador de formato do mês do ano ("Y", "y")

O especificador de formato do mês ("M", "m")

O especificador de formato padrão "M" ou "m" representa uma cadeia de caracteres de formato de data e hora personalizada que é definida pela cultura específica. Por exemplo, a cadeia de caracteres de formato personalizado para a cultura invariante é "MMMM dd".

O exemplo a seguir usa o especificador de formato "m" para exibir um valor de data e hora.

let
    Source =
    {
        DateTime.ToText(#datetime(2024, 4, 10, 6, 30, 0), [Format = "m", Culture = ""]),
        // Displays April 10
        
        DateTime.ToText(#datetime(2024, 4, 10, 6, 30, 0), [Format = "m", Culture = "en-US"]),
        // Displays April 10

        DateTime.ToText(#datetime(2024, 4, 10, 6, 30, 0), [Format = "m", Culture = "ms-MY"])
        // Displays 10 April
    }
in
    Source

Voltar à mesa

O especificador de formato do mês do ano ("Y", "y")

O especificador de formato padrão "Y" ou "y" representa uma cadeia de caracteres de formato de data personalizada que é definida por uma cultura específica. Por exemplo, a cadeia de caracteres de formato personalizado para a cultura invariante é "MMMM aaaa".

O exemplo a seguir usa o especificador de formato "y" para exibir um valor de data e hora.

let
    Source =
    {
        DateTime.ToText(#datetime(2024, 4, 10, 6, 30, 0), [Format = "Y", Culture = ""]),
        // Displays 2024 April
        
        DateTime.ToText(#datetime(2024, 4, 10, 6, 30, 0), [Format = "Y", Culture = "en-US"]),
        // Displays April 2024

        DateTime.ToText(#datetime(2024, 4, 10, 6, 30, 0), [Format = "y", Culture = "af-ZA"])
        // Displays April 2024
    }
in
    Source

Voltar à mesa

Conteúdos relacionados

• Como a cultura afeta a formatação do texto
• Conversão do tipo Date, Time, DateTime e DateTimeZone
• Funções de data
• Funções DateTime
• Funções DateTimeZone
• Funções de tempo
• Cadeias de Formato de Data e Hora Personalizadas