Tipos de template literal

Tipos de template literal são construídos sobre tipos de string literal e têm a capacidade de se expandir em muitas strings por meio de uniões.

Eles têm a mesma sintaxe dos template literals de strings em JavaScript, mas são usados em posições de tipo. Quando usado com tipos literais concretos, um template literal produz um novo tipo de string literal, concatenando o conteúdo.

ts
type World = "world";
 
type Greeting = `hello ${World}`;
type Greeting = "hello world"
Try

Quando uma união é usada na posição interpolada, o tipo é o conjunto de todos os string literals possíveis que cada membro da união pode representar:

ts
type EmailLocaleIDs = "welcome_email" | "email_heading";
type FooterLocaleIDs = "footer_title" | "footer_sendoff";
 
type AllLocaleIDs = `${EmailLocaleIDs | FooterLocaleIDs}_id`;
type AllLocaleIDs = "welcome_email_id" | "email_heading_id" | "footer_title_id" | "footer_sendoff_id"
Try

Para cada posição interpolada no template literal, as uniões são multiplicadas em produto cartesiano:

ts
type AllLocaleIDs = `${EmailLocaleIDs | FooterLocaleIDs}_id`;
type Lang = "en" | "ja" | "pt";
 
type LocaleMessageIDs = `${Lang}_${AllLocaleIDs}`;
type LocaleMessageIDs = "en_welcome_email_id" | "en_email_heading_id" | "en_footer_title_id" | "en_footer_sendoff_id" | "ja_welcome_email_id" | "ja_email_heading_id" | "ja_footer_title_id" | "ja_footer_sendoff_id" | "pt_welcome_email_id" | "pt_email_heading_id" | "pt_footer_title_id" | "pt_footer_sendoff_id"
Try

Em geral, recomendamos gerar com antecedência as uniões de strings grandes, mas isso é útil em casos menores.

Uniões de strings em tipos

O poder dos template literals aparece quando você define uma nova string com base em informações dentro de um tipo.

Considere o caso em que uma função (makeWatchedObject) adiciona uma nova função chamada on() a um objeto passado para ela. Em JavaScript, a chamada poderia ser assim: makeWatchedObject(baseObject). Podemos imaginar que o objeto base seja assim:

ts
const passedObject = {
firstName: "Saoirse",
lastName: "Ronan",
age: 26,
};
Try

A função on que será adicionada ao objeto base espera dois argumentos: um eventName (uma string) e um callback (uma function).

O eventName deve ter a forma propriedadeDoObjetoPassado + "Changed"; assim, firstNameChanged é derivado da propriedade firstName do objeto base.

A função callback, quando chamada:

  • Deve receber um valor do tipo associado ao nome propriedadeDoObjetoPassado; assim, como firstName é tipada como string, o callback do evento firstNameChanged espera receber uma string no momento da chamada. Da mesma forma, eventos associados a age devem esperar ser chamados com um argumento number
  • Deve ter tipo de retorno void (por simplicidade da demonstração)

A assinatura ingênua da função on() poderia então ser: on(eventName: string, callback: (newValue: any) => void). No entanto, na descrição anterior, identificamos restrições de tipo importantes que gostaríamos de documentar no nosso código. Tipos de template literal nos permitem trazer essas restrições para o código.

ts
const person = makeWatchedObject({
firstName: "Saoirse",
lastName: "Ronan",
age: 26,
});
 
// makeWatchedObject has added `on` to the anonymous Object
 
person.on("firstNameChanged", (newValue) => {
console.log(`firstName was changed to ${newValue}!`);
});
Try

Repare que on escuta o evento "firstNameChanged", e não apenas "firstName". Nossa especificação ingênua de on() poderia ser mais robusta se garantíssemos que o conjunto de nomes de evento elegíveis fosse restrito à união dos nomes de atributos do objeto observado com “Changed” no final. Embora estejamos à vontade para fazer esse cálculo em JavaScript, isto é, Object.keys(passedObject).map(x => `${x}Changed`), template literals dentro do sistema de tipos oferecem uma abordagem semelhante para manipulação de strings:

ts
type PropEventSource<Type> = {
on(eventName: `${string & keyof Type}Changed`, callback: (newValue: any) => void): void;
};
 
/// Create a "watched object" with an `on` method
/// so that you can watch for changes to properties.
declare function makeWatchedObject<Type>(obj: Type): Type & PropEventSource<Type>;
Try

Com isso, podemos construir algo que gera erro quando recebe a propriedade errada:

ts
const person = makeWatchedObject({
firstName: "Saoirse",
lastName: "Ronan",
age: 26
});
 
person.on("firstNameChanged", () => {});
 
// Prevent easy human error (using the key instead of the event name)
person.on("firstName", () => {});
Argument of type '"firstName"' is not assignable to parameter of type '"firstNameChanged" | "lastNameChanged" | "ageChanged"'.2345Argument of type '"firstName"' is not assignable to parameter of type '"firstNameChanged" | "lastNameChanged" | "ageChanged"'.
 
// It's typo-resistant
person.on("frstNameChanged", () => {});
Argument of type '"frstNameChanged"' is not assignable to parameter of type '"firstNameChanged" | "lastNameChanged" | "ageChanged"'.2345Argument of type '"frstNameChanged"' is not assignable to parameter of type '"firstNameChanged" | "lastNameChanged" | "ageChanged"'.
Try

