feat: introduce ChartLowLayerConfig and ChartLowLayerPainter for customizable low layer background

Author: z-chu

lib/deriv_chart.dart

@@ -146,6 +146,7 @@ export 'src/deriv_chart/chart/data_visualization/chart_series/ohlc_series/ohlc_t
 export 'src/deriv_chart/chart/data_visualization/chart_series/ohlc_series/ohlc_painter.dart';
 export 'src/deriv_chart/chart/data_visualization/chart_series/ohlc_series/ohlc_painting.dart';
 export 'src/deriv_chart/chart/data_visualization/chart_series/data_painter.dart';
+export 'src/models/chart_low_layer_config.dart';
 export 'src/theme/chart_default_theme.dart';
 export 'src/models/chart_config.dart';
 export 'src/deriv_chart/chart/data_visualization/markers/marker_icon_painters/accumulator_marker_icon_painter.dart';

lib/src/deriv_chart/chart/basic_chart.dart

@@ -7,6 +7,7 @@ import 'package:deriv_chart/src/deriv_chart/chart/y_axis/y_grid_line_painter.dar
 import 'package:deriv_chart/src/deriv_chart/chart/x_axis/x_axis_model.dart';
 import 'package:deriv_chart/src/models/chart_axis_config.dart';
 import 'package:deriv_chart/src/models/chart_config.dart';
+import 'package:deriv_chart/src/models/chart_low_layer_config.dart';
 import 'package:deriv_chart/src/theme/chart_theme.dart';
 import 'package:flutter/foundation.dart';
 import 'package:flutter/material.dart';
@@ -35,6 +36,7 @@ class BasicChart extends StatefulWidget {
     this.currentTickAnimationDuration = _defaultDuration,
     this.quoteBoundsAnimationDuration = _defaultDuration,
     this.enableYAxisScaling = true,
+    this.chartLowLayerConfig,
   })  : chartAxisConfig = chartAxisConfig ?? const ChartAxisConfig(),
         super(key: key);
 
@@ -63,6 +65,10 @@ class BasicChart extends StatefulWidget {
   /// Defaults to true.
   final bool enableYAxisScaling;
 
+  /// 磨砂背景配置，用于在图表数据下方绘制磨砂背景区域
+  /// 背景绘制在网格线之上，但在所有其他绘制元素之下
+  final ChartLowLayerConfig? chartLowLayerConfig;
+
   @override
   BasicChartState<BasicChart> createState() => BasicChartState<BasicChart>();
 }
@@ -518,6 +524,7 @@ class BasicChartState<T extends BasicChart> extends State<T>
                 topY: chartQuoteToCanvasY(widget.mainSeries.maxValue),
                 bottomY: chartQuoteToCanvasY(widget.mainSeries.minValue),
                 chartScaleModel: context.watch<ChartScaleModel>(),
+                chartLowLayerConfig: widget.chartLowLayerConfig,
               ),
             ),
           ),

lib/src/deriv_chart/chart/chart.dart

@@ -1,21 +1,23 @@
 import 'package:collection/collection.dart';
 import 'package:deriv_chart/src/deriv_chart/chart/data_visualization/models/chart_scale_model.dart';
+import 'package:deriv_chart/src/deriv_chart/chart/gestures/gesture_manager.dart';
 import 'package:deriv_chart/src/deriv_chart/chart/mobile_chart_frame_dividers.dart';
 import 'package:deriv_chart/src/deriv_chart/chart/x_axis/x_axis_model.dart';
-import 'package:deriv_chart/src/deriv_chart/interactive_layer/crosshair/crosshair_variant.dart';
-import 'package:deriv_chart/src/theme/dimens.dart';
-import 'package:flutter/foundation.dart';
-import 'package:deriv_chart/src/deriv_chart/chart/gestures/gesture_manager.dart';
 import 'package:deriv_chart/src/deriv_chart/chart/x_axis/x_axis_wrapper.dart';
 import 'package:deriv_chart/src/deriv_chart/drawing_tool_chart/drawing_tools.dart';
+import 'package:deriv_chart/src/deriv_chart/interactive_layer/crosshair/crosshair_variant.dart';
 import 'package:deriv_chart/src/misc/callbacks.dart';
 import 'package:deriv_chart/src/models/chart_axis_config.dart';
 import 'package:deriv_chart/src/models/chart_config.dart';
+import 'package:deriv_chart/src/models/chart_low_layer_config.dart';
 import 'package:deriv_chart/src/models/indicator_input.dart';
 import 'package:deriv_chart/src/theme/chart_default_light_theme.dart';
+import 'package:deriv_chart/src/theme/dimens.dart';
+import 'package:flutter/foundation.dart';
 import 'package:flutter/material.dart';
 import 'package:provider/provider.dart';
 import 'package:provider/single_child_widget.dart';
+
 import '../../add_ons/indicators_ui/indicator_config.dart';
 import '../../add_ons/repository.dart';
 import '../../misc/chart_controller.dart';
@@ -33,9 +35,8 @@ import 'data_visualization/markers/marker_series.dart';
 import 'data_visualization/models/chart_object.dart';
 import 'main_chart.dart';
 
-part 'chart_state_web.dart';
-
 part 'chart_state_mobile.dart';
+part 'chart_state_web.dart';
 
 const Duration _defaultDuration = Duration(milliseconds: 300);
 
