跳至主要內容

限制範本運算式

強制要求範本文字運算式為 string 型別。

✅

延伸 "plugin:@typescript-eslint/recommended-type-checked" 在 ESLint 組態 中啟用此規則。

💭

此規則需要 型別資訊 才能執行。

JavaScript 會在字串脈絡中自動將物件轉換為字串，例如使用 + 將其與字串串接在一起，或使用 ${} 將其嵌入範本文字中。物件的預設 toString() 方法會使用格式 "[object Object]"，這通常並不是預期結果。此規則會回報範本文字字串中使用但並非字串的值，並可以選擇允許提供有用字串化結果的其他資料類型。

備註

此規則的預設設定故意不允許在範本字串中使用具自訂 toString() 方法的物件，因為字串化結果可能不利於使用者閱讀。

例如，陣列具有自訂的 toString() 方法，其只在內部呼叫 join()，這會使用逗號來連結陣列元素。這表示：(1) 陣列元素不一定會轉換為實用的結果 (2) 逗號後面沒有空格，這使得結果不利於使用者閱讀。格式化陣列的最佳方式是使用 Intl.ListFormat，它甚至支援在必要時加入「and」連結詞。如果您想要在範本字串中使用此物件，您必須明確地呼叫 object.toString()，或開啟 allowArray 選項以明確允許陣列。no-base-to-string 規則可用於避免意外產生 "[object Object]"。

.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}`;
在遊樂場中開啟

選項​

此規則接受下列選項，且在 strict 和 strict-type-checked 設定中具備更嚴格的設定。

type Options = [
  {
    /** Whether to allow `any` typed values in template expressions. */
    allowAny?: boolean;
    /** Whether to allow `array` typed values in template expressions. */
    allowArray?: 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 defaultOptionsRecommended: Options = [
  {
    allowAny: true,
    allowBoolean: true,
    allowNullish: true,
    allowNumber: true,
    allowRegExp: true,
  },
];

// These options are merged on top of the recommended defaults
const defaultOptionsStrict: Options = [
  {
    allowAny: false,
    allowBoolean: false,
    allowNullish: false,
    allowNumber: false,
    allowRegExp: false,
    allowNever: false,
  },
];

allowNumber​

使用 { allowNumber: true } 讓此規則額外提供正確的程式碼範例

const arg = 123;
const msg1 = `arg = ${arg}`;
const msg2 = `arg = ${arg || 'zero'}`;
在遊樂場中開啟

此選項同時控制數字和 BigInt。

allowBoolean​

使用 { allowBoolean: true } 讓此規則額外提供正確的程式碼範例

const arg = true;
const msg1 = `arg = ${arg}`;
const msg2 = `arg = ${arg || 'not truthy'}`;
在遊樂場中開啟

allowAny​

使用 { allowAny: true } 讓此規則額外提供正確的程式碼範例

const user = JSON.parse('{ "name": "foo" }');
const msg1 = `arg = ${user.name}`;
const msg2 = `arg = ${user.name || 'the user with no name'}`;
在遊樂場中開啟

allowNullish​

額外正確程式碼範例，規則設定為 { allowNullish: true }

const arg = condition ? 'ok' : null;
const msg1 = `arg = ${arg}`;
在遊樂場中開啟

allowRegExp​

額外正確程式碼範例，規則設定為 { allowRegExp: true }

const arg = new RegExp('foo');
const msg1 = `arg = ${arg}`;
在遊樂場中開啟
const arg = /foo/;
const msg1 = `arg = ${arg}`;
在遊樂場中開啟

allowNever​

額外正確程式碼範例，規則設定為 { allowNever: true }

const arg = 'something';
const msg1 = typeof arg === 'string' ? arg : `arg = ${arg}`;
在遊樂場中開啟

allowArray​

額外正確程式碼範例，規則設定為 { allowArray: true }

const arg = ['foo', 'bar'];
const msg1 = `arg = ${arg}`;
在遊樂場中開啟

何時不用​

如果你不擔心錯誤地將非字串值字串化在字串範本中，那麼你可能不需要這條規則。

類型檢查程式碼校正規則比傳統的程式碼校正規則功能更強大，但你需要設定類型檢查程式碼校正。若你在啟用類型檢查規則後，遇到效能下降問題，請見效能疑難排解。

資源​