[pull] gh-pages from ruanyf:gh-pages

docs/string-methods.md

@@ -329,3 +329,88 @@ s.trimEnd() // " abc"
 
 `matchAll()`方法返回一个正则表达式在当前字符串的所有匹配，详见《正则的扩展》的一章。
 
+## 实例方法：replaceAll()
+
+历史上，字符串的实例方法`replace()`只能替换第一个匹配。
+
+```javascript
+'aabbcc'.replace('b', '_')
+// 'aa_bcc'
+```
+
+上面例子中，`replace()`只将第一个`b`替换成了下划线。
+
+如果要替换所有的匹配，不得不使用正则表达式的`g`修饰符。
+
+```javascript
+'aabbcc'.replace(/b/g, '_')
+// 'aa__cc'
+```
+
+正则表达式毕竟不是那么方便和直观，[ES2021](https://github.com/tc39/proposal-string-replaceall) 引入了`replaceAll()`方法，可以一次性替换所有匹配。
+
+```javascript
+'aabbcc'.replaceAll('b', '_')
+// 'aa__cc'
+```
+
+它的用法与`replace()`相同，返回一个新字符串，不会改变原字符串。
+
+```javascript
+String.prototype.replaceAll(searchValue, replacement)
+```
+
+上面代码中，`searchValue`是搜索模式，可以是一个字符串，也可以是一个全局的正则表达式（带有`g`修饰符）。
+
+如果`searchValue`是一个不带有`g`修饰符的正则表达式，`replaceAll()`会报错。这一点跟`replace()`不同。
+
+```javascript
+// 不报错
+'aabbcc'.replace(/b/, '_')
+
+// 报错
+'aabbcc'.replaceAll(/b/, '_')
+```
+
+上面例子中，`/b/`不带有`g`修饰符，会导致`replaceAll()`报错。
+
+`replaceAll()`的第二个参数`replacement`是一个字符串，表示替换的文本，其中可以使用一些特殊字符串。
+
+- `$&`：匹配的子字符串。
+- `` `$` ``：匹配结果前面的文本。
+- `$'`：匹配结果后面的文本。
+- `$n`：匹配成功的第`n`组内容，`n`是从1开始的自然数。
+- `$$`：指代美元符号`$`。
+
+```javascript
+'abc'.replaceAll('b', '$$')
+// 'a$c'
+```
+
+上面例子中，`$$`表示替换的文本是单个美元符号`$`。
+
+`replaceAll()`的第二个参数`replacement`除了为字符串，也可以是一个函数，该函数的返回值将替换掉第一个参数`searchValue`匹配的文本。
+
+```javascript
+'aabbcc'.replaceAll('b', () => '_')
+// 'aa__cc'
+```
+
+上面例子中，`replaceAll()`的第二个参数是一个函数，该函数的返回值会替换掉所有`b`的匹配。
+
+这个替换函数可以接受多个参数。第一个参数是捕捉到的匹配内容，第二个参数捕捉到是组匹配（有多少个组匹配，就有多少个对应的参数）。此外，最后还可以添加两个参数，倒数第二个参数是捕捉到的内容在整个字符串中的位置，最后一个参数是原字符串。
+
+```javascript
+const str = '123abc456';
+const regex = /(\d+)([a-z]+)(\d+)/g;
+
+function replacer(match, p1, p2, p3, offset, string) {
+ return [p1, p2, p3].join(' - ');
+}
+
+str.replaceAll(regex, replacer)
+// 123 - abc - 456
+```
+
+上面例子中，正则表达式有三个组匹配，所以`replacer()`函数的第一个参数`match`是捕捉到的匹配内容（即字符串`123abc456`），后面三个参数`p1`、`p2`、`p3`则依次为三个组匹配。
+