From 4b20708f8d87f25ca0f7553f1c875240971c4b3c Mon Sep 17 00:00:00 2001 From: JasonLamv-t Date: Tue, 1 Aug 2023 09:06:15 +0800 Subject: [PATCH 1/7] [zh-cn]: Update translation of String.raw() --- .../global_objects/string/raw/index.md | 101 +++++++++++++----- 1 file changed, 73 insertions(+), 28 deletions(-) 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..89c2455fa25604 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()` 是用来处理模版字符串的。不要被上面复杂的参数要求吓到，因为像所有的[标签函数](/zh-CN/docs/Web/JavaScript/Reference/template_strings#带标签的模版)一样，你通常不需要把它看成一个普通函数，你只需要把它放在模板字符串前面就可以了，而不是在它后面加个括号和一堆参数来调用它，引擎会替你去调用它。 `String.raw()` 是唯一一个内置的模板字符串标签函数，因为它太常用了。不过它并没有什么特殊能力，你自己也可以实现一个和它功能一模一样的标签函数。 +> **警告：** 不应直接使用 `String.raw` 作为“身份”标签。请参见[构建身份标签](#building_an_identity_tag)以了解如何实现此操作。 + +如果使用没有 `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` + + + Hello + + +

Hello world!

+ + +`; +``` + +一个天真的实现 `html` 标签的方式可能是： + +```js +const html = String.raw; +``` + +实际上，这对于上面的情况是有效的。然而，因为 `String.raw` 方法将连接*原始*的字符串字面量而不是“处理过”的字符串字面量，所以转义序列将不会被处理。 + +```js-nolint +const doc = html`\n`; +// "\\n" +``` + +对于“真实的标识”标签而言，这可能并不是你想要的，因为这种情况下标签纯粹用于标记化，不会改变字面量的值。在这种情况下，你可以创建一个自定义标签，并将“处理过”的字面量数组传递给 `String.raw`，假装它们是原始字符串。 + +```js-nolint +const html = (strings, ...values) => String.raw({ raw: strings }, ...values); +// 一些格式化工具将会将这个字面量的内容格式化为 HTML +const doc = html`\n`; +// "\n"; the "\n" becomes a line break +``` + +请注意，第一个参数是一个带有 `raw` 属性的对象，其值是一个类数组对象（具有 `length` 属性和整数索引），表示模板字面量中分隔的字符串。其余的参数是替换项。由于 `raw` 值可以是任何类数组对象，它甚至可以是一个字符串！例如，`'test'` 被视为 `['t', 'e', 's', 't']`。以下代码等效于 `` `t${0}e${1}s${2}t` ``： + +```js String.raw({ raw: "test" }, 0, 1, 2); // 't0e1s2t' -// 注意这个测试，传入一个 string，和一个类似数组的对象 -// 下面这个函数和 `foo${2 + 3}bar${'Java' + 'Script'}baz` 是相等的。 -String.raw( - { - raw: ["foo", "bar", "baz"], - }, - 2 + 3, - "Java" + "Script", -); // 'foo5barJavaScriptbaz' ``` ## 规范 @@ -79,6 +122,8 @@ String.raw( ## 参见 -- [模板字符串](/zh-CN/docs/Web/JavaScript/Reference/template_strings) +- [`core-js` 中 `String.raw` 的 polyfill](https://github.com/zloirock/core-js#ecmascript-string-and-regexp) +- [模版字符串](/zh-CN/docs/Web/JavaScript/Reference/Template_literals) - {{jsxref("String")}} -- [JavaScript 词法](/zh-CN/docs/Web/JavaScript/Reference/Lexical_grammar) +- [词法文法](/zh-CN/docs/Web/JavaScript/Reference/Lexical_grammar) +- From b1b1179f545c57406f420903dc6f03101b1c51c2 Mon Sep 17 00:00:00 2001 From: Jason Lam Date: Tue, 1 Aug 2023 09:11:37 +0800 Subject: [PATCH 2/7] Apply suggestions from code review --- .../web/javascript/reference/global_objects/string/raw/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 89c2455fa25604..ee122a18edc814 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 @@ -43,7 +43,7 @@ String.raw`templateString` > **警告：** 不应直接使用 `String.raw` 作为“身份”标签。请参见[构建身份标签](#building_an_identity_tag)以了解如何实现此操作。 -如果使用没有 `length `属性或 `length` 为非正数的 `raw` 属性的对象调用 `String.raw()` 方法，它将返回一个空字符串 `""`。如果 `substitutions.length < strings.raw.length - 1`（即没有足够的替换项来填充占位符——这在一个格式正确的标记模板字面量中是不可能发生的），则其余的占位符将被填充为空字符串。 +如果使用没有 `length` 属性或 `length` 为非正数的 `raw` 属性的对象调用 `String.raw()` 方法，它将返回一个空字符串 `""`。如果 `substitutions.length < strings.raw.length - 1`（即没有足够的替换项来填充占位符——这在一个格式正确的标记模板字面量中是不可能发生的），则其余的占位符将被填充为空字符串。 ## 示例 From 8762cfb65857320a893645c1de6eccf1bb871d76 Mon Sep 17 00:00:00 2001 From: Jason Lam Date: Tue, 1 Aug 2023 09:15:55 +0800 Subject: [PATCH 3/7] Apply suggestions from code review --- .../web/javascript/reference/global_objects/string/raw/index.md | 1 - 1 file changed, 1 deletion(-) 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 ee122a18edc814..273dd2261b8ad1 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 @@ -126,4 +126,3 @@ String.raw({ raw: "test" }, 0, 1, 2); // 't0e1s2t' - [模版字符串](/zh-CN/docs/Web/JavaScript/Reference/Template_literals) - {{jsxref("String")}} - [词法文法](/zh-CN/docs/Web/JavaScript/Reference/Lexical_grammar) -- From a9bb43bc622f3579b876c5b24203bdb0903f7a89 Mon Sep 17 00:00:00 2001 From: Jason Lam Date: Tue, 1 Aug 2023 09:16:17 +0800 Subject: [PATCH 4/7] Apply suggestions from code review --- .../web/javascript/reference/global_objects/string/raw/index.md | 1 + 1 file changed, 1 insertion(+) 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 273dd2261b8ad1..06415432166bd5 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 @@ -126,3 +126,4 @@ String.raw({ raw: "test" }, 0, 1, 2); // 't0e1s2t' - [模版字符串](/zh-CN/docs/Web/JavaScript/Reference/Template_literals) - {{jsxref("String")}} - [词法文法](/zh-CN/docs/Web/JavaScript/Reference/Lexical_grammar) + From 02dec8dd0533827a3f83559d6281d9282423ad58 Mon Sep 17 00:00:00 2001 From: JasonLamv-t Date: Tue, 1 Aug 2023 09:22:59 +0800 Subject: [PATCH 5/7] update --- .../web/javascript/reference/global_objects/string/raw/index.md | 1 - 1 file changed, 1 deletion(-) 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 06415432166bd5..273dd2261b8ad1 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 @@ -126,4 +126,3 @@ String.raw({ raw: "test" }, 0, 1, 2); // 't0e1s2t' - [模版字符串](/zh-CN/docs/Web/JavaScript/Reference/Template_literals) - {{jsxref("String")}} - [词法文法](/zh-CN/docs/Web/JavaScript/Reference/Lexical_grammar) - From cf7427d4084fe34a4b46403aa8442d1dd3eec8d2 Mon Sep 17 00:00:00 2001 From: Jason Lam Date: Wed, 2 Aug 2023 08:56:11 +0800 Subject: [PATCH 6/7] Apply suggestions from code review Co-authored-by: A1lo --- .../reference/global_objects/string/raw/index.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) 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 273dd2261b8ad1..6ab407c55b80ae 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 @@ -37,11 +37,11 @@ String.raw`templateString` ## 描述 -在大多数情况下，`String.raw()` 是用来处理模版字符串的。不要被上面复杂的参数要求吓到，因为像所有的[标签函数](/zh-CN/docs/Web/JavaScript/Reference/template_strings#带标签的模版)一样，你通常不需要把它看成一个普通函数，你只需要把它放在模板字符串前面就可以了，而不是在它后面加个括号和一堆参数来调用它，引擎会替你去调用它。 +在大多数情况下，`String.raw()` 与模板字符串一起使用。上面提到的第一种语法很少使用，因为 JavaScript 引擎会自动为你调用它并传入适当的参数（就像其他[标记函数](/zh-CN/docs/Web/JavaScript/Reference/Template_literals#带标签的模版)一样）。 `String.raw()` 是唯一一个内置的模板字符串标签函数，因为它太常用了。不过它并没有什么特殊能力，你自己也可以实现一个和它功能一模一样的标签函数。 -> **警告：** 不应直接使用 `String.raw` 作为“身份”标签。请参见[构建身份标签](#building_an_identity_tag)以了解如何实现此操作。 +> **警告：** 不应直接将 `String.raw` 作为“标识”标签。请参见[构建身份标签](#构建身份标签)以了解如何实现此操作。 如果使用没有 `length` 属性或 `length` 为非正数的 `raw` 属性的对象调用 `String.raw()` 方法，它将返回一个空字符串 `""`。如果 `substitutions.length < strings.raw.length - 1`（即没有足够的替换项来填充占位符——这在一个格式正确的标记模板字面量中是不可能发生的），则其余的占位符将被填充为空字符串。 @@ -54,7 +54,7 @@ String.raw`Hi\n${2 + 3}!`; // 'Hi\\n5!'，'Hi' 后面的字符不是换行符，'\' 和 'n' 是两个不同的字符。 String.raw`Hi\u000A!`; -// 'Hi\\u000A!'，同上，这里得到的会是 \, u, 0, 0, 0, A, 6 个字符， +// 'Hi\\u000A!'，同上，这里得到的会是 \、u、0、0、0、A，6 个字符。 // 任何类型的转义形式都会失效，保留原样输出。 // 你可以通过检查 string 的 .length 属性来确认这一点。 @@ -103,10 +103,10 @@ const doc = html`\n`; const html = (strings, ...values) => String.raw({ raw: strings }, ...values); // 一些格式化工具将会将这个字面量的内容格式化为 HTML const doc = html`\n`; -// "\n"; the "\n" becomes a line break +// "\n"; "\n" 变成了换行符 ``` -请注意，第一个参数是一个带有 `raw` 属性的对象，其值是一个类数组对象（具有 `length` 属性和整数索引），表示模板字面量中分隔的字符串。其余的参数是替换项。由于 `raw` 值可以是任何类数组对象，它甚至可以是一个字符串！例如，`'test'` 被视为 `['t', 'e', 's', 't']`。以下代码等效于 `` `t${0}e${1}s${2}t` ``： +请注意，第一个参数是一个带有 `raw` 属性的对象，其值是一个类数组对象（具有 `length` 属性和整数索引），表示模板字面量中分隔的字符串。其余的参数是替换项。由于 `raw` 值可以是任何类数组对象，它甚至可以是一个字符串！例如，`'test'` 被视为 `['t', 'e', 's', 't']`。以下代码与 `` `t${0}e${1}s${2}t` `` 等效： ```js String.raw({ raw: "test" }, 0, 1, 2); // 't0e1s2t' From e4815e16adbc009c4304212dc6caa543b6cf8868 Mon Sep 17 00:00:00 2001 From: Jason Lam Date: Thu, 3 Aug 2023 00:30:34 +0800 Subject: [PATCH 7/7] Apply suggestions from code review --- .../javascript/reference/global_objects/string/raw/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 6ab407c55b80ae..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 @@ -41,7 +41,7 @@ String.raw`templateString` `String.raw()` 是唯一一个内置的模板字符串标签函数，因为它太常用了。不过它并没有什么特殊能力，你自己也可以实现一个和它功能一模一样的标签函数。 -> **警告：** 不应直接将 `String.raw` 作为“标识”标签。请参见[构建身份标签](#构建身份标签)以了解如何实现此操作。 +> **警告：** 不应直接将 `String.raw` 作为“标识”标签。请参见[构建标识标签](#构建标识标签)以了解如何实现此操作。 如果使用没有 `length` 属性或 `length` 为非正数的 `raw` 属性的对象调用 `String.raw()` 方法，它将返回一个空字符串 `""`。如果 `substitutions.length < strings.raw.length - 1`（即没有足够的替换项来填充占位符——这在一个格式正确的标记模板字面量中是不可能发生的），则其余的占位符将被填充为空字符串。 @@ -66,7 +66,7 @@ String.raw`Hi \${name}!`; // 'Hi \\${name}!'，美元符号被转义；这里没有插值。 ``` -### 构建身份标签 +### 构建标识标签 许多工具会对由特定名称标记的字面量进行特殊处理。