FlexiKline #

FlexiKline 是一个 Flutter 金融 K 线图表框架，指标、绘制工具、样式与手势都可以替换或扩展，适用于股票、数字货币等行情展示场景。

Demo #

在线体验 | Android APK

版本要求 #

• Flutter SDK: >= 3.27.0
• Dart SDK: >= 3.6.0

特性 #

• 自定义指标：实现指标配置与绘制对象两个接口就能接入
• 计算与绘制解耦：指标计算在独立的 IndicatorCalculator 里，不碰渲染，可以单独测试
• 自定义绘制工具：实现 DrawObject 定义自己的画法与命中判定
• 主副区布局：全屏 / 横屏切换，图表宽高可动态调整
• 配置可控：样式、参数、指标、绘制都能定制，整体序列化落盘，FlexiKlineConfig 的写入时机由业务侧决定
• 手势操作：惯性平移、缩放锚点、平移平滑均可调；嵌在可滚动容器里也能正常拿到手势
• 多平台：Android、iOS、Web、macOS、Windows、Linux

安装 #

在 pubspec.yaml 中添加依赖：

dependencies:
  flexi_kline: ^2.5.3

然后运行：

flutter pub get

快速上手 #

1. 实现配置接口 #

IConfiguration 提供主题、FlexiKlineConfig 的读写和绘制工具注册。推荐混入 FlexiKlineConfigurationMixin 获取默认配置。

abstract interface class IConfiguration implements IStorage {
  IFlexiKlineTheme get theme;
  FlexiKlineConfig getFlexiKlineConfig();
  void saveFlexiKlineConfig(FlexiKlineConfig config);
  Map<IDrawType, DrawObjectBuilder> get drawObjectBuilders;
}

IIndicatorConfig 提供蜡烛图、时间轴以及主副区指标。参数变化后保存并调用 notifyListeners()，外层的 ListenableBuilder 会重建图表：

class MyIndicatorConfig with ChangeNotifier implements IIndicatorConfig {
  MAIndicator? _ma;
  MAIndicator get ma => _ma ??= getIndicator<MAIndicator>(maIndicatorKey, MAIndicator.fromJson) ?? MAIndicator();

  set ma(MAIndicator value) {
    _ma = value;
    saveIndicator(value);
    notifyListeners();
  }

  // 同样实现 candle、time、mainIndicators、subIndicators。
}

同一份缓存配置可供横竖屏或同页多图共享；框架只在 Controller 构造和 syncFlexiKlineConfig() 时读取它，落盘由业务侧调用 storeFlexiKlineConfig() 决定。

2. 创建 FlexiKlineController #

controller = FlexiKlineController(
  configuration: FlexiKlineConfiguration(),
  logger: LoggerImpl(tag: 'FlexiKline', debug: kDebugMode),
  subIndicatorMaxCount: defaultSubIndicatorMaxCount,
  klineDataCacheCapacity: 3,
  calculationInterval: const Duration(milliseconds: 200),
);

calculationInterval 用于合并高频 updateLatestKlineData 的计算任务；不传时默认 500ms。

3. 使用 FlexiKlineWidget #

candle / time 为必填的基础指标，mainIndicators / subIndicators 为主区 / 副区叠加的可选指标。可以像组件树一样内联构造各指标并按需定制：

FlexiKlineWidget(
  controller: controller,
  // 蜡烛图: 倒计时样式 + 主区网格线定制
  candle: CandleIndicator(
    showCountdown: true,
    countdown: const TextAreaConfig(
      style: TextStyle(fontSize: 10, height: 1.2),
      textAlign: TextAlign.center,
      padding: EdgeInsets.all(2),
      borderRadius: BorderRadius.all(Radius.circular(2)),
    ),
    // 主区横向网格线(Y 轴价格刻度线): 4 等分 nice 取整 + 虚线样式
    horizontalGrid: const GridAxisConfig(
      mode: GridTickMode.nice(targetDivisions: 4),
      line: LineConfig(type: LineType.dashed, dashes: [4, 2]),
    ),
  ),
  // 时间轴: 自定义高度、位置与刻度格式(不传 tickFormatter 时按 interval 粒度默认格式化)
  time: TimeIndicator(
    height: 16,
    position: DrawPosition.bottom,
    tickFormatter: (dateTime, interval) {
      return '${dateTime.month}/${dateTime.day}';
    },
  ),
  // 主区叠加: MA 或其他主区指标
  mainIndicators: [
    MAIndicator(
      lineWidth: 1,
      calcParam: [
        MaParam(count: 5, color: Color(0xFFFFB74D), label: 'MA5'),
        MaParam(count: 10, color: Color(0xFF03A9F4), label: 'MA10'),
        MaParam(count: 30, color: Color(0xFF9C27B0), label: 'MA30'),
      ],
    ),
    ...
  ],
  // 副区叠加: MACD 或其他副区指标
  subIndicators: [
    MACDIndicator(
      calcParam: const MACDParam(s: 12, l: 26, m: 9),
      lineWidth: 1,
    ),
    ...
  ],
)

