React组件开发中的TypeScript联合类型实践

1. React组件中的联合类型：为什么需要它？

在React组件开发中，我们经常会遇到这样的场景：一个组件的props可能需要接受多种不同类型的值。比如一个Button组件，它的size属性可能既可以是字符串'small' | 'medium' | 'large'，也可以是数字1 | 2 | 3。这就是典型的联合类型(Union Types)应用场景。

联合类型(TypeScript中的|操作符)允许我们将多个类型组合成一个类型，表示值可以是这些类型中的任意一种。在React中，这种类型处理尤为重要，因为：

1. 组件复用性：一个设计良好的组件应该能适应不同使用场景
2. API灵活性：给使用者更多选择，同时保持类型安全
3. 渐进式类型：可以逐步为现有JavaScript组件添加类型约束

我曾在实际项目中遇到过这样的情况：一个Icon组件最初只接受字符串类型的图标名称，后来需求变更需要同时支持传递React节点。如果没有使用联合类型，要么需要创建新组件，要么会失去类型检查的好处。

2. 基础联合类型处理模式

2.1 简单的值联合

最基本的联合类型就是一组固定值的联合：

typescript复制type Size = 'small' | 'medium' | 'large';

interface ButtonProps {
  size?: Size;
  // ...
}

这种模式适用于明确知道所有可能值的场景。在组件内部使用时，TypeScript会自动进行类型收窄：

typescript复制function Button({ size = 'medium' }: ButtonProps) {
  const padding = {
    small: '4px 8px',
    medium: '8px 16px',
    large: '12px 24px'
  }[size];
  
  return <button style={{ padding }}>...</button>;
}

2.2 类型联合

更复杂的情况是不同的类型联合：

typescript复制type IconProp = string | React.ReactNode;

interface IconButtonProps {
  icon: IconProp;
  // ...
}

处理这种联合类型时，通常需要使用类型守卫：

typescript复制function IconButton({ icon }: IconButtonProps) {
  return (
    <button>
      {typeof icon === 'string' ? (
        <span className={`icon-${icon}`} />
      ) : (
        icon
      )}
    </button>
  );
}

2.3 带判别属性的联合

对于更复杂的对象联合，推荐使用判别属性模式：

typescript复制type ModalProps =
  | {
      type: 'alert';
      message: string;
      onConfirm: () => void;
    }
  | {
      type: 'confirm';
      message: string;
      onConfirm: () => void;
      onCancel: () => void;
    };

function Modal(props: ModalProps) {
  switch (props.type) {
    case 'alert':
      return (
        <div>
          <p>{props.message}</p>
          <button onClick={props.onConfirm}>OK</button>
        </div>
      );
    case 'confirm':
      return (
        <div>
          <p>{props.message}</p>
          <button onClick={props.onConfirm}>Confirm</button>
          <button onClick={props.onCancel}>Cancel</button>
        </div>
      );
  }
}

这种模式利用了TypeScript的判别联合特性，在switch分支中会自动收窄类型。

3. 高级联合类型技巧

3.1 泛型与联合类型的结合

当组件需要保持某种类型一致性时，可以结合泛型：

typescript复制interface ListProps<T extends string | number> {
  items: T[];
  renderItem: (item: T) => React.ReactNode;
}

function List<T extends string | number>({ items, renderItem }: ListProps<T>) {
  return (
    <ul>
      {items.map((item, index) => (
        <li key={typeof item === 'string' ? item : index}>
          {renderItem(item)}
        </li>
      ))}
    </ul>
  );
}

3.2 条件类型处理

使用TypeScript的条件类型可以创建更灵活的联合类型：

typescript复制type ResponsiveProp<T> = T | { sm?: T; md: T; lg?: T };

interface GridProps {
  columns: ResponsiveProp<number>;
}

function Grid({ columns }: GridProps) {
  // 处理逻辑
}

3.3 类型谓词函数

对于复杂的类型判断，可以定义类型谓词函数：

typescript复制function isFunctionComponent(
  component: React.ReactNode | React.ComponentType
): component is React.ComponentType {
  return typeof component === 'function';
}

function RenderComponent({ component }: { component: React.ReactNode | React.ComponentType }) {
  return isFunctionComponent(component) ? React.createElement(component) : component;
}

4. 实战中的常见问题与解决方案

4.1 类型收窄失败

有时TypeScript无法正确收窄联合类型，特别是在回调函数中：

typescript复制type Item = { type: 'image'; src: string } | { type: 'video'; url: string };

function Gallery({ items }: { items: Item[] }) {
  const handleClick = (item: Item) => {
    // 这里item.type不会被自动收窄
    if (item.type === 'image') {
      console.log(item.src); // OK
    } else {
      console.log(item.url); // OK
    }
  };
  
  return items.map((item) => (
    <div key={item.type === 'image' ? item.src : item.url} onClick={() => handleClick(item)}>
      {/* ... */}
    </div>
  ));
}

解决方案是使用类型断言或重新定义变量：

typescript复制const handleClick = (item: Item) => {
  const narrowedItem = item; // 创建新变量帮助类型收窄
  if (narrowedItem.type === 'image') {
    console.log(narrowedItem.src);
  } else {
    console.log(narrowedItem.url);
  }
};

