diff --git a/files/zh-cn/web/javascript/reference/global_objects/string/raw/index.md b/files/zh-cn/web/javascript/reference/global_objects/string/raw/index.md index 4a70ad02cc65b6..1a33d29281f873 100644 --- a/files/zh-cn/web/javascript/reference/global_objects/string/raw/index.md +++ b/files/zh-cn/web/javascript/reference/global_objects/string/raw/index.md @@ -5,24 +5,26 @@ slug: Web/JavaScript/Reference/Global_Objects/String/raw {{JSRef()}} -**String.raw()** 是一个[模板字符串](/zh-CN/docs/Web/JavaScript/Reference/template_strings)的标签函数,它的作用类似于 Python 中的字符串前缀 `r` 和 C# 中的字符串前缀 `@`(还是有点区别的,详见隔壁 Chromium 那边的[这个 issue](https://bugs.chromium.org/p/v8/issues/detail?id=5016)),是用来获取一个模板字符串的原始字符串的,比如说,占位符(例如 `${foo}`)会被处理为它所代表的其他字符串,而转义字符(例如 `\n`)不会。 +**`String.raw()`** 静态方法是[模板字符串](/zh-CN/docs/Web/JavaScript/Reference/template_strings)的标签函数。它的作用类似于 Python 中的 `r` 前缀或 C# 中用于字符串字面量的 `@` 前缀。它用于获取模板字符串的原始字符串形式——即,替换表达式(例如 `${foo}`)会被替换处理,但转义序列(例如 `\n`)不会被处理。 + +{{EmbedInteractiveExample("pages/js/string-raw.html")}} ## 语法 -```plain -String.raw(callSite, ...substitutions) +```js-nolint +String.raw(strings, ...substitutions) String.raw`templateString` ``` ### 参数 -- `callSite` - - : 一个模板字符串的“调用点对象”。类似 `{ raw: ['foo', 'bar', 'baz'] }`。 +- `strings` + - : 格式正确的模板字符串数组对象,例如 `{ raw: ['foo', 'bar', 'baz'] }`,应该是一个具有 `raw` 属性的对象,其值是一个类数组的字符串对象。 - `...substitutions` - - : 任意个可选的参数,表示任意个内插表达式对应的值。 + - : 包含的替换表达式对应的值。 - `templateString` - - : 模板字符串,可包含占位符(`${...}`)。 + - : 一个[模板字符串](/zh-CN/docs/Web/JavaScript/Reference/template_strings),可以包含替换表达式(`${...}`)。 ### 返回值 @@ -31,42 +33,83 @@ String.raw`templateString` ### 异常 - {{jsxref("TypeError")}} - - : 如果第一个参数没有传入一个格式正确的对象,则会抛出 `TypeError` 异常。 + - : 如果第一个参数没有 `raw` 属性,或者 `raw` 属性的值为 `undefined` 或 `null`,则会抛出异常。 ## 描述 -在大多数情况下,`String.raw()` 是用来处理模版字符串的。不要被上面复杂的参数要求吓到,因为像所有的 [tag functions](/zh-CN/docs/Web/JavaScript/Reference/template_strings#Tagged_template_literals)一样,你通常不需要把它看成一个普通函数,你只需要把它放在模板字符串前面就可以了,而不是在它后面加个括号和一堆参数来调用它,引擎会替你去调用它。 +在大多数情况下,`String.raw()` 与模板字符串一起使用。上面提到的第一种语法很少使用,因为 JavaScript 引擎会自动为你调用它并传入适当的参数(就像其他[标记函数](/zh-CN/docs/Web/JavaScript/Reference/Template_literals#带标签的模版)一样)。 `String.raw()` 是唯一一个内置的模板字符串标签函数,因为它太常用了。不过它并没有什么特殊能力,你自己也可以实现一个和它功能一模一样的标签函数。 +> **警告:** 不应直接将 `String.raw` 作为“标识”标签。请参见[构建标识标签](#构建标识标签)以了解如何实现此操作。 + +如果使用没有 `length` 属性或 `length` 为非正数的 `raw` 属性的对象调用 `String.raw()` 方法,它将返回一个空字符串 `""`。如果 `substitutions.length < strings.raw.length - 1`(即没有足够的替换项来填充占位符——这在一个格式正确的标记模板字面量中是不可能发生的),则其余的占位符将被填充为空字符串。 + ## 示例 -### 使用 `String.raw()` +### 使用 String.raw() ```js String.raw`Hi\n${2 + 3}!`; -// 'Hi\\n5!',Hi 后面的字符不是换行符,\ 和 n 是两个不同的字符 +// 'Hi\\n5!','Hi' 后面的字符不是换行符,'\' 和 'n' 是两个不同的字符。 String.raw`Hi\u000A!`; -// "Hi\\u000A!",同上,这里得到的会是 \、u、0、0、0、A 6 个字符, -// 任何类型的转义形式都会失效,保留原样输出,不信你试试.length +// 'Hi\\u000A!',同上,这里得到的会是 \、u、0、0、0、A,6 个字符。 +// 任何类型的转义形式都会失效,保留原样输出。 +// 你可以通过检查 string 的 .length 属性来确认这一点。 -let name = "Bob"; +const name = "Bob"; String.raw`Hi\n${name}!`; -// "Hi\nBob!",内插表达式还可以正常运行 +// 'Hi\\nBob!',内插表达式还可以正常替换。 + +String.raw`Hi \${name}!`; +// 'Hi \\${name}!',美元符号被转义;这里没有插值。 +``` -// 正常情况下,你也许不需要将 String.raw() 当作函数调用。 -// 但是为了模拟 `t${0}e${1}s${2}t` 你可以这样做: +### 构建标识标签 + +许多工具会对由特定名称标记的字面量进行特殊处理。 + +```js-nolint +// 一些格式化工具将会将这个字面量的内容格式化为 HTML +const doc = html` + +
+