Сводка

Методreplace() возвращает новую строку с некоторыми или всеми сопоставлениями с шаблоном, заменёнными на заменитель. Шаблон может быть строкой илирегулярным выражением, а заменитель может быть строкой или функцией, вызываемой при каждом сопоставлении.

Синтаксис

str.replace(regexp|substr, newSubStr|function[, flags])

Параметры

regexp

Объект регулярного выраженияRegExp. Сопоставление заменяется возвращаемым значением второго параметра.

substr

Строка, заменяемая наnewSubStr. Обратите внимание, будет заменено только первое вхождение искомой строки.

newSubStr

Строка, заменяющая подстроку из первого параметра. Поддерживает несколько специальных шаблонов замены; смотрите ниже разделПередача строки в качестве второго параметра.

function

Функция, вызываемая для создания новой подстроки (помещаемой вместо подстроки из первого параметра). Аргументы, передаваемые функции, описаны ниже в разделеПередача функции в качестве второго параметра.

flagsНе стандартно

Обратите внимание: аргументflags не работает в ядре v8 (движок JavaScript в Chrome и NodeJs). Строка, задающая комбинациюфлагов регулярного выражения. Параметрflags в методеString.prototype.replace() является нестандартным расширением. Вместо использования этого параметра используйте объектRegExp с соответствующими флагами. Значение этого параметра, если он используется, должно быть строкой, состоящей из одного или более следующих символов, следующим образом влияющих на обработку регулярного выражения:

g

глобальное сопоставление

i

игнорировать регистр

m

сопоставление по нескольким строкам

yЭкспериментальная возможность

«липкий» поиск, сопоставление начинается с текущей позиции в строке

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

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

Описание

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

Для выполнения глобального поиска и замены либо включите флагg в регулярное выражение, либо, если первый параметр является строкой, включите флагg в параметрflags.

Передача строки в качестве второго параметра

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

Передача функции в качестве второго параметра

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

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

Точное число аргументов будет зависеть от того, был ли первым аргументом объектRegExp и, если был, сколько подгрупп в нём определено.

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

function replacer(match, p1, p2, p3, offset, string) {  // p1 - не цифры, p2 - цифры, p3 - не буквы и не цифры  return [p1, p2, p3].join(" - ");}var newString = "abc12345#$*%".replace(/([^\d]*)(\d*)([^\w]*)/, replacer);

Примеры

Пример: использование флаговglobal иignore с методомreplace()

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

var re = /яблоки/gi;var str = "Яблоки круглые и яблоки сочные.";var newstr = str.replace(re, "апельсины");console.log(newstr); // апельсины круглые и апельсины сочные.

Пример: передача регулярного выражения в методreplace()

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

// Ночь перед Рождеством, Xmas - сокращение для Christmasvar str = "Twas the night before Xmas...";var newstr = str.replace(/xmas/i, "Christmas");console.log(newstr); // Twas the night before Christmas...

Пример выведет строку 'Twas the night before Christmas...'

Пример: смена местами слов в строке

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

var re = /([А-ЯЁа-яё]+)\s([А-ЯЁа-яё]+)/;var str = "Джон Смит";var newstr = str.replace(re, "$2, $1");console.log(newstr); // Смит, Джон

Пример выведет строку 'Смит, Джон'.

Пример: использование функции для изменения сопоставившихся символов

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

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

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

ВызовstyleHyphenFormat('borderTop') вернёт строку 'border-top'.

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

var newString = propertyName.replace(/[A-Z]/g, "-" + "$&".toLowerCase()); // не работает

Происходит это потому, что сначала часть'$&'.toLowerCase() вычисляется в строковый литерал (результат по-прежнему равен'$&'), а только потом его символы используются в качестве шаблона.

Пример: замена градусов по Фаренгейту на эквивалент в градусах по Цельсию

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

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

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

Пример: использование функции вместе с регулярным выражением для избавления от циклаfor

Следующий пример принимает строку шаблона и преобразует её в массив объектов.

Входные данные:

Строка, состоящая из символовx,- и_

x-x_x---x---x---x---x-xxx-xx-x-x_x_x___x___x___

Выходные данные:

Массив объектов. Символ'x' означает состояние'on', символ'-' (дефис) означает состояние'off', а символ'_' (нижнее подчёркивание) означает продолжительность состояния'on'.

[  { on: true, length: 1 },  { on: false, length: 1 },  { on: true, length: 2 }  ...]

Код:

var str = "x-x_";var retArr = [];str.replace(/(x_*)|(-)/g, function (match, p1, p2) {  if (p1) {    retArr.push({ on: true, length: p1.length });  }  if (p2) {    retArr.push({ on: false, length: 1 });  }});console.log(retArr);

Этот код сгенерирует массив из трёх объектов в описанном формате без использования циклаfor.

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

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

Смотрите также

• String.prototype.match()
• RegExp.prototype.exec()
• RegExp.prototype.test()