String.prototype.replace()

Метод replace() значений String возвращает новую строку, в которой одно, несколько или все совпадения pattern заменены на replacement. pattern может быть строкой или RegExp, а replacement может быть строкой или функцией, вызываемой для каждого совпадения. Если pattern — строка, будет заменено только первое вхождение. Исходная строка остается неизменной.

Попробуйте

const paragraph = "This dog's name is just Dog! Yes, that is the name.";

console.log(paragraph.replace("name", "nickname"));
// Expected output: "This dog's nickname is just Dog! Yes, that is the name."

console.log(paragraph.replace(/\bis\b/, "was"));
// Expected output: "This dog's name was just Dog! Yes, that is the name."

console.log(paragraph.replace(/\bis\b/g, "was"));
// Expected output: "This dog's name was just Dog! Yes, that was the name."

Синтаксис

replace(pattern, replacement)

Параметры

pattern

Может быть строкой или объектом с методом Symbol.replace — типичным примером является регулярное выражение. Любое значение, не имеющее метода Symbol.replace, будет преобразовано в строку.

replacement

Может быть строкой или функцией.

• Если это строка, она заменит подстроку, соответствующую pattern. Поддерживается ряд специальных шаблонов замены; см. раздел Указание строки в качестве замены ниже.
• Если это функция, она будет вызываться для каждого совпадения, и ее возвращаемое значение будет использоваться в качестве текста замены. Аргументы, передаваемые этой функции, описаны в разделе Указание функции в качестве замены ниже.

Возвращаемое значение

Новая строка, в которой одно, несколько или все совпадения шаблона заменены указанной заменой.

Описание

Этот метод не изменяет значение строки, на котором он был вызван. Он возвращает новую строку.

Строковый шаблон будет заменен только один раз. Для глобального поиска и замены используйте регулярное выражение с флагом g или используйте replaceAll() вместо этого.

Если pattern является объектом с методом Symbol.replace (включая объекты RegExp), этот метод вызывается с целевой строкой и replacement в качестве аргументов. Его возвращаемое значение становится возвращаемым значением replace(). В этом случае поведение replace() полностью кодируется методом [Symbol.replace]() — например, любое упоминание «захватывающих групп» в описании ниже на самом деле является функциональностью, предоставляемой RegExp.prototype[Symbol.replace]().

Если pattern — пустая строка, замена вставляется в начало строки.

"xxx".replace("", "_"); // "_xxx"

Регулярное выражение с флагом g — это единственный случай, когда replace() заменяет более одного раза. Дополнительную информацию о том, как свойства регулярных выражений (особенно флаг sticky) взаимодействуют с replace(), см. в RegExp.prototype[Symbol.replace]().

Указание строки в качестве замены

Строка замены может включать следующие специальные шаблоны замены:

$n и $<Name> доступны только в том случае, если аргумент pattern является объектом RegExp. Если pattern — строка или если соответствующая захватывающая группа отсутствует в регулярном выражении, то шаблон будет заменен как литерал. Если группа присутствует, но не совпала (потому что она является частью дизъюнкции), она будет заменена пустой строкой.

"foo".replace(/(f)/, "$2");
// "$2oo"; the regex doesn't have the second group

"foo".replace("f", "$1");
// "$1oo"; the pattern is a string, so it doesn't have any groups

"foo".replace(/(f)|(g)/, "$2");
// "oo"; the second group exists but isn't matched

Указание функции в качестве замены

Вы можете указать функцию в качестве второго параметра. В этом случае функция будет вызвана после выполнения совпадения. Результат функции (возвращаемое значение) будет использоваться в качестве строки замены.

Функция имеет следующую сигнатуру:

function replacer(match, p1, p2, /* …, */ pN, offset, string, groups) {
  return replacement;
}

Аргументы функции следующие:

match

Совпавшая подстрока. (Соответствует $& выше.)

p1, p2, …, pN

n-ая строка, найденная захватывающей группой (включая именованные захватывающие группы), при условии, что первый аргумент replace() является объектом RegExp. (Соответствует $1, $2 и т. д. выше.) Например, если pattern — /(\a+)(\b+)/, то p1 — это совпадение для \a+, а p2 — совпадение для \b+. Если группа является частью дизъюнкции (например, "abc".replace(/(a)|(b)/, replacer)), несоответствующая альтернатива будет undefined.

offset

Смещение совпавшей подстроки в исследуемой строке. Например, если вся строка была 'abcd', а совпавшая подстрока — 'bc', то этот аргумент будет 1.

string

Вся исследуемая строка.

groups

Объект, ключами которого являются используемые имена групп, а значениями — совпавшие части (undefined, если не совпало). Присутствует только если pattern содержит хотя бы одну именованную захватывающую группу.

Точное количество аргументов зависит от того, является ли первый аргумент объектом RegExp — и, если да, то сколько у него захватывающих групп.

Следующий пример установит newString в 'abc - 12345 - #$*%':

function replacer(match, p1, p2, p3, offset, string) {
  // p1 is non-digits, p2 digits, and p3 non-alphanumerics
  return [p1, p2, p3].join(" - ");
}
const newString = "abc12345#$*%".replace(/(\D*)(\d*)(\W*)/, replacer);
console.log(newString); // abc - 12345 - #$*%

Функция будет вызвана несколько раз для каждого полного совпадения, которое нужно заменить, если регулярное выражение в первом параметре является глобальным.

Примеры

Определение регулярного выражения в replace()

В следующем примере регулярное выражение определено в replace() и включает флаг игнорирования регистра.

const str = "Twas the night before Xmas...";
const newStr = str.replace(/xmas/i, "Christmas");
console.log(newStr); // Twas the night before Christmas...

