Hexagonal

pub package License: MIT

A powerful Flutter package for creating hexagonal UI layouts with extensive customization options.

English | 中文

English

Features

  • 🎨 Grid Layout System: Traditional hexagon grid with coordinate system
  • � Free Layout System: Place hexagons freely at any pixel position
  • 🌟 Enhanced Features: Rich fill styles, animations, and interactive effects
  • � Pattern Generators: Snake, spiral, zigzag, honeycomb patterns
  • � Data-Driven: Generate layouts directly from data arrays
  • � Bounded Generation: Smart boundary detection with reflection-like turning

Installation

Add to your pubspec.yaml:

dependencies:
  hexagonal: ^0.0.1

Quick Start

1. Simple Grid Layout

import 'package:hexagonal/hexagonal.dart';

HexGridBuilder.emptyGrid(
  containerSize: Size(400, 400),
  columns: 5,
  rows: 5,
  onCellTap: (coordinate) => print('Tapped: $coordinate'),
)

2. Free Layout with Pattern

import 'package:hexagonal/hexagonal.dart';

// Create a honeycomb pattern
final hexagons = SnakePatternGenerator.createHoneycomb(
  center: FreeHexagon(
    id: 'center',
    center: Offset(200, 200),
    size: 30,
  ),
  rings: 2,
  size: 30,
);

// Render
Stack(
  children: hexagons.map((hex) => 
    Positioned(
      left: hex.center.dx - hex.size,
      top: hex.center.dy - hex.size,
      child: FreeHexWidget(hexagon: hex),
    ),
  ).toList(),
)

3. Enhanced Features with Animations

EnhancedFreeHexWidget(
  id: 'hex1',
  hexagon: FreeHexagon(
    id: 'hex1',
    center: Offset(100, 100),
    size: 40,
  ),
  fillStyle: GradientFill(
    LinearGradient(
      colors: [Colors.blue, Colors.purple],
    ),
  ),
  clickAnimation: HexClickAnimation.ripple,
  onTap: () => print('Tapped!'),
)

4. Data-Driven Generation

final data = [
  {'name': 'Alice', 'score': 95},
  {'name': 'Bob', 'score': 87},
  {'name': 'Carol', 'score': 92},
];

final hexWidgets = DataDrivenHexGenerator.generate(
  DataDrivenHexConfig(
    data: data,
    pattern: HexLayoutPattern.honeycomb,
    startPosition: Offset(200, 200),
    hexSize: 50,
    hexBuilder: (item, hex, index) {
      return EnhancedFreeHexWidget(
        id: hex.id,
        hexagon: hex,
        fillStyle: SolidColorFill(Colors.blue),
        child: Text(item['name']),
      );
    },
  ),
);

5. Bounded Snake Pattern

DataDrivenHexGenerator.generate(
  DataDrivenHexConfig(
    data: List.generate(30, (i) => i),
    pattern: HexLayoutPattern.snakeBounded,
    bounds: Rect.fromLTWH(50, 50, 600, 400),
    direction: 'right',      // up, down, left, right
    clockwise: true,         // generation order
    hexSize: 30,
    hexBuilder: (value, hex, index) {
      return EnhancedFreeHexWidget(
        id: hex.id,
        hexagon: hex,
        fillStyle: SolidColorFill(Colors.primaries[index % Colors.primaries.length]),
      );
    },
  ),
)

Key Concepts

Generation Direction

  • up: Generates upward, starts at bottom center
  • down: Generates downward, starts at top center
  • left: Generates leftward, starts at right center
  • right: Generates rightward, starts at left center

Generation Order

  • clockwise: First hexagon connects in clockwise direction
  • counter-clockwise: First hexagon connects in counter-clockwise direction

Boundary Reflection

When a hexagon hits a boundary, it reflects like light:

  • Horizontal boundaries (top/bottom): 60° reflection
  • Vertical boundaries (left/right): 120° reflection