Inferência com template literals

Repare que não aproveitamos todas as informações fornecidas no objeto original passado. Dada a mudança de um firstName (ou seja, um evento firstNameChanged), devemos esperar que o callback receba um argumento do tipo string. Da mesma forma, o callback para a mudança de age deve receber um argumento number. Estamos usando any de forma ingênua para tipar o argumento do callback. Mais uma vez, tipos de template literal tornam possível garantir que o tipo de dado de um atributo seja o mesmo tipo do primeiro argumento do callback desse atributo.

A ideia-chave que torna isso possível é: podemos usar uma função com um genérico de modo que:

  1. O literal usado no primeiro argumento seja capturado como um tipo literal
  2. Esse tipo literal possa ser validado como pertencente à união dos atributos válidos no genérico
  3. O tipo do atributo validado possa ser buscado na estrutura do genérico usando Indexed Access
  4. Essa informação de tipo então possa ser aplicada para garantir que o argumento da função callback seja do mesmo tipo
ts
type PropEventSource<Type> = {
on<Key extends string & keyof Type>
(eventName: `${Key}Changed`, callback: (newValue: Type[Key]) => void): void;
};
 
declare function makeWatchedObject<Type>(obj: Type): Type & PropEventSource<Type>;
 
const person = makeWatchedObject({
firstName: "Saoirse",
lastName: "Ronan",
age: 26
});
 
person.on("firstNameChanged", newName => {
(parameter) newName: string
console.log(`new name is ${newName.toUpperCase()}`);
});
 
person.on("ageChanged", newAge => {
(parameter) newAge: number
if (newAge < 0) {
console.warn("warning! negative age");
}
})
Try

Aqui transformamos on em um método genérico.

Quando o usuário chama com a string "firstNameChanged", o TypeScript tenta inferir o tipo certo para Key. Para isso, ele compara Key com o conteúdo antes de "Changed" e infere a string "firstName". Depois que o TypeScript descobre isso, o método on pode buscar o tipo de firstName no objeto original, que neste caso é string. Da mesma forma, quando chamado com "ageChanged", o TypeScript encontra o tipo da propriedade age, que é number.

A inferência pode ser combinada de diferentes maneiras, muitas vezes para desconstruir strings e reconstruí-las de outras formas.

Tipos intrínsecos de manipulação de strings

Para ajudar na manipulação de strings, o TypeScript inclui um conjunto de tipos que podem ser usados nessa tarefa. Esses tipos vêm integrados ao compilador por questão de desempenho e não podem ser encontrados nos arquivos .d.ts incluídos com o TypeScript.

Uppercase<StringType>

Converte cada caractere da string para sua versão em maiúsculas.

Exemplo

ts
type Greeting = "Hello, world"
type ShoutyGreeting = Uppercase<Greeting>
type ShoutyGreeting = "HELLO, WORLD"
 
type ASCIICacheKey<Str extends string> = `ID-${Uppercase<Str>}`
type MainID = ASCIICacheKey<"my_app">
type MainID = "ID-MY_APP"
Try

Lowercase<StringType>

Converte cada caractere da string para o equivalente em minúsculas.

Exemplo

ts
type Greeting = "Hello, world"
type QuietGreeting = Lowercase<Greeting>
type QuietGreeting = "hello, world"
 
type ASCIICacheKey<Str extends string> = `id-${Lowercase<Str>}`
type MainID = ASCIICacheKey<"MY_APP">
type MainID = "id-my_app"
Try

Capitalize<StringType>

Converte o primeiro caractere da string para o equivalente em maiúsculas.

Exemplo

ts
type LowercaseGreeting = "hello, world";
type Greeting = Capitalize<LowercaseGreeting>;
type Greeting = "Hello, world"
Try

Uncapitalize<StringType>

Converte o primeiro caractere da string para o equivalente em minúsculas.

Exemplo

ts
type UppercaseGreeting = "HELLO WORLD";
type UncomfortableGreeting = Uncapitalize<UppercaseGreeting>;
type UncomfortableGreeting = "hELLO WORLD"
Try
Detalhes técnicos sobre os tipos intrínsecos de manipulação de strings

O código, a partir do TypeScript 4.1, dessas funções intrínsecas usa diretamente as funções de string do runtime JavaScript para a manipulação e não é sensível à localidade (locale).

function applyStringMapping(symbol: Symbol, str: string) {
    switch (intrinsicTypeKinds.get(symbol.escapedName as string)) {
        case IntrinsicTypeKind.Uppercase: return str.toUpperCase();
        case IntrinsicTypeKind.Lowercase: return str.toLowerCase();
        case IntrinsicTypeKind.Capitalize: return str.charAt(0).toUpperCase() + str.slice(1);
        case IntrinsicTypeKind.Uncapitalize: return str.charAt(0).toLowerCase() + str.slice(1);
    }
    return str;
}

The TypeScript docs are an open source project. Help us improve these pages by sending a Pull Request ❤

Contributors to this page:
SHSteven Harms  (6)
OTOrta Therox  (4)
SGHSteven G. Harms  (3)
UMDFUlisses, Mago do Flutter  (1)
Nnavya9singh  (1)
8+

Last updated: Nov 16, 2026