Это выводит в консоль 'Twas the night before Christmas...'.

Использование флагов global и ignoreCase с replace()

Глобальная замена может быть выполнена только с помощью регулярного выражения. В следующем примере регулярное выражение включает глобальный флаг и флаг игнорирования регистра, что позволяет replace() заменить каждое вхождение 'apples' в строке на 'oranges'.

const re = /apples/gi;
const str = "Apples are round, and apples are juicy.";
const newStr = str.replace(re, "oranges");
console.log(newStr); // oranges are round, and oranges are juicy.

Это выводит в консоль 'oranges are round, and oranges are juicy'.

Перестановка слов в строке

Следующий скрипт меняет местами слова в строке. Для текста замены скрипт использует захватывающие группы и шаблоны замены $1 и $2.

const re = /(\w+)\s(\w+)/;
const str = "Maria Cruz";
const newStr = str.replace(re, "$2, $1");
console.log(newStr); // Cruz, Maria

Это выводит в консоль 'Cruz, Maria'.

Использование встроенной функции, которая изменяет совпавшие символы

В этом примере все заглавные буквы в строке преобразуются в строчные, и перед совпавшей позицией вставляется дефис. Важно то, что требуются дополнительные операции над совпавшим элементом перед его возвратом в качестве замены.

Функция замены принимает совпавший фрагмент в качестве параметра и использует его для преобразования регистра и конкатенации дефиса перед возвратом.

function styleHyphenFormat(propertyName) {
  function upperToHyphenLower(match, offset, string) {
    return (offset > 0 ? "-" : "") + match.toLowerCase();
  }
  return propertyName.replace(/[A-Z]/g, upperToHyphenLower);
}

При styleHyphenFormat('borderTop') это возвращает 'border-top'.

Поскольку нам нужно дополнительно преобразовать результат совпадения перед выполнением окончательной подстановки, мы должны использовать функцию. Это заставляет выполнить оценку совпадения перед методом toLowerCase(). Если бы мы попытались сделать это, используя совпадение без функции, toLowerCase() не имел бы эффекта.

// Won't work
const newString = propertyName.replace(/[A-Z]/g, "-" + "$&".toLowerCase());

Это потому, что '$&'.toLowerCase() сначала будет оценен как строковый литерал (результатом будет тот же '$&'), прежде чем использовать символы в качестве шаблона.

Замена градуса Фаренгейта эквивалентным градусом Цельсия

Следующий пример заменяет градус Фаренгейта эквивалентным градусом Цельсия. Градус Фаренгейта должен быть числом, заканчивающимся на "F". Функция возвращает число по Цельсию, заканчивающееся на "C". Например, если входное число — "212F", функция возвращает "100C". Если число — "0F", функция возвращает "-17.77777777777778C".

Регулярное выражение test проверяет любое число, заканчивающееся на F. Количество градусов Фаренгейта доступно функции через ее второй параметр, p1. Функция устанавливает число по Цельсию на основе количества градусов Фаренгейта, переданного в строке в функцию f2c(). f2c() затем возвращает число по Цельсию. Эта функция аппроксимирует флаг s///e в Perl.

function f2c(x) {
  function convert(str, p1, offset, s) {
    return `${((p1 - 32) * 5) / 9}C`;
  }
  const s = String(x);
  const test = /(-?\d+(?:\.\d*)?)F\b/g;
  return s.replace(test, convert);
}

Создание общего заменителя

Предположим, мы хотим создать заменитель, который добавляет данные смещения к каждой совпавшей строке. Поскольку функция-заменитель уже получает параметр offset, это будет тривиально, если регулярное выражение статически известно.

"abcd".replace(/(bc)/, (match, p1, offset) => `${match} (${offset}) `);
// "abc (1) d"

Однако этот заменитель будет трудно обобщить, если мы хотим, чтобы он работал с любым шаблоном регулярного выражения. Заменитель является вариативным — количество аргументов, которое он получает, зависит от количества присутствующих захватывающих групп. Мы можем использовать rest parameters, но это также соберет offset, string и т. д. в массив. Тот факт, что groups может быть передано или нет в зависимости от идентификатора регулярного выражения, также затруднит общее определение того, какой аргумент соответствует offset.

function addOffset(match, ...args) {
  const offset = args.at(-2);
  return `${match} (${offset}) `;
}

console.log("abcd".replace(/(bc)/, addOffset)); // "abc (1) d"
console.log("abcd".replace(/(?<group>bc)/, addOffset)); // "abc (abcd) d"

Пример addOffset выше не работает, когда регулярное выражение содержит именованную группу, потому что в этом случае args.at(-2) будет string вместо offset.

Вместо этого вам нужно извлечь последние несколько аргументов на основе типа, потому что groups — это объект, а string — строка.

function addOffset(match, ...args) {
  const hasNamedGroups = typeof args.at(-1) === "object";
  const offset = hasNamedGroups ? args.at(-3) : args.at(-2);
  return `${match} (${offset}) `;
}

console.log("abcd".replace(/(bc)/, addOffset)); // "abc (1) d"
console.log("abcd".replace(/(?<group>bc)/, addOffset)); // "abc (1) d"

Спецификации

Совместимость с браузерами

См. также

• Polyfill of String.prototype.replace in core-js with fixes and implementation of modern behavior like Symbol.replace support
• Руководство по регулярным выражениям
• String.prototype.replaceAll()
• String.prototype.match()
• RegExp.prototype.exec()
• RegExp.prototype.test()
• Symbol.replace
• RegExp.prototype[Symbol.replace]()