consistent-type-assertions

Enforce consistent usage of type assertions.

🎨

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

🔧

此规则报告的一些问题可通过 --fix ESLint 命令行选项自动修复。

💡

此规则报告的一些问题可以通过编辑器 建议 手动修复。

TypeScript 为 "类型断言" 提供了两种语法：

¥TypeScript provides two syntaxes for "type assertions":

• 尖括号：<Type>value

  ¥Angle brackets: <Type>value

• 作为：value as Type

  ¥As: value as Type

该规则旨在标准化整个代码库中类型断言样式的使用。始终坚持一种语法有助于提高代码的可读性。

¥This rule aims to standardize the use of type assertion style across the codebase. Keeping to one syntax consistently helps with code readability.

注意

类型断言在 TypeScript 中也通常称为 "类型转换"。然而，该术语在技术上与其他语言中类型转换的理解略有不同。类型断言是向 TypeScript 编译器 "我比你更了解，它实际上是这种不同的类型！" 说明的一种方式。

¥Type assertions are also commonly referred as "type casting" in TypeScript. However, that term is technically slightly different to what is understood by type casting in other languages. Type assertions are a way to say to the TypeScript compiler, "I know better than you, it's actually this different type!".

此规则始终允许 const 断言。它们的示例包括 let x = "hello" as const; 和 let x = <const>"hello";。

¥const assertions are always allowed by this rule. Examples of them include let x = "hello" as const; and let x = <const>"hello";.

Flat Config

eslint.config.mjs

export default tseslint.config({
  rules: {
    "@typescript-eslint/consistent-type-assertions": "error"
  }
});

Legacy Config

.eslintrc.cjs

module.exports = {
  "rules": {
    "@typescript-eslint/consistent-type-assertions": "error"
  }
};

在线运行试试这个规则 ↗

选项

该规则接受以下选项:

type Options = [
  | {
      /** The expected assertion style to enforce. */
      assertionStyle: /** The expected assertion style to enforce. */
      'never';
    }
  | {
      /** Whether to always prefer type declarations for array literals used as variable initializers, rather than type assertions. */
      arrayLiteralTypeAssertions?:
        | 'allow-as-parameter'
        | 'never'
        /** Whether to always prefer type declarations for array literals used as variable initializers, rather than type assertions. */
        | 'allow';
      /** The expected assertion style to enforce. */
      assertionStyle?:
        | 'angle-bracket'
        /** The expected assertion style to enforce. */
        | 'as';
      /** Whether to always prefer type declarations for object literals used as variable initializers, rather than type assertions. */
      objectLiteralTypeAssertions?:
        | 'allow-as-parameter'
        | 'never'
        /** Whether to always prefer type declarations for object literals used as variable initializers, rather than type assertions. */
        | 'allow';
    },
];

const defaultOptions: Options = [
  {
    arrayLiteralTypeAssertions: 'allow',
    assertionStyle: 'as',
    objectLiteralTypeAssertions: 'allow',
  },
];

¥Options

assertionStyle

The expected assertion style to enforce. Default: "as".

assertionStyle 的有效值为：

¥Valid values for assertionStyle are:

• as 将强制你始终使用 ... as foo。

  ¥as will enforce that you always use ... as foo.

• angle-bracket 将强制你始终使用 <foo>...

  ¥angle-bracket will enforce that you always use <foo>...

• never 将强制你不进行任何类型断言。

  ¥never will enforce that you do not do any type assertions.

大多数代码库都希望强制不使用 angle-bracket 样式，因为它与 JSX 语法相冲突，并且与通用语法搭配使用时会造成混淆。

¥Most codebases will want to enforce not using angle-bracket style because it conflicts with JSX syntax, and is confusing when paired with generic syntax.

一些代码库喜欢追求额外的类型安全级别，并通过 never 选项完全禁止断言。

¥Some codebases like to go for an extra level of type safety, and ban assertions altogether via the never option.

objectLiteralTypeAssertions

Whether to always prefer type declarations for object literals used as variable initializers, rather than type assertions. Default: "allow".

例如，这将优先使用 const x: T = { ... }; 而不是 const x = { ... } as T;（或类似带尖括号的选项）。后一种情况下的类型断言要么是不必要的，要么可能会隐藏错误。

¥For example, this would prefer const x: T = { ... }; to const x = { ... } as T; (or similar with angle brackets). The type assertion in the latter case is either unnecessary or will probably hide an error.

编译器将警告此语法中的过多属性，但不会丢失必需的字段。例如：const x: { foo: number } = {}; 将无法编译，但 const x = {} as { foo: number } 将成功。