Available Patterns

  • HexLayoutPattern.linear - Linear arrangement
  • HexLayoutPattern.snake - Snake pattern with bend factor
  • HexLayoutPattern.spiral - Spiral pattern
  • HexLayoutPattern.ring - Ring arrangement
  • HexLayoutPattern.honeycomb - Honeycomb structure
  • HexLayoutPattern.zigzag - Zigzag pattern
  • HexLayoutPattern.snakeBounded - Bounded snake with smart turning

Click Animations

  • HexClickAnimation.none - No animation
  • HexClickAnimation.scale - Scale effect
  • HexClickAnimation.ripple - Ripple effect
  • HexClickAnimation.bounce - Bounce effect
  • HexClickAnimation.glow - Glow effect

Fill Styles

  • SolidColorFill(Color) - Solid color
  • GradientFill(Gradient) - Gradient fill
  • PatternFill(Widget) - Custom pattern widget
  • ImageFill(ImageProvider) - Image fill

Examples

Check out the /example folder for complete working examples.

Documentation

For detailed API documentation, visit pub.dev/documentation/hexagonal

License

MIT License - see LICENSE file for details

中文

功能特性

  • 🎨 网格布局系统：传统六边形网格，带坐标系统
  • 🆓 自由布局系统：在任意像素位置自由放置六边形
  • 🌟 增强功能：丰富的填充样式、动画和交互效果
  • 🐍 图案生成器：蛇形、螺旋、锯齿、蜂巢图案
  • 📊 数据驱动：直接从数据数组生成布局
  • 🎯 边界生成：智能边界检测，类似光线反射的转向

安装

在 pubspec.yaml 中添加：

dependencies:
  hexagonal: ^0.0.1

快速开始

1. 简单网格布局

import 'package:hexagonal/hexagonal.dart';

HexGridBuilder.emptyGrid(
  containerSize: Size(400, 400),
  columns: 5,
  rows: 5,
  onCellTap: (coordinate) => print('点击: $coordinate'),
)

2. 自由布局图案

import 'package:hexagonal/hexagonal.dart';

// 创建蜂巢图案
final hexagons = SnakePatternGenerator.createHoneycomb(
  center: FreeHexagon(
    id: 'center',
    center: Offset(200, 200),
    size: 30,
  ),
  rings: 2,
  size: 30,
);

// 渲染
Stack(
  children: hexagons.map((hex) => 
    Positioned(
      left: hex.center.dx - hex.size,
      top: hex.center.dy - hex.size,
      child: FreeHexWidget(hexagon: hex),
    ),
  ).toList(),
)

3. 增强功能与动画

EnhancedFreeHexWidget(
  id: 'hex1',
  hexagon: FreeHexagon(
    id: 'hex1',
    center: Offset(100, 100),
    size: 40,
  ),
  fillStyle: GradientFill(
    LinearGradient(
      colors: [Colors.blue, Colors.purple],
    ),
  ),
  clickAnimation: HexClickAnimation.ripple,
  onTap: () => print('已点击！'),
)

4. 数据驱动生成

final data = [
  {'name': '张三', 'score': 95},
  {'name': '李四', 'score': 87},
  {'name': '王五', 'score': 92},
];

final hexWidgets = DataDrivenHexGenerator.generate(
  DataDrivenHexConfig(
    data: data,
    pattern: HexLayoutPattern.honeycomb,
    startPosition: Offset(200, 200),
    hexSize: 50,
    hexBuilder: (item, hex, index) {
      return EnhancedFreeHexWidget(
        id: hex.id,
        hexagon: hex,
        fillStyle: SolidColorFill(Colors.blue),
        child: Text(item['name']),
      );
    },
  ),
);

5. 边界蛇形图案

DataDrivenHexGenerator.generate(
  DataDrivenHexConfig(
    data: List.generate(30, (i) => i),
    pattern: HexLayoutPattern.snakeBounded,
    bounds: Rect.fromLTWH(50, 50, 600, 400),
    direction: 'right',      // up(上), down(下), left(左), right(右)
    clockwise: true,         // 生成顺序
    hexSize: 30,
    hexBuilder: (value, hex, index) {
      return EnhancedFreeHexWidget(
        id: hex.id,
        hexagon: hex,
        fillStyle: SolidColorFill(Colors.primaries[index % Colors.primaries.length]),
      );
    },
  ),
)

核心概念

