Hexagonal #

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

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个是交互式控制面板：

Basic - 基础自由布局
Adjacent - 边对边相邻（不同间隙）
Honeycomb - 蜂巢图案生成
Sizes - 不同尺寸混合
🎮 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个完整示例，展示所有增强功能：

Fill Styles（填充样式） - 展示6种填充方式：
- Solid（纯色）
- Gradient（渐变）
- Pattern（图案）
- Border（边框）
- Shadow（阴影）
- Opacity（透明度）
Animations（动画效果） - 5种点击动画：
- None（无动画）
- Scale（缩放）
- Ripple（涟漪）
- Bounce（弹跳）
- Glow（发光）
Snake Patterns（蛇形图案） - 交互式调节：
- 模式选择：Snake / Spiral / ZigZag
- Bend Factor（弯折系数）：0.0 - 1.0
- Count（数量）：5 - 20
- 实时预览彩虹渐变效果
Data Driven（数据驱动） - 实际应用示例：
- 用户分数排行榜
- 蜂巢布局自动生成
- 点击查看详情
- 颜色透明度表示性能

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

贡献 #

欢迎提交 Issue 和 Pull Request！

许可 #

MIT License

hexagonal 0.0.2 hexagonal: ^0.0.2 copied to clipboard

Metadata

Hexagonal #

English #

Features #

Installation #

Quick Start #

1. Simple Grid Layout

2. Free Layout with Pattern

3. Enhanced Features with Animations

4. Data-Driven Generation

5. Bounded Snake Pattern

Key Concepts #

Generation Direction

Generation Order

Boundary Reflection

Available Patterns #

Click Animations #

Fill Styles #

Examples #

Documentation #

License #

中文 #

功能特性 #

安装 #

快速开始 #

1. 简单网格布局

2. 自由布局图案

3. 增强功能与动画

4. 数据驱动生成

5. 边界蛇形图案

核心概念 #

生成方向

生成顺序

边界反射

可用图案 #

点击动画 #

填充样式 #

示例 #

文档 #

许可证 #

坐标系统 #

布局策略 #

Widget 放置 #

🆕 自由布局快速开始 #

1. 基础自由布局 #

2. 边对边相邻 #

3. 自动生成蜂巢图案 #

4. 创建环形排列 #

🌟 增强功能详解 #

1. 丰富的填充样式 #

2. 点击动画效果 #

3. 边框和视觉效果 #

4. 蛇形图案生成 #

方向说明

5. 数据驱动生成 #

支持的布局模式 #

边界回折模式示例

API 文档 #

示例 #

网格布局示例 #

自由布局示例 #

🎮 交互式控制面板

🌟 增强功能示例 #

贡献 #

许可 #

← Metadata

Publisher

Weekly Downloads

Metadata

Documentation

License

Dependencies

More

hexagonal 0.0.2
hexagonal: ^0.0.2 copied to clipboard