hexagonal 0.0.2

A powerful Flutter package for creating hexagonal UI layouts with grid system, free layout, pattern generators, and boundary-aware generation.

0.0.1 Initial Release

✨ 核心功能

网格布局系统

• 支持尖顶朝上（pointy）和平顶朝上（flat）两种六边形方向
• 灵活的网格配置：行数、列数、六边形尺寸
• 可自定义网格样式：颜色、边框、间距
• 支持 Widget 占据多个网格单元
• 多种自动布局策略：线性、蛇形、环形、对角线
• 交互支持：点击、长按、悬停、拖拽
• 基于立方体坐标系统的数学运算

自由布局系统

• 不依赖网格，在任意像素位置放置六边形
• 每个六边形可以有不同尺寸
• 边对边精确相邻，可控间隙
• 图案生成器：蜂巢、环形、线性、螺旋、蛇形、Z字形

增强功能

• 丰富的填充样式：纯色、渐变、图片、自定义图案
• 可配置边框：颜色、宽度、连接样式
• 点击动画：Scale、Ripple、Bounce、Glow
• 多种交互：点击、长按、双击、悬停
• 视觉效果：阴影、透明度控制

边界蛇形生成

• createSnakeWithBounds(): 带边界约束的智能蛇形生成
• 参数：
  • direction: 生成方向（'up', 'down', 'left', 'right'）
  • clockwise: 生成顺序（true=顺时针, false=逆时针）
• 光线反射式转向逻辑：
  • 水平边界（上/下）：60° 反射（±1）
  • 垂直边界（左/右）：120° 反射（±2）
• 动态边界检测，智能选择转向方向

数据驱动生成

• DataDrivenHexGenerator.generate(): 从数据数组生成布局
• 支持所有图案类型
• 自定义 hexBuilder 构建每个六边形
• 支持边界约束

🧪 测试覆盖

• 32 个单元测试全部通过 ✅
• 包含边界检测、转向逻辑、图案生成等测试

📦 API 导出

• lib/hexagonal.dart: 统一导出所有模块
• 模块：core, grid, widgets, layout, free_layout, enhanced features

---

0.0.3 (历史版本)

🐛 Bug 修复

• 修复动画点击无反应的问题
  • 修改 EnhancedHexagonRenderer：即使没有回调，只要有动画也添加手势检测
  • 确保 Ripple 动画正确触发（forward 后自动 reverse）
  • 所有 5 种动画现在都能正确响应点击

🆕 新增功能

边界回折蛇形模式

• SnakePatternGenerator.createSnakeWithBounds(): 带边界约束的蛇形生成

  • bounds: 边界矩形（Rect）
  • initialDirection: 初始方向（0-5，对应六边形的6个边）
  • turnDirection: 转向方向（1=右转，-1=左转）
  • 自动检测边界并转向
  • 当所有方向都超界时停止生成

• HexLayoutPattern.snakeBounded: 新的布局模式

  • 在数据驱动生成器中支持边界回折
  • 自动在边界内填充六边形
  • 适合填充固定区域

蛇形图案参数扩展

• snakeInitialDirection: 蛇形起始方向（0-5）
  • 0: 右边（Right）
  • 1: 右下（Down-Right）
  • 2: 左下（Down-Left）
  • 3: 左边（Left）
  • 4: 左上（Up-Left）
  • 5: 右上（Up-Right）
• snakeTurnDirection: 碰到边界时的转向方向（1=右转，-1=左转）

📝 示例更新

• enhanced_example.dart 蛇形图案页面：
  • 添加 "Bounded" 模式选择
  • 为边界模式添加方向选择器
  • 为边界模式添加转向方向选择（左转/右转）
  • 边界模式支持最多 50 个六边形
  • 实时可视化边界约束效果

🧪 测试

• 新增 snake_bounds_test.dart（6个测试用例）
  • 边界检测
  • 转向行为
  • 左转/右转对比
  • 初始方向验证
  • 数据驱动集成
  • 边界过小时的停止逻辑
• 总测试数: 32 个（全部通过 ✅）

---

0.0.2

🌟 增强功能 (Enhanced Features)

新增组件

• EnhancedFreeHexWidget: 增强版六边形配置类

  • 支持多种填充样式：纯色、渐变、图片、自定义图案
  • 可配置边框样式：颜色、宽度、连接样式
  • 多种点击动画：None、Scale、Ripple、Bounce、Glow
  • 丰富的回调：onTap、onLongPress、onDoubleTap、onHover
  • 视觉效果：阴影、透明度控制

• EnhancedHexagonRenderer: 增强版渲染器

  • StatefulWidget，支持动画控制
  • 实现所有填充样式的渲染
  • 自定义 Painters：边框、涟漪、发光效果
  • 手势检测和悬停支持

填充样式

• SolidColorFill: 纯色填充
• GradientFill: 渐变填充（支持所有 Flutter Gradient 类型）
• ImageFill: 图片填充（支持 ImageProvider 和 BoxFit）
• PatternFill: 自定义图案填充（使用 Widget）

边框样式

• HexBorderStyle: 可配置颜色、宽度、连接样式
• 支持 StrokeJoin.miter/round/bevel

点击动画

• HexClickAnimation.none: 无动画
• HexClickAnimation.scale: 缩放动画
• HexClickAnimation.ripple: 涟漪扩散动画
• HexClickAnimation.bounce: 弹跳动画
• HexClickAnimation.glow: 发光动画

蛇形图案生成器

• SnakePatternGenerator: 静态工具类
  • createSnake(): 创建蛇形图案
    • 支持 bendFactor 参数（0.0 = 直线，1.0 = 最大弯曲）
    • 可指定起始方向
    • 自动左右交替转向
  • createSpiralSnake(): 创建螺旋蛇形
    • 从中心向外螺旋扩展
    • tightness 参数控制螺旋紧密度
    • 段长度自动递增
  • createZigZag(): 创建 Z 字形图案
    • 可配置宽度和高度
    • 水平和垂直方向交替