生成方向

  • up（上）：向上生成，起始位置在底部中心
  • down（下）：向下生成，起始位置在顶部中心
  • left（左）：向左生成，起始位置在右侧中心
  • right（右）：向右生成，起始位置在左侧中心

生成顺序

  • clockwise（顺时针）：第一个六边形按顺时针方向连接
  • counter-clockwise（逆时针）：第一个六边形按逆时针方向连接

边界反射

当六边形碰到边界时，会像光线一样反射：

  • 水平边界（上/下）：60° 反射
  • 垂直边界（左/右）：120° 反射

可用图案

  • HexLayoutPattern.linear - 线性排列
  • HexLayoutPattern.snake - 蛇形图案（可配置弯折系数）
  • HexLayoutPattern.spiral - 螺旋图案
  • HexLayoutPattern.ring - 环形排列
  • HexLayoutPattern.honeycomb - 蜂巢结构
  • HexLayoutPattern.zigzag - 锯齿图案
  • HexLayoutPattern.snakeBounded - 边界蛇形（智能转向）

点击动画

  • HexClickAnimation.none - 无动画
  • HexClickAnimation.scale - 缩放效果
  • HexClickAnimation.ripple - 涟漪效果
  • HexClickAnimation.bounce - 弹跳效果
  • HexClickAnimation.glow - 发光效果

填充样式

  • SolidColorFill(Color) - 纯色填充
  • GradientFill(Gradient) - 渐变填充
  • PatternFill(Widget) - 自定义图案
  • ImageFill(ImageProvider) - 图片填充

示例

查看 /example 文件夹获取完整示例。

文档

详细 API 文档请访问 pub.dev/documentation/hexagonal

许可证

MIT 许可证 - 详见 LICENSE 文件

坐标系统

本包使用立方体坐标系统（Cube Coordinates），满足约束 x + y + z = 0。同时支持与偏移坐标（Offset Coordinates）的转换。

// 创建坐标
final coord = HexCoordinate.fromOffsetPointy(2, 3);

// 坐标运算
final neighbor = coord.neighbor(0);
final distance = coord.distanceTo(neighbor); // 1

// 获取环形区域
final ring = coord.ring(2);
final spiral = coord.spiral(3);

布局策略

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

Widget 放置

Widget 可以占据多个网格单元，通过 spanWidth 和 spanHeight 控制：

HexWidget(
  id: 'large_widget',
  child: YourWidget(),
  position: HexCoordinate.fromOffsetPointy(0, 0),
  spanWidth: 3,  // 占据 3 列
  spanHeight: 2, // 占据 2 行
)

🆕 自由布局快速开始

自由布局系统允许你在不使用网格的情况下，自由放置不同尺寸的六边形。

1. 基础自由布局

import 'package:hexagonal/hexagonal.dart';

// 创建任意位置、任意大小的六边形
final hex1 = FreeHexagon(
  id: 'hex1',
  center: Offset(100, 100),  // 像素坐标
  size: 50,                   // 半径
);

final hex2 = FreeHexagon(
  id: 'hex2',
  center: Offset(250, 120),
  size: 70,                   // 不同的大小
);

// 包装成 Widget
final hexWidgets = [
  FreeHexWidget(
    id: 'widget1',
    hexagon: hex1,
    child: Icon(Icons.star, color: Colors.white),
    backgroundColor: Colors.blue,
    clipToHexShape: true,     // 裁剪为六边形
  ),
  FreeHexWidget(
    id: 'widget2',
    hexagon: hex2,
    child: Text('Hello'),
    backgroundColor: Colors.green,
  ),
];

// 显示在画布上
FreeHexagonCanvas(
  size: Size(400, 300),
  hexWidgets: hexWidgets,
  showBorders: true,
)

2. 边对边相邻

// 中心六边形
final centerHex = FreeHexagon(
  id: 'center',
  center: Offset(200, 200),
  size: 50,
);

// 计算右边相邻六边形的位置（带间隙）
final rightCenter = HexagonLayoutHelper.calculateAdjacentCenter(
  sourceHex: centerHex,
  sourceEdge: 0,      // 边索引（0=右边）
  targetSize: 50,     // 目标六边形大小
  gap: 10.0,          // 10像素间隙
);

