将打字稿字符串文字联合中的一个（或多个）值注释为已弃用

Question

我知道可以将整个属性注释为已弃用，但是是否可以将字符串联合中的一个（或多个）单个值注释为已弃用？

例如，给定此类型声明：

export type BoxProps = HTMLAttributes<HTMLDivElement> & {
  /**
   * @deprecated rounded has no effect and will be removed in a future version
   */
  rounded?: boolean;
  variant?:
    | 'neutral'
    | 'grey'
    | 'success'
    | 'warning';
  thickBorder?: boolean;
};

...我的 IDE（VS Code）会警告我

rounded

参数已被弃用，并将其显示为视觉上的“划掉”。

但是，如果我尝试注释

variant

字符串文字联合类型的一个值，我的 IDE 将建议所有可能的选项，而不会发出任何警告或视觉处理来指示任何字符串已被弃用：

TypeScript
export type BoxProps = HTMLAttributes<HTMLDivElement> & {
  /**
   * @deprecated rounded has no effect and will be removed in a future version
   */
  rounded?: boolean;
  variant?:
    | 'neutral'
    /** @deprecated */
    | 'grey'
    | 'success'
    | 'warning';
  thickBorder?: boolean;

// or 

TypeScript
export type BoxProps = HTMLAttributes<HTMLDivElement> & {
  /**
   * @deprecated rounded has no effect and will be removed in a future version
   */
  rounded?: boolean;
  variant?:
    | 'neutral'
    | 'grey' /** @deprecated */
    | 'success'
    | 'warning';
  thickBorder?: boolean;
};

// or 

TypeScript
export type BoxProps = HTMLAttributes<HTMLDivElement> & {
  /**
   * @deprecated rounded has no effect and will be removed in a future version
   */
  rounded?: boolean;
  variant?:
    | 'neutral'
    | /** @deprecated */ 'grey' 
    | 'success'
    | 'warning';
  thickBorder?: boolean;
};

这是不可能的吗？或者是否需要使用其他一些语法来将单个字符串注释为已弃用？ （或者我缺少 VS Code 插件吗？）

Answer 1

@depecated

支持已于 2020 年通过 TS 4.0 落地。

在

ticket上对此进行了讨论，但目前没有联合和插入类型成员根本不支持TSDoc。

Answer 2

我认为 Visual Studio Code 中的 TSDoc 不可能做到这一点。我在我的 IDE（Visual Studio Code）中尝试过，但没有成功。

但是，有一个关于相同问题的 GitHub 问题，但使用了函数参数。尽管它不属于联合类型，但可能会有所帮助。只需

点击这里！

Answer 3

我正在尝试做同样的事情，并通过创建一个更高级别的联盟（不确定此模式的“官方名称”）取得了一些成功，如下所示：

这是所有未弃用的 props 的完整类型

export type BoxProps = HTMLAttributes<HTMLDivElement> & {
  /**
   * @deprecated rounded has no effect and will be removed in a future version
   */
  rounded?: boolean;
  variant?:
    | 'neutral'
    | 'success'
    | 'warning';
  thickBorder?: boolean;
};

这是您要应用于 Box 组件的类型，方法是创建原始类型的组合，然后创建一个非常窄的类型（仅包含您想要弃用的嵌套联合中的值）。

type BoxPropsWithBackwardsCompatibility =
  | BoxProps
  | (Omit<BoxProps, 'variant'> & {
      /**
       * @deprecated Use `neutral` instead of `grey`
       */
      intent: 'grey';
    });

我的 VS Code 可能配置错误，因为我没有看到错误，但我在悬停该道具时看到了弃用通知。

Answer 4

通过将联合值分为两种不同的类型并使用类型重载，您可以将重载的变体标记为已弃用。当使用该值时，这会触发警告。

以一个非反应示例开始，这样更容易理解。

type A = "A" | "C"
type B = "B"

function foo(input: A): void
/**
 * @deprecated do not use
 */
function foo(input: B): void
function foo(input: A | B): void {}

foo('A')
foo('B') // deprecated warning is generated
foo('C')

ts 游乐场链接

然后将其扩展为 React 组件

import React, { ReactElement } from 'react'

type A = {
    variant: "foo" | "bar"
}

type B = {
    variant: "baz"
}

function MyComponent(props: A): ReactElement
/**
 * @deprecated
 */
function MyComponent(props: B): ReactElement
function MyComponent(props: A | B): ReactElement {
  return <div></div>
}

const happy = <MyComponent variant='foo' /> // ok
const warning = <MyComponent variant='baz' /> // deprecation warning

ts 游乐场反应链接

根据 eslint 规则，可能需要忽略一些。我通过使用 @depreacted 值遇到了 eslint 错误，以及有关统一类型的另一个错误。正如 eslint lint 所理解的，这是冗余重载。

这些重载可以组合成一个签名

A | B