数据驱动生成器

• DataDrivenHexGenerator: 从数据数组生成六边形

  • generate(): 主生成方法
  • 支持泛型数据类型 <T>
  • hexBuilder 回调：将数据映射到六边形配置

• DataDrivenHexConfig: 配置类

  • data: 数据列表
  • pattern: 布局模式
  • hexBuilder: 数据到六边形的转换函数
  • 支持所有布局参数（大小、间隙、方向等）

布局模式

• HexLayoutPattern.linear: 线性排列
• HexLayoutPattern.ring: 环形排列
• HexLayoutPattern.honeycomb: 蜂巢结构
• HexLayoutPattern.snake: 蛇形图案
• HexLayoutPattern.spiral: 螺旋图案
• HexLayoutPattern.zigzag: Z 字形图案

新示例

• enhanced_example.dart: 增强功能完整示例
  • Fill Styles: 展示所有填充样式
  • Animations: 展示所有动画效果
  • Snake Patterns: 交互式调节蛇形图案
  • Data Driven: 实际应用示例（用户分数排行榜）

🐛 Bug 修复

• 修复自由布局相邻算法的关键 bug
  • getEdgeNormal(): 修正法向量方向（逆时针 → 顺时针）
  • calculateAdjacentCenter(): 修正距离计算（从边中点出发，只需 targetApothem + gap）

📝 文档更新

• README.md: 添加增强功能详细说明和示例
• 导出所有新组件到主包

---

0.0.1

初始版本

核心功能

• ✨ 六边形网格生成和渲染
• 📐 支持尖顶朝上 (Pointy-top) 和平顶朝上 (Flat-top) 两种方向
• 🧮 基于立方体坐标系统 (Cube Coordinates) 的数学运算
• 🔄 坐标转换：立方体坐标 ↔ 偏移坐标
• ✂️ 新增: Widget 可裁剪为六边形形状 (clipToHexShape 参数)
• 🎨 默认方向: 网格默认使用平顶朝上 (Flat-top) 方向

网格配置

• 可配置的网格尺寸（行数、列数、六边形大小）
• 可自定义的视觉样式（网格线颜色、宽度、填充色、间距等）
• 默认配置：根据窗口大小自动计算六边形尺寸

Widget 布局

• 支持 Widget 占据单个或多个网格单元
• Widget 可跨越任意数量的行和列（spanWidth、spanHeight）
• 自动计算和管理 Widget 占用的网格单元

自动布局策略

• LinearLayoutStrategy: 线性布局（从左到右、从上到下）
• SnakeLayoutStrategy: 蛇形布局（每行交替方向）
• RingLayoutStrategy: 环形布局（从中心螺旋向外）
• DiagonalLayoutStrategy: 对角线布局（沿对角线填充）

交互功能

• 🖱️ 单元格点击事件 (onCellTap)
• 👆 单元格长按事件 (onCellLongPress)
• 🎯 单元格悬停事件 (onCellHover)

🆕 自由布局系统 (Free Layout)

• FreeHexagon: 不依赖网格的自由六边形类

  • 支持任意像素位置 (center: Offset)
  • 支持任意大小 (size: double)
  • 支持旋转 (rotation: double)
  • 提供顶点、边中点、边法向量等几何计算

• HexagonLayoutHelper: 布局辅助工具类

  • calculateAdjacentCenter(): 计算边对边相邻六边形的位置（支持间隙控制）
  • createRing(): 生成环形排列（6个六边形围绕中心）
  • createLine(): 生成线性排列（支持不同大小）
  • createHoneycomb(): 生成蜂巢图案（多环结构）
  • isOverlapping(): 检测六边形碰撞
  • containsPoint(): 点是否在六边形内

• FreeHexWidget: 自由布局 Widget 包装器

  • 与 HexWidget 类似的功能
  • 基于 FreeHexagon 而非网格坐标
  • 支持裁剪、拖拽、点击等交互

• FreeHexagonCanvas: 自由布局画布

  • 显示和管理多个自由六边形
  • 支持悬停、点击事件
  • 可选显示边框
  • 自动处理层级和定位

• 应用场景:

  • 艺术设计和自由创作
  • 不规则蜂巢布局
  • 有机生长型图案
  • 需要精确控制间隙的场景
  • 不同尺寸六边形混合布局

🎮 交互式示例

• 新增第5个示例: 交互式参数控制面板

  • 实时调整蜂巢环数（1-5环）
  • 实时调整六边形大小（20-80px）
  • 实时调整间隙（0-20px）
  • 三种布局模式切换：蜂巢、环形、线性
  • 显示实时统计信息（六边形总数）
  • 提供完整的交互式指南文档

• 🔀 Widget 拖拽支持 (draggable)

• 单元格选中状态管理

工具类

• HexMath: 六边形数学运算（距离计算、路径查找等）
• HexLayout: 坐标系统与像素坐标的转换
• HexGridBuilder: 简化网格创建的构建器类

组件

• HexagonalGrid: 主网格 Widget 组件
• HexWidget: Widget 包装器
• HexCell: 单元格数据模型
• HexGridConfig: 网格配置类
• HexGridPainter: 自定义绘制器

示例

• 网格布局: 5个示例（空网格、自动布局、手动布局、交互式网格、裁剪）
• 自由布局: 5个示例（基础、相邻、蜂巢、尺寸、🎮交互式控制）
• 详细的 API 文档和使用说明
• 交互式指南文档 (INTERACTIVE_GUIDE.md)