final rightHex = FreeHexagon(
  id: 'right',
  center: rightCenter,
  size: 50,
);

3. 自动生成蜂巢图案

// 生成完美的蜂巢结构
final honeycomb = HexagonLayoutHelper.createHoneycomb(
  center: Offset(300, 300),
  size: 40,
  rings: 2,           // 2圈 = 19个六边形
  gap: 2.0,           // 2像素间隙
);

// honeycomb 是 List<FreeHexagon>
// 可以直接用来创建 FreeHexWidget

4. 创建环形排列

// 在中心六边形周围创建一圈
final ring = HexagonLayoutHelper.createRing(
  center: centerHex,
  ringSize: 30,       // 周围六边形的大小
  gap: 5.0,
  startEdge: 0,
);

更多自由布局示例，请参考 自由布局详细指南。

🌟 增强功能详解

1. 丰富的填充样式

import 'package:hexagonal/hexagonal.dart';

// 纯色填充
final solidHex = EnhancedFreeHexWidget(
  id: 'solid',
  hexagon: myHexagon,
  fillStyle: SolidColorFill(Colors.blue),
  child: Text('Solid'),
);

// 渐变填充
final gradientHex = EnhancedFreeHexWidget(
  id: 'gradient',
  hexagon: myHexagon,
  fillStyle: GradientFill(
    LinearGradient(
      colors: [Colors.purple, Colors.pink],
      begin: Alignment.topLeft,
      end: Alignment.bottomRight,
    ),
  ),
  child: Text('Gradient'),
);

// 图片填充
final imageHex = EnhancedFreeHexWidget(
  id: 'image',
  hexagon: myHexagon,
  fillStyle: ImageFill(
    AssetImage('assets/texture.jpg'),
    fit: BoxFit.cover,
  ),
  child: Text('Image'),
);

// 自定义图案填充
final patternHex = EnhancedFreeHexWidget(
  id: 'pattern',
  hexagon: myHexagon,
  fillStyle: PatternFill(
    Container(
      decoration: BoxDecoration(
        gradient: RadialGradient(
          colors: [Colors.yellow, Colors.orange],
        ),
      ),
    ),
  ),
  child: Text('Pattern'),
);

2. 点击动画效果

// Scale 动画（缩放）
EnhancedFreeHexWidget(
  id: 'scale',
  hexagon: myHexagon,
  fillStyle: SolidColorFill(Colors.teal),
  clickAnimation: HexClickAnimation.scale,
  onTap: () => print('Scaled!'),
  child: Text('Click Me'),
);

// Ripple 动画（涟漪）
EnhancedFreeHexWidget(
  id: 'ripple',
  hexagon: myHexagon,
  fillStyle: SolidColorFill(Colors.blue),
  clickAnimation: HexClickAnimation.ripple,
  onTap: () => print('Ripple!'),
);

// Bounce 动画（弹跳）
EnhancedFreeHexWidget(
  id: 'bounce',
  hexagon: myHexagon,
  fillStyle: SolidColorFill(Colors.orange),
  clickAnimation: HexClickAnimation.bounce,
  onTap: () => print('Bounced!'),
);

// Glow 动画（发光）
EnhancedFreeHexWidget(
  id: 'glow',
  hexagon: myHexagon,
  fillStyle: SolidColorFill(Colors.purple),
  clickAnimation: HexClickAnimation.glow,
  onTap: () => print('Glowing!'),
);

3. 边框和视觉效果

EnhancedFreeHexWidget(
  id: 'styled',
  hexagon: myHexagon,
  fillStyle: SolidColorFill(Colors.white),
  
  // 边框样式
  borderStyle: HexBorderStyle(
    color: Colors.green,
    width: 4.0,
    join: StrokeJoin.round,
  ),
  
  // 阴影
  shadows: [
    BoxShadow(
      color: Colors.black.withOpacity(0.3),
      blurRadius: 10,
      offset: Offset(2, 2),
    ),
  ],
  
  // 透明度
  opacity: 0.8,
  
  child: Text('Styled'),
);

