jQuery / Método / .text() - Ler ou substituir conteúdo de texto

No jQuery, .text() devolve uma string que combina o texto de todos os elementos selecionados e seus descendentes. .text(value) substitui o conteúdo de cada elemento por texto sem interpretar tags HTML. Para resultados separados, leia cada elemento em um array em vez de usar o getter combinado.

Escopo de leitura, html e val

A API .text() lê a seleção inteira, não apenas o primeiro elemento. Exclui marcação, inclui texto dos descendentes e não acrescenta separadores entre elementos. Não extrai somente o que aparece visível na tela.

.html() trata marcação e .val() valores atuais de entrada. Não leia o valor atual de input com .text(). O método funciona em documentos XML e HTML.

Comparar resultados combinados e individuais

Salve todo o código em UTF-8 como text-demo.html e abra no navegador. É preciso internet para carregar o arquivo oficial do jQuery 4.0.0 pela rede de distribuição de conteúdo, CDN, sem instalar pacotes. Leitura, escrita, prefixos por função, limpeza, Reset e exemplo do Console foram executados com 3.7.1 e 4.0.0.

O primeiro parágrafo contém Alpha e um span hidden com Hidden; o segundo contém Beta. JSON.stringify() mostra limites das strings e valores vazios. perItem lê cada elemento com .map() e .get() transforma em array comum.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Read and replace text contents</title>
  <script src="https://code.jquery.com/jquery-4.0.0.min.js"></script>
  <style>
    body { font: 16px/1.6 sans-serif; max-width: 760px; margin: 24px auto; padding: 16px; }
    button, input { font: inherit; margin: 4px; max-width: 100%; }
    .item { border: 2px solid teal; padding: 16px; }
    pre { white-space: pre-wrap; overflow-wrap: anywhere; }
  </style>
</head>
<body>
  <h1>Plain text from multiple elements</h1>
  <label>Value <input id="value" value="&lt;em&gt;Hello&lt;/em&gt;"></label>
  <button type="button" id="set">Set text</button>
  <button type="button" id="prefix">Prefix each item</button>
  <button type="button" id="clear">Clear text</button>
  <button type="button" id="read">Read</button>
  <button type="button" id="reset">Reset</button>
  <div id="items"><p class="item"><strong>Alpha</strong><span hidden>Hidden</span></p><p class="item">Beta</p></div>
  <pre id="result" aria-live="polite"></pre>
  <script>
    $(function () {
      const $items = $("#items > .item");
      const initial = $items.get().map(node => node.innerHTML);
      function report() {
        const combined = $items.text();
        const perItem = $items.map(function () { return $(this).text(); }).get();
        $("#result").text(`combined=${JSON.stringify(combined)}\nper item=${JSON.stringify(perItem)}\nitems=${$items.length}`);
      }
      $("#set").on("click", function () { $items.text($("#value").val()); report(); });
      $("#prefix").on("click", function () {
        $items.text(function (index, oldText) { return (index + 1) + ". " + oldText; });
        report();
      });
      $("#clear").on("click", function () { $items.text(""); report(); });
      $("#read").on("click", report);
      $("#reset").on("click", function () {
        $items.html(function (index) { return initial[index]; });
        $("#value").val("<em>Hello</em>");
        report();
      });
      report();
    });
  </script>
</body>
</html>

Resultado inicial:

combined="AlphaHiddenBeta"
per item=["AlphaHidden","Beta"]
items=2

1. Read dá o mesmo resultado. Hidden não aparece, mas está em combined e no primeiro item do array.
2. Prefix each item usa index e oldText para criar 1. AlphaHidden e 2. Beta. strong e o span oculto são substituídos por texto.
3. Depois de Reset, Set text mostra literalmente <em>Hello</em> nos dois parágrafos, sem criar em.
4. Edite Value e repita. A entrada é lida com .val() e espaços iniciais e finais ficam na string.
5. Clear text aplica .text(""). combined fica vazio, per item tem duas strings vazias e permanecem dois parágrafos.
6. Reset restaura HTML e entrada guardados. Repetir prefixos acrescenta ao texto atual: restaure antes de comparar as mesmas condições iniciais.

Espaços, conteúdo oculto e formatação perdida

Nenhum espaço é acrescentado entre Alpha e Beta, então combined é AlphaHiddenBeta. Mantenha perItem quando limites importarem ou use join com seu separador. Espaços e quebras do modelo de objetos do documento, DOM, e diferenças de análise do navegador podem afetar o resultado.

O textContent nativo também trata texto independentemente dos estilos e difere de innerText. Para excluir conteúdo oculto, decida primeiro quais elementos incluir. Ler um contêiner amplo sem considerar visibilidade não é exatamente o texto visto pelo leitor.

.text(value) não apenas acrescenta caracteres. Substitui tags filhas, então aplicar ao pai inteiro pode remover ícones, links e botões. Limite a escrita ao span do rótulo para manter os demais filhos.

0, false, seleções vazias e valores literais

Execute este trecho completo no Console. Ele altera um div temporário não inserido e o limpa no final. Números e booleanos viram texto; & permanece como caracteres sem ser interpretado como entidade HTML.

const $box = $("<div>A <span>B</span> C</div>");
console.log(`spaces=${JSON.stringify($box.text())}`);
$box.text(0);
console.log(`number=${JSON.stringify($box.text())}`);
$box.text(false);
console.log(`boolean=${JSON.stringify($box.text())}`);
$box.text("&amp;");
console.log(`entity characters=${JSON.stringify($box.text())}`);
console.log(`empty selection=${JSON.stringify($().text())}`);
$box.remove();

spaces="A B C"
number="0"
boolean="false"
entity characters="&"
empty selection=""

.text() de seleção vazia é uma string vazia. Um elemento existente sem conteúdo pode dar o mesmo resultado; confira .length para saber se existe. Não transforme automaticamente 0 ou false em ausência de dados com value || "".

Strings passadas a .text() não executam como tags nesse caminho textual. Passar o resultado a .html() depois é outra interpretação HTML. .text() não é sanitizador HTML; mantenha como texto os valores destinados a caracteres. Confira escopo, descendentes, separadores, .val() nos formulários e erros no Console se o resultado diferir.