ECharts的配置优先级策略

Learning by Code Wiki of ECharts.

The  “most specific wins” priority system

ECharts uses a “most specific wins” priority system for various elements and configurations beyond just tooltips and axisPointers. This means that options defined closer to a specific component or data item will generally override more general, global settings. Here are some additional cases and information about priority:

1. General Component Options:

• Component-specific options vs. Theme vs. Default: When a component is initialized or its options are merged, ECharts first applies the theme, then the component’s defaultOption, and finally merges the user-provided options. For example, ComponentModel.mergeDefaultAndTheme and GlobalModel._mergeOption show this cascading merge. This allows for theme customization and sensible defaults while giving the user ultimate control.

2. Styling (Line, Item, Area, Text Styles):

• Mixins and Mappers: ECharts uses mixins like LineStyleMixin, ItemStyleMixin, AreaStyleMixin, and TextStyleMixin (from src/model/mixin/lineStyle.ts, src/model/mixin/itemStyle.ts, src/model/mixin/areaStyle.ts, src/model/mixin/textStyle.ts respectively) to provide consistent styling. The makeStyleMapper utility (src/model/mixin/makeStyleMapper.ts) facilitates mapping these generic model properties to ZRender-specific style objects.
• Inheritance and Overrides: Styles can be inherited. For example, in LegendView.getLegendStyle, itemStyle.fill === 'inherit' means it will use the itemVisualStyle[drawType]. This implies a priority where explicit settings on the legendItemModel override inherited series visuals.
• Palette and Decals: The PaletteMixin (src/model/mixin/palette.ts) handles color and decal assignment, ensuring visual consistency from configured palettes. LegendView.getLegendStyle demonstrates how a decal can be explicitly set or inherited (itemStyle.decal = (!decalStyle || decalStyle === 'inherit') ? itemVisualStyle.decal : createOrUpdatePatternFromDecal(decalStyle, api)).

3. Marker Components (MarkLine, MarkPoint, MarkArea):

• Data Item > Series > Global: Marker configurations follow a similar priority.
  • Data Item Options: The highest priority is given to options defined on individual data items within a markPoint, markLine, or markArea series. For example, markPoint.data[i].symbol will override markPoint.symbol. This is evident in MarkPointView.renderSeries where itemModel.getShallow('symbol') is retrieved first.
  • Marker Series Options: If not specified on a data item, options like symbol, symbolSize, symbolRotate, and symbolOffset from the MarkPointModel (src/component/marker/MarkPointModel.ts) or MarkLineModel (src/component/marker/MarkLineModel.ts) apply to all its data points. This is shown in MarkPointView.renderSeries and MarkLineView.renderSeries.
  • Derived Properties: MarkLineView.renderSeries also shows how lineStyle.stroke can be explicitly set or will default to fromData.getItemVisual(idx, 'style').fill.
  • z and zlevel: MarkPointModel and MarkLineModel have z properties. This determines rendering order, with higher z values rendering on top. MarkPointView sets z2 on visual items based on itemModel.get('z2').

4. dataZoom Components:

• start/end vs. startValue/endValue vs. rangeMode: DataZoomModel (src/component/dataZoom/DataZoomModel.ts) has a complex priority for defining the zoom range.
  • start/end (percentage) and startValue/endValue (actual data values) can be specified.
  • If both percentage and value are provided, DataZoomModel._updateRangeUse and DataZoomModel._doInit indicate that start/end (percentage) generally take precedence over startValue/endValue unless explicitly overridden by rangeMode.
  • The rangeMode property ['value', 'value'] explicitly forces startValue/endValue to be used.
• Throttle: DataZoomModel._setDefaultThrottle shows that if throttle is explicitly set in inputRawOption, it overrides the auto-calculated throttle value.

5. graphic Components:

• Element-specific options: For graphic elements, individual element options (GraphicComponentElementOption from src/component/graphic/GraphicModel.ts) override more general settings.
• zlevel, z, z2: GraphicComponentView._updateElements and updateCommonAttrs show that these properties can be defined on individual graphic elements. If zlevel or z are not explicitly set on an element, the global graphicModel.get('zlevel') and graphicModel.get('z') are used as defaults.
• CSS-like Properties: The graphic component supports various CSS-like properties for layout and styling, like x, y, width, height, left, right, top, bottom, which are resolved by layoutUtil.positionElement in GraphicComponentView._relocate.

6. Legend Components:

• LegendModel Data Items: Each item in a legend’s data array can have its own icon and textStyle properties (LegendModel.getData). These item-specific settings override the general LegendModel properties, as shown in LegendView._createItem.
• inactiveColor and inactiveBorderColor: These are used when a legend item is not selected, overriding the active colors.
• selector: The selector option allows for ‘all’ or ‘inverse’ selection buttons. LegendModel._updateSelector normalizes these options, giving precedence to explicitly defined title values over default locale-based titles.
• pageIcons: For ScrollableLegendModel (src/component/legend/ScrollableLegendModel.ts), pageIcons can be configured globally.

7. Toolbox Features:

