必须安装 @types/styled-components 以支持 TypeScript 类型推导，否则 props.theme 报错或为 any；ThemeProvider 需包裹所有依赖主题的组件，theme 值须通过完整路径（如 props.theme.colors.primary）访问，并配合 ThemeInterface 定义确保类型安全。
安装 styled-components 并确认 TypeScript 支持
不装 @types/styled-components，TypeScript 下 props 类型推导会失效，props.theme 报错或提示为 any。yarn 用户执行：
yarn add styled-components yarn add -D @types/styled-components babel-plugin-styled-components
npm 用户对应用 npm install 和 npm install -D。Babel 插件不是可选的——它影响开发时组件名显示、服务端渲染类名稳定性，以及生产环境的体积优化。
配置 ThemeProvider 与主题类型定义
直接往 ThemeProvider 里传裸对象会导致类型丢失。必须先定义 ThemeInterface，再用 createGlobalStyle 或 styled 组件消费时才能获得自动补全和类型检查。
- 在
theme.ts中定义接口和默认主题：
export interface ThemeInterface {
colors: {
primary: string;
background: string;
text: string;
};
spacing: (n: number) => string;
}
<p>export const defaultTheme: ThemeInterface = {
colors: {
primary: '#007bff',
background: '#ffffff',
text: '#333333',
},
spacing: (n) => <code>${n * 4}px</code>,
};- 在根组件（如
App.tsx）包裹ThemeProvider：
import { ThemeProvider } from 'styled-components';
import { defaultTheme } from './theme';
<p>function App() {
return (
<ThemeProvider theme={defaultTheme}>
<div>...</div>
</ThemeProvider>
);
}用 props.theme 在 styled 组件中读取主题值
错误写法：background-color: ${props => props.theme.primary} —— 缺少路径，primary 不在根层级；正确写法必须带完整路径，比如 props.theme.colors.primary。
根据项目规范生成 React 和 Vue 组件，包括 TypeScript 类型定义、Ant Design 5 集成、Tailwind CSS 样式及 Vitest 测试文件。当用户提出创建、生成或搭建前端组件的需求时启用，例如：“帮我写一个表格组件”、“生成一个弹窗”、“create a form component”、“写一个列表页”、“生成一个下拉选择器”。该能力在以下任一场景触发：涉及 React/TSX/Vue 组件生成、UI 组件创建，或为组件生成测试文件。
立即学习“前端免费学习笔记（深入）”；
- 支持嵌套结构，也支持函数式值（如
spacing）：
const Card = styled.div`
background-color: ${props => props.theme.colors.background};
color: ${props => props.theme.colors.text};
padding: ${props => props.theme.spacing(3)};
`;- 如果组件自身还接收额外 props（如
variant），主题值和业务 props 可共存：
const Button = styled.button<{ variant?: 'primary' | 'outline' }>`
background-color: ${props =>
props.variant === 'primary'
? props.theme.colors.primary
: 'transparent'};
border: 1px solid ${props => props.theme.colors.primary};
`;避免 theme 值被覆盖或未定义的坑
常见报错 Cannot read property 'colors' of undefined，本质是组件在 ThemeProvider 外部被渲染，或者 theme 没传进 Provider。调试时优先检查：
-
console.log(useTheme())在自定义 Hook 中是否返回有效对象 -
ThemeProvider是否包裹了所有需要主题的子组件（包括路由懒加载组件） - TypeScript 中是否漏写了
as const导致推导出string而非字面量类型，进而破坏联合类型判断
主题不是“设一次就完事”的配置，它是贯穿组件树的 context 数据流。任何中断（比如忘了在 Suspense 外包一层 ThemeProvider）都会让下游 styled 组件拿不到 theme。
