如何在styled-components v6中结合JSDoc为Props添加类型？

正确的JSDoc标注方案 #

方案1：完整标注组件为StyledComponent类型 #

这种方式能覆盖组件的所有类型（包括HTML原生Props、自定义Props），确保组件使用时的类型提示和校验完全正常：

/**
 * @type {import('styled-components').StyledComponent<
 *   import('react').HTMLAttributes<HTMLDivElement>, // 基础div元素的原生Props
 *   import('styled-components').DefaultTheme,       // 主题类型（无需主题可替换为{}）
 *   { $open: boolean }                              // 自定义Props
 * >}
 */
const ChildContent = styled.div`
  animation: ${p => p.$open ? slideOpen : slideClose};
`

使用组件时，TypeScript会自动校验原生属性（如style、ref）和自定义$open属性：

// 无类型错误，正常渲染
const Component = <ChildContent style={{ position: "absolute" }} $open={show} />

方案2：在样式回调中单独标注Props #

如果不需要给整个组件标注类型，也可以直接在样式的回调函数里用JSDoc标注参数，获得样式内部的类型提示：

const ChildContent = styled.div`
  /**
   * @param {Object} props
   * @param {boolean} props.$open 控制动画开关的自定义属性
   */
  animation: ${props => props.$open ? slideOpen : slideClose};
`

这种方式更轻量化，组件外部的类型校验依赖tsconfig的checkJs配置。

原有写法报错的原因 #

1. 第一种写法的问题：
   styled["div"]<{ $open: boolean }>的泛型语法不符合JSDoc的解析规则——styled.div是工厂函数，返回的是StyledComponent实例，直接给函数加泛型标注无法被TypeScript正确识别。

2. 第二种写法的问题：
   StyleFunction是styled-components内部用于创建样式的函数类型，并非最终的React组件类型。将styled.div的结果标注为StyleFunction后，TypeScript会认为它是普通函数，而非可渲染的JSX组件，因此使用<ChildContent />时会报错。

必要的tsconfig.json配置 #

要让TypeScript正确解析JS文件中的JSDoc类型，需确保tsconfig.json包含以下关键配置：

{
  "compilerOptions": {
    "checkJs": true,        // 开启JS文件的类型检查
    "jsx": "react-jsx",     // 支持React JSX语法
    "strict": true,         // 启用严格类型检查（推荐）
    "target": "ESNext",
    "moduleResolution": "bundler"
  },
  "include": ["src/**/*"]   // 包含需要检查的JS/JSX文件
}

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