# React 项目基础（css prop + ThemeProvider）
npm install @emotion/react
 
# 加上 styled 组件 API
npm install @emotion/react @emotion/styled
 
# 框架无关用法（非 React 项目）
npm install @emotion/css
 
# 开发依赖：Babel 插件（推荐，用于样式优化和源码映射）
npm install -D @emotion/babel-plugin

// .babelrc
{
  "plugins": [
    "@emotion"
    // ⚠️ @emotion/babel-plugin 必须放在 plugins 数组的第一位
  ]
}

// tsconfig.json
{
  "compilerOptions": {
    "jsxImportSource": "@emotion/react"
    // 启用 css prop 支持
  }
}

// types/emotion.d.ts
import '@emotion/react'
 
declare module '@emotion/react' {
  export interface Theme {
    colors: {
      primary: string
      secondary: string
      background: string
      text: string
    }
    spacing: {
      sm: string
      md: string
      lg: string
    }
    breakpoints: {
      mobile: string
      tablet: string
      desktop: string
    }
  }
}

import { css } from '@emotion/react'
 
function App() {
  return (
    <div
      css={css`
        display: flex;
        flex-direction: column;
        align-items: center;
        padding: 24px;
        background-color: #f5f5f5;
      `}
    >
      <h1
        css={{
          color: '#333',
          fontSize: '2rem',
          marginBottom: '16px',
        }}
      >
        Hello Emotion
      </h1>
      <p
        css={(theme) => css`
          color: ${theme.colors.text};
          font-size: 1rem;
        `}
      >
        使用 css prop 直接编写样式
      </p>
    </div>
  )
}

import styled from '@emotion/styled'
 
const Container = styled.div`
  display: flex;
  flex-direction: column;
  align-items: center;
  padding: 24px;
  background-color: ${(props) => props.theme.colors.background};
`
 
const Title = styled.h1({
  color: '#333',
  fontSize: '2rem',
  marginBottom: '16px',
})
 
// 支持动态 props
const Button = styled.button<{ variant: 'primary' | 'secondary' }>`
  padding: 8px 16px;
  border: none;
  border-radius: 4px;
  cursor: pointer;
  background-color: ${(props) =>
    props.variant === 'primary' ? '#007bff' : '#6c757d'};
  color: white;
 
  &:hover {
    opacity: 0.9;
  }
`
 
function App() {
  return (
    <Container>
      <Title>Hello Emotion</Title>
      <Button variant="primary">点击我</Button>
    </Container>
  )
}

import React from 'react'
import { ThemeProvider } from '@emotion/react'
import styled from '@emotion/styled'
 
const theme = {
  colors: {
    primary: '#007bff',
    secondary: '#6c757d',
    background: '#ffffff',
    text: '#333333',
  },
  spacing: {
    sm: '8px',
    md: '16px',
    lg: '24px',
  },
  breakpoints: {
    mobile: '480px',
    tablet: '768px',
    desktop: '1024px',
  },
}
 
const Card = styled.div`
  background: ${(props) => props.theme.colors.background};
  color: ${(props) => props.theme.colors.text};
  padding: ${(props) => props.theme.spacing.lg};
  border-radius: 8px;
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
 
  @media (max-width: ${(props) => props.theme.breakpoints.tablet}) {
    padding: ${(props) => props.theme.spacing.md};
  }
`
 
function App() {
  return (
    <ThemeProvider theme={theme}>
      <Card>
        <h2>主题化卡片</h2>
        <p>样式从 theme 对象中读取设计令牌</p>
      </Card>
    </ThemeProvider>
  )
}
 
export default App

// 模板字符串语法
const A = styled.div`
  color: red;
  &:hover { color: blue; }
  @media (min-width: 768px) { font-size: 1.2rem; }
`
 
// 对象语法（TypeScript 推断更友好）
const B = styled.div({
  color: 'red',
  '&:hover': { color: 'blue' },
  '@media (min-width: 768px)': { fontSize: '1.2rem' },
})

import { ThemeProvider, useTheme } from '@emotion/react'
 
function ThemedComponent() {
  const theme = useTheme()
  return <div css={{ color: theme.colors.primary }}>主题色文字</div>
}

import { css, cx } from '@emotion/css'
 
const base = css`
  padding: 8px;
  border-radius: 4px;
`
const primary = css`
  background: #007bff;
  color: white;
`
const large = css`
  padding: 16px;
  font-size: 1.2rem;
`
 
function Badge({ isLarge }: { isLarge: boolean }) {
  return <span className={cx(base, primary, isLarge && large)}>标签</span>
}

import serializer from '@emotion/jest/serializer'
 
expect.addSnapshotSerializer(serializer)
 
test('按钮样式', () => {
  const { container } = render(<Button>Click</Button>)
  expect(container.firstChild).toMatchEmotionSnapshot()
})

import { Global, css } from '@emotion/react'
 