4. 蛇形图案生成

// 创建蛇形图案（bendFactor 控制弯折程度）
final snake = SnakePatternGenerator.createSnake(
  start: startHexagon,
  count: 15,           // 15个六边形
  size: 40,            // 每个大小40
  gap: 2.0,            // 间隙2像素
  bendFactor: 0.3,     // 0.0=直线, 1.0=最大弯曲
  initialDirection: 0, // 起始方向（0=右，1=右下，2=左下，3=左，4=左上，5=右上）
);

// 创建螺旋蛇形
final spiral = SnakePatternGenerator.createSpiralSnake(
  center: centerHexagon,
  count: 20,
  size: 35,
  gap: 3.0,
  tightness: 0.5,      // 0.0=宽松螺旋, 1.0=紧密螺旋
);

// 创建Z字形图案
final zigzag = SnakePatternGenerator.createZigZag(
  start: startHexagon,
  count: 12,
  size: 40,
  gap: 2.0,
  zigWidth: 3,         // Z字宽度
  zigHeight: 2,        // Z字高度
);

// 🆕 创建带边界回折的蛇形（自动在边界内填充）
final boundedSnake = SnakePatternGenerator.createSnakeWithBounds(
  start: startHexagon,
  count: 50,
  bounds: Rect.fromLTWH(0, 0, 600, 400),  // 边界矩形
  size: 30,
  gap: 2.0,
  initialDirection: 0,    // 初始方向
  turnDirection: 1,       // 1=碰到边界时右转，-1=左转
);

方向说明

六边形的 6 个边对应的方向索引：

  • 0: 右边（Right）→
  • 1: 右下（Down-Right）↘
  • 2: 左下（Down-Left）↙
  • 3: 左边（Left）←
  • 4: 左上（Up-Left）↖
  • 5: 右上（Up-Right）↗

5. 数据驱动生成

从数据数组直接生成六边形布局：

// 用户数据
final users = [
  {'name': 'Alice', 'score': 95, 'color': Colors.red},
  {'name': 'Bob', 'score': 87, 'color': Colors.blue},
  {'name': 'Carol', 'score': 92, 'color': Colors.green},
];

// 自动生成六边形
final hexWidgets = DataDrivenHexGenerator.generate(
  DataDrivenHexConfig<Map<String, dynamic>>(
    data: users,
    pattern: HexLayoutPattern.honeycomb,  // 蜂巢布局
    startPosition: Offset(300, 300),
    hexSize: 50,
    gap: 3.0,
    honeycombRings: 2,
    
    // 数据到六边形的映射
    hexBuilder: (userData, hexagon, index) {
      return EnhancedFreeHexWidget(
        id: 'user_$index',
        hexagon: hexagon,
        fillStyle: SolidColorFill(userData['color']),
        borderStyle: HexBorderStyle(color: Colors.white, width: 2.0),
        clickAnimation: HexClickAnimation.bounce,
        onTap: () {
          print('${userData['name']} scored ${userData['score']}');
        },
        child: Center(
          child: Column(
            mainAxisSize: MainAxisSize.min,
            children: [
              Text(userData['name']),
              Text('${userData['score']}'),
            ],
          ),
        ),
      );
    },
  ),
);

// 渲染
Stack(
  children: hexWidgets.map((w) => 
    Positioned(
      left: w.hexagon.center.dx - w.hexagon.size,
      top: w.hexagon.center.dy - w.hexagon.size,
      child: SizedBox(
        width: w.hexagon.size * 2,
        height: w.hexagon.size * 2,
        child: EnhancedHexagonRenderer(config: w),
      ),
    ),
  ).toList(),
)

支持的布局模式

数据驱动生成器支持以下布局模式：

  • HexLayoutPattern.linear - 线性排列
  • HexLayoutPattern.ring - 环形排列
  • HexLayoutPattern.honeycomb - 蜂巢结构
  • HexLayoutPattern.snake - 蛇形图案（可配置弯折）
  • HexLayoutPattern.spiral - 螺旋图案
  • HexLayoutPattern.zigzag - Z字形图案
  • HexLayoutPattern.snakeBounded - 🆕 边界回折蛇形（自动在边界内填充）

