如何在同步多组件公共Props时覆盖TSDoc/JSDoc注释？

问题场景 #

我正在用TypeScript开发React组件<EmailHeader>，需要定义它的Props类型。为了和父组件<EmailEditor>保持Props同步，我用Pick来合并继承的Props和自有Props，代码如下：

export type EmailHeaderProps = Pick<EmailEditorProps, 'availableSenders'> &
    Pick<EmailEditorProps['email'], 'sender' | 'recipients' | 'subject'> & {
        // 自有Props定义在此处
    };

现在我想给这些继承来的Props添加父组件不需要的特定TSDoc/JSDoc注释，但又不想放弃Props同步，请问有没有办法实现？还是必须重新声明每个属性并添加自定义注释？

可行解决方案 #

方法1：Omit+重新声明（保留类型同步的最优解）

可以先通过Omit排除需要自定义注释的属性，再重新声明这些属性并添加专属TSDoc，同时直接复用父组件的类型定义来保证类型同步。这样父组件类型变更时，子组件的类型会自动同步，只需要维护注释即可。

示例代码：

// 提取继承的基础类型，排除要自定义注释的属性
type InheritedEmailHeaderProps = Omit<
  Pick<EmailEditorProps, 'availableSenders'> &
  Pick<EmailEditorProps['email'], 'sender' | 'recipients' | 'subject'>,
  'availableSenders' | 'sender' | 'recipients' | 'subject'
>;

export type EmailHeaderProps = InheritedEmailHeaderProps & {
  /**
   * <EmailHeader>专属：可选发件人列表，用于头部快速切换发件人
   */
  availableSenders: EmailEditorProps['availableSenders'];
  /**
   * <EmailHeader>专属：当前选中的发件人信息，支持下拉切换
   */
  sender: EmailEditorProps['email']['sender'];
  /**
   * <EmailHeader>专属：邮件收件人集合，支持批量添加/删除
   */
  recipients: EmailEditorProps['email']['recipients'];
  /**
   * <EmailHeader>专属：邮件主题，限制最多100字符
   */
  subject: EmailEditorProps['email']['subject'];

  // 自有Props定义在此处
};

方法2：利用@inheritDoc标签（工具依赖型方案）

如果你的文档生成工具（如TypeDoc）支持TSDoc的@inheritDoc标签，可以在自定义注释中引用父组件的原有注释，再补充专属内容。不过这种方式需要额外声明变量来挂载注释，且兼容性有限。

示例代码：

export type EmailHeaderProps = Pick<EmailEditorProps, 'availableSenders'> &
  Pick<EmailEditorProps['email'], 'sender' | 'recipients' | 'subject'> & {
    // 自有Props定义在此处
  };

/**
 * <EmailHeader>专属：可选发件人列表，用于头部快速切换发件人
 * @inheritDoc EmailEditorProps.availableSenders
 */
export declare let availableSenders: EmailHeaderProps['availableSenders'];

// 其他属性同理添加注释声明

总结 #

不需要完全放弃Props同步，方法1是兼顾类型同步和自定义注释的最优选择：既保留了父组件类型变更时的自动同步能力，又能给每个继承属性添加专属的TSDoc说明。

内容的提问来源于stack exchange，提问作者GoncaloNGT