function GlobalStyles() {
  return (
    <Global
      styles={css`
        *,
        *::before,
        *::after {
          box-sizing: border-box;
          margin: 0;
          padding: 0;
        }
 
        body {
          font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto,
            sans-serif;
          -webkit-font-smoothing: antialiased;
        }
      `}
    />
  )
}

import { keyframes } from '@emotion/react'
import styled from '@emotion/styled'
 
const fadeIn = keyframes`
  from { opacity: 0; transform: translateY(10px); }
  to { opacity: 1; transform: translateY(0); }
`
 
const AnimatedCard = styled.div`
  animation: ${fadeIn} 0.3s ease-out;
`

// .babelrc
{
  "plugins": [
    [
      "@emotion",
      {
        "sourceMap": true,           // 开发环境开启源码映射
        "autoLabel": "dev-only",     // 开发环境自动添加标签
        "labelFormat": "[local]",    // 类名格式：css-hash-ComponentName
        "importMap": {               // 自定义导入映射
          "@emotion/styled": {
            "styled": {
              "canonicalImport": ["@emotion/styled", "default"],
              "computedStyles": ["Button"]
            }
          }
        }
      }
    ]
  ]
}

// pages/_app.tsx（Pages Router）
import { CacheProvider } from '@emotion/react'
import createCache from '@emotion/cache'
import { ThemeProvider } from '@emotion/react'
import theme from '@/theme'
 
const clientSideEmotionCache = createCache({ key: 'css' })
 
function MyApp({ Component, pageProps }) {
  return (
    <CacheProvider value={clientSideEmotionCache}>
      <ThemeProvider theme={theme}>
        <Component {...pageProps} />
      </ThemeProvider>
    </CacheProvider>
  )
}

// pages/_document.tsx（Pages Router SSR）
import { Html, Head, Main, NextScript } from 'next/document'
import createCache from '@emotion/cache'
import { renderStylesToString } from '@emotion/server'
 
export default function Document({ html, styles }) {
  return (
    <Html lang="zh-CN">
      <Head />
      <body dangerouslySetInnerHTML={{ __html: html }}>
        {styles}
        <Main />
        <NextScript />
      </body>
    </Html>
  )
}
 
Document.getInitialProps = async (ctx) => {
  const cache = createCache({ key: 'css' })
  const extractStyles = renderStylesToString
  // ... 自定义 SSR 逻辑
}

// 方式一：shouldForwardProp
const Box = styled('div', {
  shouldForwardProp: (prop) => prop !== 'isHighlighted',
})<{ isHighlighted: boolean }>`
  background: ${(props) => (props.isHighlighted ? 'yellow' : 'white')};
`
 
// 方式二：transient props（$ 前缀，Emotion 11+）
const Box = styled.div<{ $isHighlighted: boolean }>`
  background: ${(props) => (props.$isHighlighted ? 'yellow' : 'white')};
`
// $ 前缀的 props 自动不会转发到 DOM

npm install -D @emotion/babel-plugin

// theme/tokens.ts
export const tokens = {
  colors: {
    primary: { 50: '#eff6ff', 500: '#3b82f6', 900: '#1e3a8a' },
    neutral: { 50: '#fafafa', 500: '#6b7280', 900: '#111827' },
  },
  spacing: { 0: '0', 1: '4px', 2: '8px', 3: '12px', 4: '16px', 6: '24px', 8: '32px' },
  fontSizes: { xs: '12px', sm: '14px', base: '16px', lg: '18px', xl: '20px' },
  radii: { sm: '4px', md: '8px', lg: '12px', full: '9999px' },
} as const

import { css } from '@emotion/react'
 
const flexCenter = css`
  display: flex;
  align-items: center;
  justify-content: center;
`
 
const cardBase = css`
  border-radius: 8px;
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
  padding: 16px;
`
 
// 组合使用
const CenteredCard = styled.div`
  ${flexCenter};
  ${cardBase};
`

// ❌ 不好：每次渲染都创建新对象
function Bad() {
  return <div css={{ color: 'red', padding: '16px' }}>内容</div>
}
 
// ✅ 好：提取到组件外部或使用变量
const redStyle = css`
  color: red;
  padding: 16px;
`
function Good() {
  return <div css={redStyle}>内容</div>
}

// .babelrc
{
  "plugins": [
    ["@emotion", { "labelFormat": "[filename]--[local]" }]
  ]
}
// 生成类名如：css-abc123-Button--Container

import createCache from '@emotion/cache'
import { CacheProvider } from '@emotion/react'
 
// 服务端每次请求创建独立 cache，避免样式泄漏
const cache = createCache({ key: 'my-app' })
 
function App({ children }) {
  return <CacheProvider value={cache}>{children}</CacheProvider>
}

// ✅ 利用 theme 参数避免重复 useTheme
<p css={(theme) => css`color: ${theme.colors.primary};`}>
  主题色文字
</p>