kline_flutter 0.2.0

一个面向金融行情场景的 Flutter 图表库，提供 K 线图、技术指标、交互控制和深度图能力。它以 `CustomPainter` 和 delegate 架构为核心，让你既可以快速接入一套默认 UI，也可以在真实业务中按需替换绘制、布局、覆盖层和数据适配。

ZHKLine Flutter

一个面向金融行情场景的 Flutter 图表库，提供 K 线图、技术指标、交互控制和深度图能力。它以 CustomPainter 和 delegate 架构为核心，让你既可以快速接入一套默认 UI，也可以在真实业务中按需替换绘制、布局、覆盖层和数据适配。

详细使用方式、自定义 UI、深度图接入和 example 说明请参考 example/use_docs.md。

效果预览

指标切换

滚动与缩放

长按详情

自定义背景

自定义指标文案

自定义主图绘制

为什么选择它

• 几分钟完成接入：业务页面只需要准备 List<T> 和 KLineDataAdapter<T>，默认 UI 已包含蜡烛图、指标、副图、长按详情和基础状态展示，不需要为了图表改造已有数据模型。
• 扩展点清晰可控：通过 KLineChartDelegate<T> / DeepChartDelegate<T> 暴露绘制流程。想改背景、网格、指标文案、主图绘制、选中浮层或深度图，只替换对应模块即可。
• 默认能力可复用：每个默认绘制能力都拆到了独立的 KLineDefaultDelegateImplUtil 中。你可以复用坐标计算、文本绘制、指标布局等基础能力，只专注改业务真正关心的那一层 UI。
• 为高频行情优化：基于 CustomPainter 分层绘制，并提前计算坐标、可见区节点和绘制数据，减少绘制阶段重复计算，适合滚动、缩放、长按等高频交互场景。
• 业务模型零侵入：K 线和深度图都通过 adapter 读取字段，后端模型、缓存模型、计算后的指标模型都可以直接接入。
• 架构长期可维护：核心图表、默认实现、主题布局、controller、example 数据层边界清晰，后续新增指标、替换 UI、接入不同交易所数据时不会牵一发动全身。
• 金融图表能力完整：内置 MA、EMA、BOLL、MACD、KDJ、RSI、WR、VOL 等常见指标，支持外部控制缩放、滚动、选中状态，也提供盘口累计深度图 DeepChart。

快速开始

在你的 Flutter 项目中添加依赖：

flutter pub add kline_flutter

或者手动写入 pubspec.yaml：

dependencies:
  kline_flutter: ^0.2.0

然后在业务代码中导入：

import 'package:kline_flutter/kline_flutter.dart';

如果想运行本仓库的示例工程：

git clone https://github.com/911hzh/ZHKLineFlutter.git
cd ZHKLineFlutter
cd example
flutter pub get
flutter run -d macos

最小接入

接入时通常只需要准备两部分：

• MyCandle：你的业务 K 线数据类，可以来自接口、数据库或本地计算结果。
• MyCandleAdapter：把业务数据转换成图表 UI 能识别的 open、high、low、close、volume 和时间文案。

import 'package:kline_flutter/kline_flutter.dart';

class MyCandle {
  const MyCandle({
    required this.open,
    required this.high,
    required this.low,
    required this.close,
    required this.volume,
    required this.timeLabel,
  });

  final double open;
  final double high;
  final double low;
  final double close;
  final double volume;
  final String timeLabel;
}

class MyCandleAdapter extends KLineDataAdapter<MyCandle> {
  const MyCandleAdapter();

  @override
  double open(MyCandle item) => item.open;

  @override
  double high(MyCandle item) => item.high;

  @override
  double low(MyCandle item) => item.low;

  @override
  double close(MyCandle item) => item.close;

  @override
  double volume(MyCandle item) => item.volume;

  @override
  String dateLabel(MyCandle item) => item.timeLabel;
}

UI 层在你的某个页面里，直接把数据数组和 adapter 传给 KLineWidget 即可：