也可从一个 IIndicatorConfig 解构，并混入配置之外的指标（如业务侧的 External 指标）：

ListenableBuilder(
  listenable: myIndicatorConfig,
  builder: (context, _) => FlexiKlineWidget(
    controller: controller,
    candle: myIndicatorConfig.candle,
    time: myIndicatorConfig.time,
    mainIndicators: [...myIndicatorConfig.mainIndicators, ...otherIndicators],
    subIndicators: myIndicatorConfig.subIndicators,
  ),
)

4. 更新数据 #

import 'package:flexi_formatter/date_time.dart' show TimeUnit;

final spec = KlineSpec(
  symbol: 'BTC-USDT',
  interval: const FlexiTimeInterval(1, TimeUnit.day),
);

controller.switchKlineData(spec);
controller.replaceKlineData(spec, initialCandles); // 首次加载 / 刷新
controller.updateLatestKlineData(spec, latestCandles); // WebSocket 最新端更新
controller.appendHistoryKlineData(spec, olderCandles); // 更早的历史数据

final index = await controller.moveToDateTime(DateTime(2024, 6, 15));

三个更新入口各自声明意图：replaceKlineData 整体替换并全量重算，updateLatestKlineData 只处理最新端，appendHistoryKlineData 只追加历史端。switchKlineData 命中缓存时返回 true；传入 spec 与当前数据不一致的更新会被忽略。

蜡烛合并与指标计算由同一条内部流水线串行编排。后续计划开放外置流水线接口，让业务侧完成清洗、复权、聚合或换算后，再交回框架绘制。

配置 #

图表的全部可配置项都在一份 FlexiKlineConfig 里，由 IConfiguration.getFlexiKlineConfig() 提供，可整体序列化成 JSON 落盘。

配置组成 #

LineConfig、PointConfig、TextAreaConfig、TipsConfig、MarkConfig、PaintConfig、GradientConfig、TooltipConfig、MagnifierConfig、LoadingConfig、ToleranceConfig 是被上述配置与各指标复用的样式单元。

所有字段的默认值参考：FlexiKline 完整配置.json

主题 #

颜色不写死在配置对象里，由 IFlexiKlineTheme 在绘制时注入，同一份配置就能跟随亮 / 暗色主题切换。主题变化后调用 controller.onThemeChanged()，各绘制对象会重建自己的主题派生资源。

耐久性与一致性 #

两个 Controller 方法各管一件事，它们不是一对逆操作：

syncFlexiKlineConfig() 取的是 getFlexiKlineConfig() 返回的配置而非存储快照——返回共享实例时全程不碰存储，返回新实例时对侧须先落盘本侧才读得到。它不发通知（与 showMainIndicator() 一致），调用方需自行刷新依赖激活集合的状态。

绘制 overlay 不在以上任何一环，它由框架自动落盘，见「绘制工具」一节。

指标系统 #

提供指标 #

IIndicatorConfig 的四个 getter 分别向 FlexiKlineWidget 提供基础指标与可选指标；它与 IConfiguration 平行，并继承 IStorage 保存指标参数。

指标分类 #

框架通过 IIndicatorKey sealed class 区分三类指标，各自有对应的 Indicator 与 PaintObject 基类：

指标声明（Indicator）负责可序列化配置；运行时绘制对象（PaintObject）在指标激活时由 createPaintObject() 创建。

生命周期 #

三类 PaintObject 共享同一套生命周期回调：

Direct 与 Computed 的 autoActivate 默认 false；show 时创建、hide 时销毁，keepAlive 为真则保活复用。External 的 autoActivate 与 keepAlive 默认都是 true，声明即激活，移除声明才销毁。

绘制入口 #

交互入口 #

默认全部为空操作，按需覆写。点击与拖动按 zIndex 倒序询问，视觉最上层的对象优先作答。

