React中CSSProperties无法通过索引访问自定义属性，求解决方案

问题场景 #

你定义了一个类型为React.CSSProperties的样式对象，包含自定义CSS变量和标准样式属性：

const style = {
  '--primary-color': '#ff0000',
  color: '#ff0000',
} as React.CSSProperties;

访问标准属性style['color']正常，但访问自定义属性style['--primary-color']或style['var(--primary-color)']时，TypeScript报错：

Element implicitly has an 'any' type because expression of type '"--primary-color"' can't be used to index type 'CSSProperties'.
  Property '--primary-color' does not exist on type 'CSSProperties'

解决思路 #

1. 临时类型断言（快速解决） #

通过类型断言绕过TypeScript的类型检查，直接访问自定义属性：

// 最简单的方式，断言为any
console.log((style as any)['--primary-color']);

// 更严谨的断言，指定值类型范围
console.log((style as Record<string, string | number | undefined>)['--primary-color']);

2. 全局扩展CSSProperties类型（长期方案） #

在项目的.d.ts文件（比如src/types/react.d.ts）中扩展React.CSSProperties接口，让它支持所有以--开头的自定义CSS变量：

declare module 'react' {
  interface CSSProperties {
    // 支持任意以--开头的自定义属性，值为CSS允许的类型
    [key: `--${string}`]: string | number | undefined;
  }
}

扩展后，无需额外断言即可直接访问所有自定义CSS变量，同时保留TypeScript的类型检查能力。

3. 自定义交叉类型（局部类型安全） #

如果不想修改全局类型，可以定义一个包含目标自定义属性的类型，与React.CSSProperties交叉使用：

// 定义包含自定义属性的类型
type CustomStyle = React.CSSProperties & {
  '--primary-color'?: string;
  // 可按需添加更多自定义属性
};

// 使用自定义类型定义样式对象
const style: CustomStyle = {
  '--primary-color': '#ff0000',
  color: '#ff0000',
};

// 直接访问无类型错误
console.log(style['--primary-color']);

原因说明 #

React官方的CSSProperties类型仅包含标准CSS属性的定义，未覆盖自定义CSS变量（--xxx格式），因此TypeScript会判定这些属性不属于CSSProperties类型，触发索引报错。

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