Skip to main content

restrict-template-expressions

Enforce template literal expressions to be of string type.

✅

在 ESLint 配置 中扩展"plugin:@typescript-eslint/recommended-type-checked" 可启用此规则。

💭

该规则需要 类型信息 才能运行。


JavaScript 在字符串上下文中自动 将对象转换为字符串，例如使用 + 将其与字符串连接或使用 ${} 将其嵌入到模板字面量中。 对象的默认 toString() 方法返回 "[object Object]"，这通常不是预期的。 此规则报告模板字面量字符串中使用的值，这些值不是字符串、数字或 BigInt，还可以选择允许提供有用的字符串化结果的其他数据类型。

英：JavaScript automatically converts an object to a string in a string context, such as when concatenating it with a string using + or embedding it in a template literal using ${}. The default toString() method of objects returns "[object Object]", which is often not what was intended. This rule reports on values used in a template literal string that aren't strings, numbers, or BigInts, optionally allowing other data types that provide useful stringification results.

注意

此规则有意不允许在模板文本中使用具有自定义 toString() 方法的对象，因为字符串化结果可能不方便用户使用。

英：This rule intentionally does not allow objects with a custom toString() method to be used in template literals, because the stringification result may not be user-friendly.

例如，数组有一个自定义的 toString() 方法，该方法仅在内部调用 join()，该方法用逗号连接数组元素。 这意味着 (1) 数组元素不一定会字符串化为有用的结果 (2) 逗号后面没有空格，导致结果对用户不友好。 格式化数组的最佳方法是使用 Intl.ListFormat，它甚至支持在必要时添加 "and" 连接词。 如果要在模板字面量中使用此对象，则必须显式调用 object.toString()。 no-base-to-string 规则可以用来防止这种情况下意外产生 "[object Object]"。

英：For example, arrays have a custom toString() method, which only calls join() internally, which joins the array elements with commas. This means that (1) array elements are not necessarily stringified to useful results (2) the commas don't have spaces after them, making the result not user-friendly. The best way to format arrays is to use Intl.ListFormat, which even supports adding the "and" conjunction where necessary. You must explicitly call object.toString() if you want to use this object in a template literal. The no-base-to-string rule can be used to guard this case against producing "[object Object]" by accident.

.eslintrc.cjs
module.exports = {
  "rules": {
    "@typescript-eslint/restrict-template-expressions": "error"
  }
};
在线运行试试这个规则 ↗

示例​

const arg1 = [1, 2];
const msg1 = `arg1 = ${arg1}`;

const arg2 = { name: 'Foo' };
const msg2 = `arg2 = ${arg2 || null}`;
Open in Playground

选项​

allowNumber​

此规则与 { allowNumber: true } 的附加 correct 代码示例：

英：Examples of additional correct code for this rule with { allowNumber: true }:

const arg = 123;
const msg1 = `arg = ${arg}`;
const msg2 = `arg = ${arg || 'zero'}`;
Open in Playground

此选项控制数字和 BigInt。

英：This option controls both numbers and BigInts.

allowBoolean​

此规则与 { allowBoolean: true } 的附加 correct 代码示例：

英：Examples of additional correct code for this rule with { allowBoolean: true }:

const arg = true;
const msg1 = `arg = ${arg}`;
const msg2 = `arg = ${arg || 'not truthy'}`;
Open in Playground

allowAny​

此规则与 { allowAny: true } 的附加 correct 代码示例：

英：Examples of additional correct code for this rule with { allowAny: true }:

const user = JSON.parse('{ "name": "foo" }');
const msg1 = `arg = ${user.name}`;
const msg2 = `arg = ${user.name || 'the user with no name'}`;
Open in Playground

allowNullish​

此规则与 { allowNullish: true } 的附加 correct 代码示例：

英：Examples of additional correct code for this rule with { allowNullish: true }:

const arg = condition ? 'ok' : null;
const msg1 = `arg = ${arg}`;
Open in Playground

allowRegExp​

此规则与 { allowRegExp: true } 的附加 correct 代码示例：

英：Examples of additional correct code for this rule with { allowRegExp: true }:

const arg = new RegExp('foo');
const msg1 = `arg = ${arg}`;
Open in Playground
const arg = /foo/;
const msg1 = `arg = ${arg}`;
Open in Playground

allowNever​

此规则与 { allowNever: true } 的附加 correct 代码示例：

英：Examples of additional correct code for this rule with { allowNever: true }:

const arg = 'something';
const msg1 = typeof arg === 'string' ? arg : `arg = ${arg}`;
Open in Playground

何时不使用它​

如果你不担心模板文本中的非字符串值被错误地字符串化，那么你可能不需要此规则。

英：If you're not worried about incorrectly stringifying non-string values in template literals, then you likely don't need this rule.

选项​

该规则接受以下选项

type Options = [
  {
    /** Whether to allow `any` typed values in template expressions. */
    allowAny?: boolean;
    /** Whether to allow `boolean` typed values in template expressions. */
    allowBoolean?: boolean;
    /** Whether to allow `never` typed values in template expressions. */
    allowNever?: boolean;
    /** Whether to allow `nullish` typed values in template expressions. */
    allowNullish?: boolean;
    /** Whether to allow `number` typed values in template expressions. */
    allowNumber?: boolean;
    /** Whether to allow `regexp` typed values in template expressions. */
    allowRegExp?: boolean;
  },
];

const defaultOptions: Options = [
  {
    allowAny: true,
    allowBoolean: true,
    allowNullish: true,
    allowNumber: true,
    allowRegExp: true,
  },
];

资源​