4.2 默认值处理

为联合类型的props设置默认值时需要小心：

typescript复制type TextValue = string | number;

interface TextFieldProps {
  value: TextValue;
  onChange: (value: TextValue) => void;
}

// 错误做法：默认值可能不符合所有类型
function TextField({ value = '', onChange }: TextFieldProps) {
  // ...
}

// 正确做法：使用重载或更明确的类型
interface TextFieldProps {
  value?: TextValue;
  onChange: (value: TextValue) => void;
  defaultValue?: TextValue;
}

4.3 性能考虑

复杂的联合类型可能会影响TypeScript的编译性能，特别是在大型项目中。如果发现类型检查变慢，可以考虑：

1. 将复杂的联合类型提取为单独的类型别名
2. 避免过度嵌套的联合类型
3. 使用interface而不是type来定义对象联合（在某些TypeScript版本中性能更好）

5. 与其他React特性的结合

5.1 联合类型与Hooks

在自定义Hook中使用联合类型：

typescript复制function useToggle(initialValue: boolean | (() => boolean)): [boolean, () => void] {
  const [value, setValue] = React.useState(initialValue);
  
  const toggle = React.useCallback(() => {
    setValue(prev => !prev);
  }, []);
  
  return [value, toggle];
}

5.2 Context中的联合类型

在Context中使用联合类型时，需要注意默认值处理：

typescript复制type Theme = 'light' | 'dark' | 'system';

const ThemeContext = React.createContext<{
  theme: Theme;
  setTheme: (theme: Theme) => void;
} | null>(null);

function ThemeProvider({ children }: { children: React.ReactNode }) {
  const [theme, setTheme] = React.useState<Theme>('light');
  
  return (
    <ThemeContext.Provider value={{ theme, setTheme }}>
      {children}
    </ThemeContext.Provider>
  );
}

function useTheme() {
  const context = React.useContext(ThemeContext);
  if (!context) {
    throw new Error('useTheme must be used within a ThemeProvider');
  }
  return context;
}

5.3 高阶组件中的类型处理

创建处理联合类型的高阶组件：

typescript复制function withLoading<P>(
  Component: React.ComponentType<P>,
  options?: { delay?: number }
): React.ComponentType<P & { isLoading?: boolean | { delay: number } }> {
  return function WithLoading(props) {
    const { isLoading, ...rest } = props;
    
    const [showLoading, setShowLoading] = React.useState(false);
    
    React.useEffect(() => {
      if (typeof isLoading === 'object') {
        const timer = setTimeout(() => {
          setShowLoading(true);
        }, isLoading.delay);
        return () => clearTimeout(timer);
      } else {
        setShowLoading(!!isLoading);
      }
    }, [isLoading]);
    
    return showLoading ? <div>Loading...</div> : <Component {...rest as P} />;
  };
}

6. 测试策略与类型安全

6.1 测试组件处理不同联合类型

使用Jest测试联合类型处理：

typescript复制describe('Button component', () => {
  it('should handle all size variants', () => {
    const sizes: Array<'small' | 'medium' | 'large'> = ['small', 'medium', 'large'];
    
    sizes.forEach(size => {
      render(<Button size={size} />);
      expect(screen.getByRole('button')).toHaveStyle({
        padding: expect.any(String)
      });
    });
  });
  
  it('should default to medium size', () => {
    render(<Button />);
    expect(screen.getByRole('button')).toHaveStyle({
      padding: '8px 16px'
    });
  });
});

6.2 类型测试工具

使用@ts-expect-error注释来测试类型错误：

typescript复制// 正确的使用应该没有类型错误
<Button size="medium" />

// 测试不正确的类型应该被捕获
// @ts-expect-error
<Button size="extra-large" />

6.3 运行时类型检查

对于来自外部API的数据，可能需要运行时验证：

typescript复制function isSize(value: unknown): value is 'small' | 'medium' | 'large' {
  return ['small', 'medium', 'large'].includes(value as string);
}

function Button({ size = 'medium' }: { size?: unknown }) {
  const validSize = isSize(size) ? size : 'medium';
  
  // ...使用validSize
}

7. 工程化最佳实践

7.1 类型组织策略

在大型项目中，建议这样组织联合类型：

code复制src/
  components/
    Button/
      types.ts  # 导出Button相关的所有类型
    types/
      common.ts # 全局共享的联合类型

7.2 文档化联合类型

使用TSDoc注释增强可读性：

typescript复制/**
 * 按钮尺寸选项
 * @default 'medium'
 */
export type ButtonSize = 'small' | 'medium' | 'large';

interface ButtonProps {
  /**
   * 控制按钮尺寸
   * @example
   * <Button size="large" />
   */
  size?: ButtonSize;
}

7.3 类型版本控制

当联合类型需要扩展时，考虑兼容性：

typescript复制// v1
type IconSize = 'sm' | 'md' | 'lg';

// v2 - 向后兼容的方式
type IconSize = 'sm' | 'md' | 'lg' | number;

7.4 性能优化

对于频繁使用的联合类型，可以使用const enum优化：

typescript复制const enum Size {
  Small = 'small',
  Medium = 'medium',
  Large = 'large'
}

interface Props {
  size?: Size;
}

这种用法会在编译时内联，减少运行时开销。