class MarketPage extends StatelessWidget {
  const MarketPage({super.key});

  @override
  Widget build(BuildContext context) {
    return KLineWidget<MyCandle>(
      dataSource: candles,
      adapter: const MyCandleAdapter(),
      initialIndicators: const ['volume'],
    );
  }
}

实时数据接入

实时行情推荐保持一个简单边界：业务层先决定数据插到哪里，再按需要调用 controller 滚动到目标位置。package 不判断 socket 数据应该插到头部、尾部还是替换整窗。

class MarketPageState extends State<MarketPage> {
  final controller = KLineController(initialFollowLatest: true);
  List<MyCandle> candles = [];

  void onSocketCandle(MyCandle candle) {
    setState(() {
      candles = [candle, ...candles];
    });

    if (controller.isFollowingLatest) {
      controller.scrollToLatest();
    }
  }

  void onLoadOlder(List<MyCandle> olderCandles) {
    setState(() {
      candles = [...candles, ...olderCandles];
    });

    controller.scrollToIndex(
      candles.length - 1,
      alignment: KLineScrollAlignment.right,
    );
  }

  @override
  Widget build(BuildContext context) {
    return KLineWidget<MyCandle>(
      controller: controller,
      dataSource: candles,
      adapter: const MyCandleAdapter(),
    );
  }
}

常用控制方法：

• controller.setFollowingLatest(true)：保持最新一根可见，但不立刻滚动。
• controller.scrollToLatest()：滚动到最新，并进入跟随最新模式。
• controller.scrollToIndex(index, alignment: KLineScrollAlignment.left)：滚动到指定下标。
• controller.revealSelected()：把当前选中项滚回可见区域。

如果需要加载更多旧数据，可以在自定义 delegate 的滚动回调里根据 KLineScrollMetrics 判断是否到达边界；数据回来后先更新 dataSource，再按业务需要调用 scrollToIndex 保持目标 K 线可见。

深度图也保持同样的接入思路：

DeepChart<DeepDepthEntry>(
  bids: bids,
  asks: asks,
  adapter: const DeepDepthEntryAdapter(),
)

更多自定义绘制、主题、布局、错误态、加载态和 example 数据接入，请查看 example/use_docs.md。

核心能力

K 线图

• KLineWidget<T>：默认 K 线 UI，适合快速接入。
• KLineChart<T>：核心图表组件，适合完全自定义绘制。
• KLineChartDelegate<T>：绘制协议，可控制布局节点、网格、主图、副图、覆盖层和选中 UI。
• KLineDataAdapter<T>：业务模型适配器。
• KLineController：缩放、滚动、选中、可见区和指标状态控制。

深度图

• DeepChart<T>：默认深度图组件。
• DeepChartDataAdapter<T>：盘口数据适配器。
• DeepChartDelegate<T>：深度图绘制协议。
• DeepChartLayoutConfig：中间图形区域和底部价格行的布局配置。

简洁项目结构

lib/
├── kline_flutter.dart
└── src/
    ├── kline/
    └── deepchart/

example/
├── lib/base/api/
├── lib/base/store/
└── lib/module/usecase/pages/
    ├── kline/
    ├── deep_chart/
    └── custom_page/

适合场景

• 交易所行情页、合约行情页、股票/基金行情页。
• 需要快速接入默认 K 线 UI 的业务。
• 需要深度定制金融图表绘制协议的业务。
• 需要统一维护 K 线、技术指标、盘口深度和图表交互的 Flutter 项目。

参与维护

这个库还在持续完善中，欢迎大家一起参与维护：

• 提交 Issue 反馈 Bug、性能问题或 API 设计建议。
• 提交 Pull Request 补充图表能力、example、测试和文档。
• 分享真实业务中的自定义 delegate、主题和交互方案。

如果这个项目对你有帮助，欢迎点一个 Star，也欢迎一起把它维护成更好用的 Flutter 金融图表库。

License

本项目采用 MIT License，详情见 LICENSE。