边界回折模式示例

final hexWidgets = DataDrivenHexGenerator.generate(
  DataDrivenHexConfig<int>(
    data: List.generate(50, (i) => i),
    pattern: HexLayoutPattern.snakeBounded,
    startPosition: Offset(100, 100),
    hexSize: 30,
    gap: 2.0,
    bounds: Rect.fromLTWH(50, 50, 600, 400),  // 定义边界
    snakeInitialDirection: 0,  // 向右开始
    snakeTurnDirection: 1,     // 碰到边界时右转
    hexBuilder: (value, hex, index) {
      return EnhancedFreeHexWidget(
        id: 'hex_$index',
        hexagon: hex,
        fillStyle: SolidColorFill(Colors.blue),
        child: Text('$value'),
      );
    },
  ),
);

API 文档

详细的 API 文档请参考源代码中的注释。

示例

网格布局示例

查看 /example/lib/main.dart：

  • 空网格
  • 自动布局（蛇形、环形等）
  • 手动放置
  • 交互式网格
  • 六边形裁剪

自由布局示例

运行 /example/free_layout_example.dart：

cd example
flutter run -d chrome free_layout_example.dart

包含 5个示例，其中第5个是交互式控制面板：

  1. Basic - 基础自由布局
  2. Adjacent - 边对边相邻（不同间隙）
  3. Honeycomb - 蜂巢图案生成
  4. Sizes - 不同尺寸混合
  5. 🎮 Interactive Controls - 交互式参数控制（⭐推荐！）

🎮 交互式控制面板

第5个示例提供实时参数调整：

蜂巢模式：

  • 调整环数（1-5环，最多91个六边形）
  • 调整六边形大小（20-60px）
  • 调整间隙（0-10px）

环形模式：

  • 调整中心六边形大小（30-80px）
  • 调整周围6个六边形大小（20-60px）
  • 调整间隙（0-20px）

线性模式：

  • 调整六边形数量（2-10个）
  • 调整六边形大小（20-60px）
  • 调整间隙（0-15px）

所有参数都可以实时调整，立即看到效果！

🌟 增强功能示例

运行 /example/lib/enhanced_example.dart：

cd example
flutter run -d chrome -t lib/enhanced_example.dart

包含 4个完整示例，展示所有增强功能：

  1. Fill Styles（填充样式） - 展示6种填充方式：

    • Solid（纯色）
    • Gradient（渐变）
    • Pattern（图案）
    • Border（边框）
    • Shadow（阴影）
    • Opacity（透明度）

  2. Animations（动画效果） - 5种点击动画：

    • None（无动画）
    • Scale（缩放）
    • Ripple（涟漪）
    • Bounce（弹跳）
    • Glow（发光）

  3. Snake Patterns（蛇形图案） - 交互式调节：

    • 模式选择：Snake / Spiral / ZigZag
    • Bend Factor（弯折系数）：0.0 - 1.0
    • Count（数量）：5 - 20
    • 实时预览彩虹渐变效果

  4. Data Driven（数据驱动） - 实际应用示例：

    • 用户分数排行榜
    • 蜂巢布局自动生成
    • 点击查看详情
    • 颜色透明度表示性能

详细使用指南请参考：example/INTERACTIVE_GUIDE.md

贡献

欢迎提交 Issue 和 Pull Request！

许可

MIT License

Libraries

core/hex_coordinate
core/hex_math
core/hex_orientation
free_layout/data_driven_hex_generator
free_layout/enhanced_hex_renderer
free_layout/enhanced_hex_widget
free_layout/free_hex_widget
free_layout/free_hexagon
free_layout/free_hexagon_canvas
free_layout/free_hexagon_painter
free_layout/snake_pattern_generator
grid/hex_cell
grid/hex_grid_config
grid/hexagonal_grid
helpers/hex_grid_builder
hexagonal
A Flutter package for creating hexagonal grid-based UIs.
layout/diagonal_layout
layout/hex_layout_strategy
layout/linear_layout
layout/ring_layout
layout/snake_layout
widgets/hex_clipper
widgets/hex_painter
widgets/hex_widget