@dcg-overseas/equal-split

等分图形（Equal Split）分数学习组件。只负责图形区域的渲染：将形状等分成 N 份并给指定分块着色。分数面板、英文读法等周边 UI 由使用方自行实现（可借助包导出的工具函数）。

安装

pnpm add @dcg-overseas/equal-split

使用

import {
  EqualSplit,
  useEqualSplit,
  getFractionWords,
} from '@dcg-overseas/equal-split'

export default function App() {
  const eq = useEqualSplit()

  return (
    <div>
      {/* 使用方自己实现选择器 / 分数面板 / 英文读法等 UI */}
      <EqualSplit
        shape={eq.shape}
        parts={eq.parts}
        coloredParts={eq.coloredParts}
        className="w-[420px] aspect-square"
      />
      <p>{getFractionWords(eq.coloredCount, eq.parts ?? 0)}</p>
    </div>
  )
}

EqualSplit Props

| Prop | 类型 | 说明 | |------|------|------| | shape | ShapeType \| null | 当前形状；null 时显示 "Select shape" 占位 | | parts | number \| null | 等分数；null 时只绘制形状轮廓 | | coloredParts | number[] | 着色分块的索引（从 0 开始） | | className | string? | 外层容器类名，尺寸由使用方控制（组件内 SVG 自适应填满容器） |

useEqualSplit

管理 形状 → 等分数 → 着色数 的三级级联状态（上游变化自动重置下游），返回：

| 字段 | 说明 | |------|------| | shape / parts / coloredParts | 当前状态，直接透传给 <EqualSplit /> | | coloredCount | 已着色块数（分子） | | setShape / setParts / setColoredCount | 状态 setter；setColoredCount(n) 着色前 n 块 | | shapeOptions | 形状选项列表 | | partsOptions | 当前形状支持的等分数选项 | | coloredOptions | 可选着色数（1 ~ parts） | | strokeColor | 当前形状的描边色 |

其他导出

| 名称 | 说明 | |------|------| | SHAPES | 形状列表 { id, label }[] | | SHAPE_PARTS | 各形状支持的等分数白名单 | | SHAPE_STROKES / SHAPE_COLORS | 各形状的描边/填充色 | | getFractionWords(num, den) | 分数英文读法（如 three fourths、one whole） | | useResponsiveScale(w, h?) | 固定设计稿等比缩放 hook，返回 { containerRef, scale } |

支持的等分数

| 形状 | 可选等分数 | |------|-----------| | Circle | 2, 3, 4, 5, 6, 8, 10 | | Triangle | 2, 3, 4, 6 | | Square | 2, 3, 4, 5, 6, 8, 9, 10 | | Rectangle | 2, 3, 4, 5, 6, 7, 8, 10, 12 | | Pentagon | 2, 5, 10 | | Hexagon | 2, 6, 12 |

文件结构

src/
├── constants.ts          # 类型、常量、分数英文转换函数
├── geometry.ts           # SVG 路径计算（各形状等分逻辑）
├── ShapeCanvas.tsx       # SVG 画布渲染
├── useEqualSplit.ts      # 级联状态 hook
├── useResponsiveScale.ts # 等比缩放 hook
└── EqualSplitIndex.tsx   # 主组件（纯展示）