@@ -83,6 +84,7 @@ class Chart extends StatefulWidget {
     this.loadingAnimationColor,
     this.useDrawingToolsV2 = false,
     this.enableYAxisScaling = true,
+    this.chartLowLayerConfig,
     Key? key,
   }) : super(key: key);
 
@@ -224,6 +226,10 @@ class Chart extends StatefulWidget {
   /// Defaults to true.
   final bool enableYAxisScaling;
 
+  /// 磨砂背景配置，用于在图表数据下方绘制磨砂背景区域
+  /// 背景绘制在网格线之上，但在所有其他绘制元素之下
+  final ChartLowLayerConfig? chartLowLayerConfig;
+
   @override
   State<StatefulWidget> createState() =>
       // TODO(Ramin): Make this customizable from outside.

lib/src/deriv_chart/chart/chart_state_mobile.dart

@@ -139,7 +139,8 @@ class _ChartStateMobile extends _ChartState {
                   onCrosshairDisappeared: widget.onCrosshairDisappeared,
                   onCrosshairHover: _onCrosshairHover,
                   onCrosshairTickChanged: widget.onCrosshairTickChanged,
-                  onCrosshairTickEpochChanged: widget.onCrosshairTickEpochChanged,
+                  onCrosshairTickEpochChanged:
+                      widget.onCrosshairTickEpochChanged,
                   loadingAnimationColor: widget.loadingAnimationColor,
                   currentTickAnimationDuration: currentTickAnimationDuration,
                   quoteBoundsAnimationDuration: quoteBoundsAnimationDuration,
@@ -149,6 +150,7 @@ class _ChartStateMobile extends _ChartState {
                   interactiveLayerBehaviour: widget.interactiveLayerBehaviour,
                   useDrawingToolsV2: widget.useDrawingToolsV2,
                   enableYAxisScaling: widget.enableYAxisScaling,
+                  chartLowLayerConfig: widget.chartLowLayerConfig,
                 ),
                 Align(
                   alignment: Alignment.topLeft,

lib/src/deriv_chart/chart/chart_state_web.dart

@@ -54,6 +54,7 @@ class _ChartStateWeb extends _ChartState {
             interactiveLayerBehaviour: widget.interactiveLayerBehaviour,
             useDrawingToolsV2: widget.useDrawingToolsV2,
             enableYAxisScaling: widget.enableYAxisScaling,
+            chartLowLayerConfig: widget.chartLowLayerConfig,
           ),
         ),
         if (bottomSeries?.isNotEmpty ?? false)

lib/src/deriv_chart/chart/custom_painters/chart_data_painter.dart

@@ -1,15 +1,16 @@
 // ignore_for_file: unnecessary_null_comparison
-
 import 'package:deriv_chart/src/deriv_chart/chart/data_visualization/chart_data.dart';
 import 'package:deriv_chart/src/deriv_chart/chart/data_visualization/models/animation_info.dart';
 import 'package:deriv_chart/src/deriv_chart/chart/data_visualization/models/chart_scale_model.dart';
 import 'package:deriv_chart/src/models/chart_config.dart';
+import 'package:deriv_chart/src/models/chart_low_layer_config.dart';
 import 'package:deriv_chart/src/theme/chart_theme.dart';
 import 'package:flutter/material.dart';
 
 import '../data_visualization/chart_series/line_series/line_series.dart';
 import '../data_visualization/chart_series/ohlc_series/candle/candle_series.dart';
 import '../data_visualization/chart_series/series.dart';
+import 'chart_low_layer_painter.dart';
 
 /// A `CustomPainter` which paints the chart data inside the chart.
 class ChartDataPainter extends BaseChartDataPainter {
@@ -28,6 +29,7 @@ class ChartDataPainter extends BaseChartDataPainter {
     required ChartScaleModel chartScaleModel,
     List<Series> secondarySeries = const <Series>[],
     AnimationInfo animationInfo = const AnimationInfo(),
+    this.chartLowLayerConfig,
   }) : super(
           chartConfig: chartConfig,
           theme: theme,
@@ -45,8 +47,25 @@ class ChartDataPainter extends BaseChartDataPainter {
   /// Chart's main data series.
   final Series mainSeries;
 
+  /// 磨砂背景配置，如果为 null 则不绘制背景
+  final ChartLowLayerConfig? chartLowLayerConfig;
+
   @override
   void paint(Canvas canvas, Size size) {
+    // 先绘制磨砂背景（在网格线之上，但在所有其他元素之下）
+    if (chartLowLayerConfig != null) {
+      ChartLowLayerPainter.paint(
+        canvas: canvas,
+        size: size,
+        config: chartLowLayerConfig!,
+        epochToCanvasX: epochToCanvasX,
+        defaultBackgroundColor: theme.backgroundColor,
+        topY: 0,
+        bottomY: size.height,
+      );
+    }
+
+    // 然后绘制主系列
     mainSeries.paint(
       canvas,
       size,
@@ -73,9 +92,13 @@ class ChartDataPainter extends BaseChartDataPainter {
     bool visibleAnimationChanged() =>
         mainSeries.shouldRepaint(oldDelegate.mainSeries);
 
+    bool backgroundChanged() =>
+        chartLowLayerConfig != oldDelegate.chartLowLayerConfig;
+
     return super.shouldRepaint(oldDelegate) ||
         styleChanged() ||
-        visibleAnimationChanged();
+        visibleAnimationChanged() ||
+        backgroundChanged();
   }
 }