@nested-grid/react-cards

JSON 驱动 CSS Grid 布局的带皮肤卡片 UI。

把布局描述为一棵普通对象树 —— columns、span、gap。引入 <NestedGridCards>，即刻得到嵌套 CSS Grid 中带样式的 <CardGroup> / <CardItem> 卡片，含标题、hover 状态、可展开内容，以及 30 个 CSS 自定义属性的主题系统。零 CSS 手写，完全可主题化。

适用于产品目录、设置面板、组织架构图、架构图、色彩 Token 面板、时间线 —— 任何该用卡片展示的层级数据。

底层引擎： @nested-grid/core — 零依赖布局引擎，从树数据计算 CSS Grid 样式。
无头替代： @nested-grid/react — 相同布局引擎，但你通过 renderItem / renderGroup / renderNode 自行控制所有样式。如需掌控每个像素，选它。

安装

pnpm add @nested-grid/react-cards

引入 CSS：

import "@nested-grid/react-cards/styles.css";

快速开始

import { NestedGridCards, type CardGridNode } from "@nested-grid/react-cards";
import "@nested-grid/react-cards/styles.css";

const nodes: CardGridNode[] = [
  {
    id: "fruits",
    title: "水果",
    children: [
      { id: "apple", title: "苹果" },
      { id: "banana", title: "香蕉" },
    ],
  },
];

function App() {
  return <NestedGridCards nodes={nodes} gap="12px" />;
}

API

<NestedGridCards>

继承 <NestedGrid> 的所有 props，包括 defaultColumns、gap、renderItem、renderGroup、renderNode、onNodeClick、className、style 以及其他根元素 HTMLAttributes<HTMLDivElement>。额外属性：

| 属性 | 类型 | 说明 | |---|---|---| | theme? | CardTheme | 卡片主题覆盖 | | showContent? | boolean | 是否默认展开所有 item 内容 | | itemOnlyGap? | string | 仅对子节点全为 item 的 group 生效的间距。用途：叶子 group 内部间距更紧凑 |

当你传入 renderItem 或 renderGroup 时，NestedGridCards 仍会先构建默认的 <CardItem> / <CardGroup>，并通过 oriNode 传给你的回调。

<CardItem>

带样式的 item 卡片。除以下属性外，还接受所有 HTMLAttributes<HTMLDivElement>：

| 属性 | 类型 | 说明 | |---|---|---| | node | CardLayoutNode<T> | 布局节点，title 和 content 在顶层 | | theme? | CardTheme | 主题覆盖，会转换为当前卡片上的 CSS 变量 | | styles? | CardStyles | 样式覆盖：header 和 body CSS 属性 | | showContent? | boolean | 展开内容体 | | titleExtra? | ReactNode \| ((state: { expanded: boolean }) => ReactNode) | 标题行附加元素 |

<CardGroup>

带样式的 group 卡片。除 children 外，接受所有 HTMLAttributes<HTMLDivElement>，另外还有：

| 属性 | 类型 | 说明 | |---|---|---| | node | CardLayoutNode<T> | 布局节点，title 在顶层 | | theme? | CardTheme | 主题覆盖，会转换为当前卡片上的 CSS 变量 | | styles? | CardStyles | 样式覆盖：header 和 body CSS 属性 | | children | ReactNode \| null | 预渲染的子节点 |

类型

| 导出 | 说明 | |---|---| | CardData | 最小数据结构，包含可选的 title 和 content | | CardGridNode<T> | 在顶层暴露 title 和 content 的 GridNode<T> 变体 | | CardLayoutNode<T> | 在顶层暴露 title 和 content 的 LayoutNode<T> 变体 | | CardStyles | 分区样式覆盖：header 和 body | | CardTheme | 被 themeToVars 和卡片组件消费的主题 token 对象 |

重导出

@nested-grid/react-cards 还会重导出：

• 来自 @nested-grid/core：createLayout、toColumns、GridNode、LayoutNode、CreateLayoutOptions
• 来自 @nested-grid/react：NestedGrid、NestedGridProps、RenderItemProps、RenderGroupProps、RenderNodeProps

CardTheme

| 字段 | 默认值 | 说明 | |---|---|---| | groupBg / groupBgEven / groupBgOdd | — | Group 背景色（按深度交替） | | groupBorder | — | Group 边框 | | groupBorderRadius | — | Group 圆角 | | groupTitleColor | — | Group 标题文字颜色 | | groupTitleFontSize / groupTitleFontWeight | — | Group 标题排版 | | groupPadding / groupHeaderPadding / groupBodyPadding | — | Group 间距 | | itemBg | — | Item 背景 | | itemBorder | — | Item 边框 | | itemBorderRadius | — | Item 圆角 | | itemShadow | — | Item 阴影 | | itemPadding | — | Item 内边距 | | itemHoverBg / itemHoverColor | — | Item hover 状态 | | itemTitleFontSize / itemTitleFontWeight | — | Item 标题排版 | | contentColor / contentFontSize / contentLineHeight | — | 可展开内容体 | | contentPaddingTop | — | 内容顶部间距 | | contentAnimDuration | — | 展开/收起动画时长 |

themeToVars(theme?)

将 CardTheme 对象转换为 CSS 自定义属性覆盖。由 NestedGridCards 内部使用。

import { themeToVars } from '@nested-grid/react-cards'

<div style={themeToVars({ groupTitleColor: '#4338ca' })}>
  <NestedGridCards nodes={nodes} />
</div>

itemOnlyGap

当 group 只包含 item（无嵌套 group）时，itemOnlyGap 覆盖默认间距。以此营造视觉层级——兄弟 group 间距大，组内 item 间距小。

<NestedGridCards
  nodes={nodes}
  gap="16px"       // group 之间的间距
  itemOnlyGap="4px" // 叶子 group 内部 item 间距
/>

更多示例

examples 目录 中有 15+ 真实布局示例 —— 定价表、看板、杂志布局、组织架构图、照片墙、色彩面板等。每个不超过 100 行。

License

MIT