如何在TypeScript编辑器层面为自定义Image组件的可选alt参数加警告？

要让VSCode像对待Next.js的next/image组件那样，在你的CustomImage组件未传入alt时触发警告，有两种实用方案：

方案一：配置ESLint的可访问性规则 #

VSCode里的这类警告大多来自ESLint的jsx-a11y/alt-text规则，它默认只检查原生<img>标签。我们只需要扩展这个规则，让它识别你的自定义组件：

在ESLint配置文件（比如.eslintrc.js）中修改规则配置：

module.exports = {
  // 其他配置项...
  rules: {
    'jsx-a11y/alt-text': [
      'warn', // 也可设为'error'强制要求传入
      {
        elements: ['img', 'object', 'area', 'input[type="image"]'],
        img: ['CustomImage'] // 将你的自定义组件名添加到这里
      }
    ]
  }
};

配置完成后，ESLint会把CustomImage当作图片组件检查，未传入alt时就会弹出警告。

方案二：用TypeScript+JSDoc增强类型提示 #

如果不想依赖ESLint，也可以通过类型定义和JSDoc实现类似的警告效果：

方式1：JSDoc标记必填提示 #

直接在类型上通过JSDoc说明alt是必填项（仅当图片为纯装饰性时可省略），VSCode会读取这个提示并给出警告：

/**
 * 自定义图片组件
 * @param src 图片地址（必填）
 * @param alt 图片替代文本（必填，仅当图片纯装饰时可省略）
 * @param width 图片宽度
 * @param height 图片高度
 */
type ImageProps = {
  src: string;
  /** @default "" */
  alt?: string;
  width?: number;
  height?: number;
};

const CustomImage = ({ src, alt = "", width, height }: ImageProps) => {
  return <img src={src} alt={alt} width={width} height={height} />;
};

方式2：条件类型强制区分场景 #

如果想从类型层面强制区分普通图片和装饰图，可以使用条件类型：

type ImageProps<T extends boolean = false> = {
  src: string;
  width?: number;
  height?: number;
} & (T extends true ? { alt?: string } : { alt: string });

const CustomImage = <T extends boolean = false>({
  src,
  alt,
  width,
  height
}: ImageProps<T>) => {
  return <img src={src} alt={alt ?? ""} width={width} height={height} />;
};

// 普通图片必须传alt，否则TypeScript会报错
<CustomImage src="product.jpg" alt="商品展示图" />;
// 装饰图可以不传alt，但需要显式声明类型
<CustomImage<true> src="border-decor.jpg" />;

这种方式能从类型层面约束，正常使用时必须传入alt，只有明确标记为装饰图时才允许省略。

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