Blocos de Texto em Java: Literais de String Multilinha

Um bloco de texto é um literal de string multilinha que elimina a confusão de newlines escapados e concatenações. Introduzido como prévia no Java 13 e tornado permanente no Java 15, ele permite colar HTML, JSON, SQL ou qualquer bloco de texto formatado diretamente no seu código-fonte, tornando-o legível como o original.

Antes dos blocos de texto, algumas linhas de marcação embutida resultavam em uma parede de escapes \n e operadores +. Um bloco de texto abre com três aspas duplas (""") seguidas de uma quebra de linha, e tudo até o fechamento """ torna-se a string — com o espaço em branco inicial tratado de forma inteligente.

A Sintaxe das Aspas Triplas

Um bloco de texto começa com """ e um terminador de linha. O conteúdo começa na linha seguinte; o delimitador de abertura não pode compartilhar uma linha com texto. O bloco termina com outro """.

// Old way: escapes and concatenation
String json = "{\n" +
              "  \"name\": \"Ada\"\n" +
              "}";

// Text block: paste it as-is
String block = """
    {
      "name": "Ada"
    }
    """;

Aviso

O erro de compilação mais comum é escrever conteúdo na linha de abertura, por exemplo String s = """{. O """ de abertura deve ser seguido imediatamente por um terminador de linha — apenas o """ de fechamento pode compartilhar sua linha com texto.

Os dois produzem strings quase idênticas, mas o bloco de texto é legível à primeira vista e as aspas duplas embutidas não precisam de escape. Um bloco de texto é uma String como qualquer outra — não há tipo separado — portanto, todos os métodos de String funcionam nele, e um bloco de texto ainda é imutável após a criação.

Espaço em Branco Incidental vs. Essencial

O compilador distingue o espaço em branco incidental (recuo adicionado apenas para manter o código-fonte organizado) do espaço em branco essencial (recuo que você realmente deseja no valor). Ele encontra a linha com o menor espaço em branco inicial — incluindo a linha do """ de fechamento — e remove essa quantidade comum de cada linha.

String html = """
        <p>Hi</p>
    """;
// The closing """ is indented 4 spaces, the <p> 8 spaces.
// Common minimum is 4, so the result keeps 4 leading spaces: "    <p>Hi</p>\n"

Mover o delimitador de fechamento altera a quantidade removida. Colocar """ na extremidade esquerda não remove nenhuma indentação; colocá-lo abaixo da linha mais profunda remove toda ela. Isso lhe dá controle preciso sem contar espaços manualmente.

Escapes e a Newline Final

Blocos de texto suportam as sequências de escape usuais, além de duas que existem somente para eles:

Escape	Efeito
`\n`, `\t`, `\"`	Escapes padrão, ainda válidos
`\` (final de linha)	Continuação de linha — suprime a newline que seguiria
`\s`	Um único espaço que nunca é removido como espaço em branco incidental

Um bloco de texto cujo conteúdo termina em sua própria linha inclui uma newline final; colocar o """ de fechamento na mesma linha que o último texto a omite.

String withNewline = """
    last line
    """;          // ends with "\n"

String noNewline = """
    last line""";  // no trailing newline

Casos de Uso Comuns

Blocos de texto se destacam sempre que texto formatado e multilinha aparece no código:

// SQL kept readable instead of one long escaped string
String query = """
    SELECT id, name, price
    FROM products
    WHERE price < ?
    ORDER BY name
    """;

// JSON payload with quotes that need no escaping
String payload = """
    {
      "user": "ada",
      "roles": ["admin", "editor"]
    }
    """;

Como o texto espelha sua forma final, copiar e colar um trecho de um arquivo .sql ou .json funciona imediatamente, e os revisores podem detectar erros de formatação de imediato.

Blocos de Texto em Ação

O exemplo abaixo exercita cada recurso: remoção de espaço em branco incidental, formatted() para marcadores de posição, o stream lines(), os escapes \s e \ no final de linha, indentação controlada pelo delimitador e aspas duplas embutidas sem escape. Leia os comentários — cada linha corresponde a uma regra acima.

java— editable, runs on the server

public class TextBlockDemo {
    public static void main(String[] args) {
        // A text block: opening """ must be followed by a line terminator.
        String html = """
            <html>
                <body>
                    <p>Hello, %s!</p>
                </body>
            </html>
            """;

// Incidental indentation is stripped relative to the closing """.
        System.out.println("--- raw text block ---");
        System.out.print(html);

// Text blocks are just String instances; all String methods apply.
        String formatted = html.formatted("World");
        System.out.println("--- formatted ---");
        System.out.print(formatted);

// The line count proves the trailing newline from the closing line.
        long lines = html.lines().count();
        System.out.println("Line count: " + lines);

// \ at end of line suppresses the newline (line continuation).
        String oneLine = """
            Roses are red, \
            violets are blue.""";
        System.out.println("Continuation: " + oneLine);

// \s is a space escape that preserves trailing whitespace.
        String padded = """
            ends here:\s
            next line""";
        System.out.println("Has trailing space: "
            + (padded.split("\n")[0].endsWith(" ")));

// Closing delimiter position controls how much indent is removed.
        String indented = """
                kept
              base""";
        System.out.println("--- indentation control ---");
        System.out.println(indented);

// No special escaping needed for embedded double quotes.
        String json = """
            {"name": "Ada", "active": true}""";
        System.out.println("JSON: " + json);
    }
}

O que observar na execução:

O bloco bruto imprime <html> alinhado à margem esquerda mesmo que estivesse recuado no fonte, pois o espaço em branco incidental comum foi removido em relação ao """ de fechamento.
formatted("World") substitui o marcador %s, provando que um bloco de texto é uma String comum que pode ser passada para métodos de formatação.
Line count: 5 vem de html.lines() percorrendo as cinco linhas de conteúdo; a newline final adicionada pelo """ de fechamento em sua própria linha termina a última linha em vez de criar uma sexta vazia.
Has trailing space: true mostra que \s forçou um espaço a sobreviver que o compilador teria removido como incidental.
Continuation: Roses are red, violets are blue. prova que um \ no final de linha uniu as duas linhas do fonte em uma, e {"name": "Ada", "active": true} foi impresso sem uma única aspa escapada.

Prática

Em um bloco de texto Java, o que determina quanto espaço em branco inicial é removido de cada linha?

A linha com menos recuo, incluindo a linha das aspas triplas de fechamentoSempre exatamente quatro espaços, independentemente de como o bloco está recuadoO recuo do delimitador de aspas triplas de aberturaNada é removido; blocos de texto preservam todo o espaço em branco literalmente