React用styled-components瞬态props报Invalid attribute name警告解决方法

使用styled-components的瞬态props（transient props，即$前缀的自定义props）特性，本想避免自定义属性被渲染传递到DOM元素上，但React仍然抛出警告：Invalid attribute name: $attrName。

复现代码如下：

interface ListItemProps {
  $item: boolean
}
export const ListItem = styled(ListItemBase)<ListItemProps>(({ $item }) => ({
 color: $item ? 'blue' : 'red'
}))

组件使用代码：

<ListItem $item={true} />

styled-components对瞬态props的自动过滤逻辑，仅在直接通过styled修饰原生DOM标签（比如styled.div、styled.li）时生效。如果是styled()包裹自定义React组件，styled-components不会自动拦截$开头的props，会把所有props完整传递给封装的自定义组件；如果自定义组件没有做属性过滤，直接把接收到的所有props透传给底层原生DOM节点，React识别到DOM上存在$开头的非法属性名，就会抛出该警告。
另外如果项目使用的styled-components版本低于5.1，瞬态props特性本身就没有内置支持，也会出现同类警告。

• 升级依赖版本：先确认本地styled-components版本≥5.1.0，低于该版本请先升级到稳定版，才能获得瞬态props的基础支持。
• 自定义组件层过滤props：在封装的ListItemBase组件内部，手动拦截所有$开头的瞬态props，不要把这类属性传递给底层DOM节点。
  单个属性过滤示例：

  // 单独解构出$item，剩余属性再传给DOM
  const ListItemBase = ({ $item, ...restProps }) => {
    return <li {...restProps} />
  }
  

  批量过滤通用写法：

  // 通用工具：过滤所有$开头的瞬态props
  const omitTransientProps = (props) => {
    return Object.fromEntries(
      Object.entries(props).filter(([key]) => !key.startsWith('$'))
    )
  }
  
  const ListItemBase = (props) => {
    const domValidProps = omitTransientProps(props)
    return <li {...domValidProps} />
  }
  

• 配置shouldForwardProp拦截属性：如果不想修改自定义组件逻辑，可以在定义styled组件时通过withConfig配置属性转发规则，显式拦截所有$开头的props，不让其传递给内层组件：

  interface ListItemProps {
    $item: boolean
  }
  export const ListItem = styled(ListItemBase).withConfig({
    shouldForwardProp: (propName) => !propName.startsWith('$')
  })<ListItemProps>(({ $item }) => ({
    color: $item ? 'blue' : 'red'
  }))
  

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