String.prototype.replaceAll()

replaceAll() 方法是 String 值的一种方法,它返回一个新的字符串,其中所有与 pattern 匹配的内容都将被 replacement 替换。pattern 可以是字符串或 RegExpreplacement 可以是字符串或一个函数,该函数会在每次匹配时被调用。原始字符串保持不变。

试试看

语法

js
replaceAll(pattern, replacement)

参数

pattern

可以是字符串或具有 Symbol.replace 方法的对象——典型的例子是 正则表达式。任何不具有 Symbol.replace 方法的值都将被强制转换为字符串。

如果 pattern 是正则表达式,那么它必须设置全局 (g) 标志,否则将抛出 TypeError

replacement

可以是字符串或函数。replacement 的语义与 String.prototype.replace() 的语义相同。

返回值

一个新的字符串,其中所有与 pattern 匹配的内容都将被 replacement 替换。

异常

TypeError

如果 pattern 是正则表达式,并且没有设置全局 (g) 标志(它的 flags 属性不包含 "g"),则抛出此异常。

描述

此方法不会改变它所调用的字符串值。它返回一个新的字符串。

replace() 不同,此方法将替换字符串的所有出现,而不仅仅是第一个。如果字符串不是静态已知的,这将特别有用,因为在没有转义特殊字符的情况下调用 RegExp() 构造函数可能会无意中改变其语义。

js
function unsafeRedactName(text, name) {
  return text.replace(new RegExp(name, "g"), "[REDACTED]");
}
function safeRedactName(text, name) {
  return text.replaceAll(name, "[REDACTED]");
}

const report =
  "A hacker called ha.*er used special characters in their name to breach the system.";

console.log(unsafeRedactName(report, "ha.*er")); // "A [REDACTED]s in their name to breach the system."
console.log(safeRedactName(report, "ha.*er")); // "A hacker called [REDACTED] used special characters in their name to breach the system."

如果 pattern 是具有 Symbol.replace 方法的对象(包括 RegExp 对象),则该方法将以目标字符串和 replacement 作为参数调用。它的返回值将成为 replaceAll() 的返回值。在这种情况下,replaceAll() 的行为完全由 [Symbol.replace]() 方法编码,因此将与 replace() 产生相同的结果(除了对正则表达式是否全局的额外输入验证)。

如果 pattern 是空字符串,则替换将插入到每个 UTF-16 代码单元之间,类似于 split() 的行为。

js
"xxx".replaceAll("", "_"); // "_x_x_x_"

有关正则表达式属性(尤其是 粘性 标志)如何与 replaceAll() 交互的更多信息,请参阅 RegExp.prototype[Symbol.replace]()

示例

使用 replaceAll()

js
"aabbcc".replaceAll("b", ".");
// 'aa..cc'

非全局正则表达式抛出异常

使用正则表达式搜索值时,它必须是全局的。这将不起作用

js
"aabbcc".replaceAll(/b/, ".");
// TypeError: replaceAll must be called with a global RegExp

这将起作用

js
"aabbcc".replaceAll(/b/g, ".");
("aa..cc");

规范

规范
ECMAScript 语言规范
# sec-string.prototype.replaceall

浏览器兼容性

BCD 表格只在浏览器中加载

另请参阅