¥The compiler will warn for excess properties with this syntax, but not missing required fields. For example: const x: { foo: number } = {}; will fail to compile, but const x = {} as { foo: number } will succeed.

TypeScript 3.4 中引入的 const 断言 const x = { foo: 1 } as const 被认为是有益的，并且被此选项忽略。

¥The const assertion const x = { foo: 1 } as const, introduced in TypeScript 3.4, is considered beneficial and is ignored by this option.

此选项还会忽略对 any 的断言。

¥Assertions to any are also ignored by this option.

{ assertionStyle: 'as', objectLiteralTypeAssertions: 'never' } 的代码示例：

¥Examples of code for { assertionStyle: 'as', objectLiteralTypeAssertions: 'never' }:

❌ Incorrect

const x = { foo: 1 } as T;

function bar() {
  return { foo: 1 } as T;
}

Open in Playground

✅ Correct

const x: T = { foo: 1 };
const y = { foo: 1 } as any;
const z = { foo: 1 } as unknown;

function bar(): T {
  return { foo: 1 };
}

Open in Playground

{ assertionStyle: 'as', objectLiteralTypeAssertions: 'allow-as-parameter' } 的代码示例：

¥Examples of code for { assertionStyle: 'as', objectLiteralTypeAssertions: 'allow-as-parameter' }:

❌ Incorrect

const x = { foo: 1 } as T;

function bar() {
  return { foo: 1 } as T;
}

Open in Playground

✅ Correct

const x: T = { foo: 1 };
const y = { foo: 1 } as any;
const z = { foo: 1 } as unknown;
bar({ foo: 1 } as T);
new Clazz({ foo: 1 } as T);
function bar() {
  throw { foo: 1 } as Foo;
}
const foo = <Foo props={{ bar: 1 } as Bar} />;

Open in Playground

arrayLiteralTypeAssertions

Whether to always prefer type declarations for array literals used as variable initializers, rather than type assertions. Default: "allow".

例如，这将优先使用 const x: T[] = [ ... ]; 而不是 const x = [ ... ] as T[];（或类似带尖括号的选项）。

¥For example, this would prefer const x: T[] = [ ... ]; to const x = [ ... ] as T[]; (or similar with angle brackets).

编译器将警告使用此语法的元素的多余属性，但不会缺少这些对象的必需字段。例如：const x: {foo: number}[] = [{}]; 将无法编译，但 const x = [{}] as [{ foo: number }] 将成功。

¥The compiler will warn for excess properties of elements with this syntax, but not missing required fields of those objects. For example: const x: {foo: number}[] = [{}]; will fail to compile, but const x = [{}] as [{ foo: number }] will succeed.

TypeScript 3.4 中引入的 const 断言 const x = [1, 2, 3] as const 被认为是有益的，并且被此选项忽略。

¥The const assertion const x = [1, 2, 3] as const, introduced in TypeScript 3.4, is considered beneficial and is ignored by this option.

此选项还会忽略对 any 的断言。

¥Assertions to any are also ignored by this option.

{ assertionStyle: 'as', arrayLiteralTypeAssertions: 'never' } 的代码示例：

¥Examples of code for { assertionStyle: 'as', arrayLiteralTypeAssertions: 'never' }:

❌ Incorrect

const x = ['foo'] as T;

function bar() {
  return ['foo'] as T;
}

Open in Playground

✅ Correct

const x: T = ['foo'];
const y = ['foo'] as any;
const z = ['foo'] as unknown;

function bar(): T {
  return ['foo'];
}

Open in Playground

{ assertionStyle: 'as', arrayLiteralTypeAssertions: 'allow-as-parameter' } 的代码示例：

¥Examples of code for { assertionStyle: 'as', arrayLiteralTypeAssertions: 'allow-as-parameter' }:

❌ Incorrect

const x = ['foo'] as T;

function bar() {
  return ['foo'] as T;
}

Open in Playground

✅ Correct

const x: T = ['foo'];
const y = ['foo'] as any;
const z = ['foo'] as unknown;
bar(['foo'] as T);
new Clazz(['foo'] as T);
function bar() {
  throw ['foo'] as Foo;
}
const foo = <Foo props={['foo'] as Bar} />;

Open in Playground

何时不使用它

¥When Not To Use It

如果你不想强制执行一致的类型断言。

¥If you do not want to enforce consistent type assertions.

但是，请记住，不一致的风格可能会损害项目的可读性。我们建议为此规则选择一个最适合你的项目的选项。

¥However, keep in mind that inconsistent style can harm readability in a project. We recommend picking a single option for this rule that works best for your project.

'## 资源'

• 规则源码
• 测试源码