• Feature-specific options: Each toolbox feature (e.g., saveAsImage, magicType, dataZoom, restore) has its own defaultOption and can be configured individually. For example, ToolboxSaveAsImageFeatureOption defines backgroundColor, name, excludeComponents, and pixelRatio specifically for the save image feature.
• icon and title: These can be defined globally for the toolbox or specifically for each feature, with feature-specific settings taking precedence, as seen in ToolboxDataZoomFeature.getDefaultOption and ToolboxMagicType.getIcons.
• iconStatus: The setIconStatus method (used in ToolboxDataZoomFeature and ToolboxMagicType) allows dynamically changing the visual state of a feature icon (e.g., ‘emphasis’ or ‘normal’), effectively overriding the default appearance.

In summary, ECharts is designed for extensibility and granular control. Configurations are typically applied in a layered fashion: global defaults -> theme -> component-level defaults -> series-level options -> data-item or element-specific options. This allows users to set broad chart styles and behaviors while providing the flexibility to customize individual elements as needed.

A case: grid.tooltip.axisPointer VS. xAxis.axisPointer

ECharts manages tooltip and axisPointer configurations with a hierarchical priority system, where more specific settings override general ones. This allows for fine-grained control over how tooltips and axisPointers behave across different components and series. The priority order, from highest to lowest, is as follows:

1. Component/Data Item tooltip options:

   • Individual Data Items: The highest priority is given to tooltip options defined directly on individual data items within a series. This is processed by the _showSeriesItemTooltip function in src/component/tooltip/TooltipView.ts.
   • Component-specific tooltipConfig: Certain components (like legend or toolbox) can define their own tooltipConfig, which takes precedence for those specific elements. This is handled by _showComponentItemTooltip in src/component/tooltip/TooltipView.ts.
   • Marker tooltip: Markers such as markPoint, markLine, and markArea also have their own tooltip configurations, for example, markArea.tooltip in src/component/marker/MarkAreaModel.ts, markLine.tooltip in src/component/marker/MarkLineModel.ts, and markPoint.tooltip in src/component/marker/MarkPointModel.ts. These configurations are typically set to trigger: 'item'.

2. Series tooltip options: If a tooltip is not defined on a specific data item, ECharts falls back to the tooltip option configured at the series level. This configuration is part of the series.tooltip property. The _showSeriesItemTooltip function in src/component/tooltip/TooltipView.ts also considers this level.

3. Coordinate System tooltip options:

   • Grid tooltip: For Cartesian coordinate systems (grids), the grid component can have its own tooltip configuration. This is less common for general tooltip settings but applies to axisPointer settings within the grid. The GridModel in src/coord/cartesian/GridModel.ts is where this can be configured.
   • Polar tooltip: Similar to grids, polar coordinate systems can also have their own tooltip configurations.

4. xAxis / yAxis / angleAxis / radiusAxis axisPointer options:

   • Each axis model (e.g., CartesianAxisModel in src/coord/cartesian/AxisModel.ts for xAxis and yAxis, or PolarAxisModel for radiusAxis in src/component/axisPointer/PolarAxisPointer.ts) can define an axisPointer configuration. This is used to determine how the axisPointer behaves when interacting with that specific axis.
   • The axisPointer can be configured with properties like type ('line', 'shadow', 'cross'), snap, lineStyle, shadowStyle, and label.
   • The collect function in src/component/axisPointer/modelHelper.ts aggregates these axis-specific axisPointer models.
   • The AxisView class (e.g., CartesianAxisView in src/component/axis/CartesianAxisView.ts and RadiusAxisView in src/component/axis/RadiusAxisView.ts) uses this axisPointer configuration to render the visual elements.

5. Global tooltip.axisPointer option:

   • If no specific axisPointer configuration is found on an individual axis, ECharts uses the global tooltip.axisPointer setting, as defined in TooltipModel.defaultOption in src/component/tooltip/TooltipModel.ts. This provides a default behavior for all axisPointers in the chart.
   • This global configuration also supports link property, allowing multiple axisPointers to be linked together, which is handled by the collect function in src/component/axisPointer/modelHelper.ts.

6. Global tooltip option:

   • The lowest priority is the global tooltip option, defined in the tooltip component directly, as seen in TooltipModel.defaultOption in src/component/tooltip/TooltipModel.ts. This sets the default behavior for all tooltips in the chart if no more specific configuration overrides it. This includes general properties like show, trigger, alwaysShowContent, backgroundColor, textStyle, etc.

How ECharts Resolves Priorities:

The buildTooltipModel function in src/component/tooltip/TooltipView.ts is crucial for resolving this hierarchy. It takes a cascade of tooltip configurations (from data items, series, coordinate systems, and global settings) and merges them into a single effective tooltip model, with later (more specific) options overriding earlier (more general) ones.

For axisPointers, the modelHelper.collect function in src/component/axisPointer/modelHelper.ts processes axisPointer configurations, prioritizing local settings (e.g., axis.axisPointer) over global tooltip.axisPointer settings. It also creates a temporary axisPointerModel when a tooltip with trigger: 'axis' is used on a coordinate system or series, effectively making the tooltip’s axisPointer configuration take precedence for those triggered axes.

In essence, ECharts follows a “most specific wins” rule, where configurations defined closer to the data or component being interacted with will override more general, higher-level settings.