position 已按大区分派：主区指标只收到 mainRect 内的位置，副区指标只收到 subRect 内的位置。认领拖动后，框架抑制图表平移、惯性平移、loadMore 与 Cross 更新；目标中途消失时调用 context.requestReleasePaintObject(this) 释放持有。

Direct 指标 #

最基础的形态，直接读取当前 K 线数据与绘制上下文。createPaintObject() 连接声明与运行时对象；computeVisibleMinMax 与 paint 是最常见的绘制入口。内置蜡烛图与时间轴都是这一类。

class VolumeIndicator extends DirectIndicator {
  @override
  DirectPaintObject<VolumeIndicator> createPaintObject() => VolumePaintObject();
}

class VolumePaintObject extends DirectPaintObject<VolumeIndicator> {
  @override
  MinMax? computeVisibleMinMax(int start, int end) {
    // 遍历当前可见 K 线，返回成交量的最大最小值。
  }

  @override
  void paint(Canvas canvas, Size size) {
    // 绘制成交量柱。
  }
}

Computed 指标 #

Computed 比 Direct 多一层预计算：createCalculator(dataIndex) 创建 IndicatorCalculator 写入槽位，ComputedPaintObject 通过 dataIndex 读取结果再绘制。计算器不依赖 Flutter、Canvas 或 PaintObject，可单独测试。

下面省略构造参数、序列化和具体算法，但保留计算器与 PaintObject 的接线关系：

class MAIndicator extends ComputedIndicator {
  @override
  final List<MaParam> calcParam;

  @override
  ComputedPaintObject<MAIndicator> createPaintObject() => MAPaintObject();

  @override
  IndicatorCalculator<MAIndicator> createCalculator(int dataIndex) => MACalculator(this, dataIndex);

  @override
  bool shouldRecompute(covariant MAIndicator old) => old.calcParam != calcParam;
}

class MACalculator extends IndicatorCalculator<MAIndicator> {
  MACalculator(super.indicator, super.dataIndex);

  @override
  void compute(KlineData data, Range range, {bool reset = false}) {
    // 用 indicator.calcParam 计算 range，并写入 slots[dataIndex]。
  }
}

class MAPaintObject extends ComputedPaintObject<MAIndicator> {
  @override
  MinMax? computeVisibleMinMax(int start, int end) {
    // 从 slots[dataIndex] 聚合当前可见指标值。
  }

  @override
  void paint(Canvas canvas, Size size) {
    // 从 slots[dataIndex] 读取结果并绘制指标线。
  }
}

External 指标 #

External 由业务数据或用户操作驱动，不占计算槽位。initState 默认调用 loadBusinessData()；挂单线、成交标记等业务图形通常只需覆写这一处，并在数据完成后调用 setState()。

class TradeIndicator extends ExternalIndicator {
  @override
  ExternalPaintObject<TradeIndicator> createPaintObject() => TradePaintObject();
}

class TradePaintObject extends ExternalPaintObject<TradeIndicator> {
  @override
  void loadBusinessData() {
    // 拉取挂单 / 成交数据，完成后调用 setState()。
  }

  @override
  void didChangeDependencies(KlineSpec oldSpec) {
    loadBusinessData();
    setState();
  }

  @override
  void paint(Canvas canvas, Size size) {
    // 绘制挂单线或成交标记。
  }
}

绘制工具 #

绘制工具（趋势线、射线、斐波那契等）通过 IDrawType 与 DrawObject 扩展，在 IConfiguration.drawObjectBuilders 中注册，也可运行期 controller.registerDrawObjectBuilder(type, builder) 追加。

内置绘制工具集由 flexi_kline_draw_tools 提供。

class RayLineDrawObject extends DrawObject {
  RayLineDrawObject(super.overlay, super.config);

  @override
  bool hitTest(DrawContext context, Offset position, {bool isMove = false}) {
    // 判断 [position] 是否命中当前绘制对象
  }

  @override
  void draw(DrawContext context, Canvas canvas, Size size) {
    // 绘制已完成的图形
  }
}

可覆写的钩子 #

持久化 #

绘制实例按 symbol 存在独立存储键下，由框架自动落盘：绘制完成、点位确认、移动结束、改样式、锁定、改层级都会立即写入，业务侧无需调用 storeFlexiKlineConfig()。跨 Controller 同步由 syncFlexiKlineConfig() 顺带完成。

License #

Apache License 2.0