react-flex-kit

轻量级的 Flexbox 布局组件库，同时支持 React (Web) 和 React Native。

特性

• 🚀 轻量 - 压缩后仅 ~4KB
• 📱 跨平台 - 同时支持 React Web 和 React Native
• 🎨 Tailwind 风格 - gap 间距系统与 Tailwind CSS 一致
• ⚡ 高性能 - 内置样式缓存和 React.memo 优化
• 🔧 可定制 - 支持自定义 gap 计算函数和默认值
• 📦 Tree-shaking - ESM 支持，按需打包

安装

# npm
npm install react-flex-kit

# yarn
yarn add react-flex-kit

# pnpm
pnpm add react-flex-kit

# bun
bun add react-flex-kit

基本使用

Web

import { Row, Col, Flex } from 'react-flex-kit';

function App() {
  return (
    <Col space={4} fullWidth>
      <Row space={2} justify="between">
        <span>Left</span>
        <span>Right</span>
      </Row>
      <Row space={2}>
        <button>Button 1</button>
        <button>Button 2</button>
        <button>Button 3</button>
      </Row>
    </Col>
  );
}

React Native

import { Row, Col, Flex } from 'react-flex-kit/native';

function App() {
  return (
    <Col space={4} fullWidth>
      <Row space={2} justify="between">
        <Text>Left</Text>
        <Text>Right</Text>
      </Row>
      <Row space={2}>
        <Button title="Button 1" />
        <Button title="Button 2" />
      </Row>
    </Col>
  );
}

组件

Row

水平方向的 Flex 容器。

<Row space={4} align="center" justify="between">
  {children}
</Row>

Col

垂直方向的 Flex 容器。

<Col space={4} align="center" justify="start">
  {children}
</Col>

Flex

通用 Flex 容器，可指定方向。

<Flex direction="row" space={4}>
  {children}
</Flex>

Props

| 属性 | 类型 | 默认值 | 说明 | | ------------ | ---------------------------- | ---------- | ------------------- | | children | ReactNode | - | 子元素 | | reverse | boolean | false | 反转子元素顺序 | | fullWidth | boolean | false | 宽度 100% | | fullHeight | boolean | false | 高度 100% | | align | FlexAlign | "center" | 交叉轴对齐 | | justify | FlexJustify | "start" | 主轴对齐 | | space | number \| string | 2 | 子元素间距 | | className | string | - | CSS 类名 (仅 Web) | | style | CSSProperties \| ViewStyle | - | 内联样式 | | direction | FlexDirection | "row" | 方向 (仅 Flex 组件) | | ref | Ref | - | 元素引用 |

FlexAlign

type FlexAlign = "start" | "center" | "end" | "stretch" | "baseline";

FlexJustify

type FlexJustify = "start" | "center" | "end" | "between" | "around" | "evenly";

FlexDirection

type FlexDirection = "row" | "row-reverse" | "column" | "column-reverse";

间距系统

space 属性遵循 Tailwind CSS 的间距系统：

| space | Web | React Native | | -------- | ------- | ------------ | | 1 | 0.25rem | 4px | | 2 | 0.5rem | 8px | | 4 | 1rem | 16px | | 8 | 2rem | 32px | | "20px" | 20px | - |

自定义配置

使用 createFlexComponents 创建自定义配置的组件：

Web

import { createFlexComponents } from 'react-flex-kit';

export const { Row, Col, Flex } = createFlexComponents({
  // 自定义 gap 计算函数
  gapCalculator: (space) => `${space * 4}px`,
  // 默认间距
  defaultSpace: 4,
  // 默认对齐
  defaultAlign: "start",
  // 默认主轴对齐
  defaultJustify: "start",
});

React Native (使用 nativewind-scale)

import { scale } from '@flickering/nativewind-scale';
import { createFlexComponents } from 'react-flex-kit/native';

export const { Row, Col, Flex } = createFlexComponents({
  // 使用响应式缩放
  gapCalculator: (space) => scale(space),
  defaultSpace: 8,
});

样式优先级

组件 props > 内联 style > className (Tailwind)

// fullWidth 会覆盖 style 的 width
<Row fullWidth style={{ width: "50%" }}>
  {/* width: 100% (fullWidth 优先) */}
</Row>

// style 中不冲突的属性会保留
<Row fullWidth style={{ padding: "10px" }}>
  {/* width: 100%, padding: 10px */}
</Row>

// 组件 props 生成的内联样式会覆盖 Tailwind 类
<Row className="gap-2" space={4}>
  {/* gap: 1rem (space={4}) 覆盖 gap-2 */}
</Row>

HTML 属性透传

组件支持所有原生 HTML/View 属性：

// Web
<Row
  data-testid="my-row"
  aria-label="Row container"
  onClick={() => console.log('clicked')}
>
  {children}
</Row>

// React Native
<Row
  testID="my-row"
  accessibilityLabel="Row container"
  onLayout={(e) => console.log(e)}
>
  {children}
</Row>

TypeScript

完整的类型支持：

import type {
  FlexLayoutProps,
  FlexProps,
  FlexAlign,
  FlexJustify,
  FlexDirection,
  FlexConfig,
} from 'react-flex-kit';

// React Native
import type {
  NativeFlexLayoutProps,
  NativeFlexProps,
} from 'react-flex-kit/native';

兼容性

• React 17+
• React Native 0.60+
• TypeScript 4.7+

License

MIT