回归线扩展指南

回归线在统计场景下经常出现，vchart-extensions 支持回归线的扩展功能，支持常用回归线（多项式回归、核密度估计 KDE、经验累积分布 ECDF 等）的计算和显示

注册扩展

回归线组件位于扩展包中，使用前需先注册组件：

import VChart from '@visactor/vchart';
import {
  registerRegressionLine,
  appendBarRegressionLineConfig,
  appendHistogramRegressionLineConfig,
  appendScatterRegressionLineConfig
} from '@visactor/vchart-extension';

registerRegressionLine();

如果使用 CDN 打包的全局变量 VChartExtension，请调用 VChartExtension.registerRegressionLine()。

API 概览

• registerRegressionLine() — 注册回归线组件并启用附加配置方法
• appendBarRegressionLineConfig(spec, config) — 在柱图配置中增加回归线配置，注意现在仅简单柱图（即没有分组、堆积等计算）中支持回归线，仅支持多项式回归线
• appendHistogramRegressionLineConfig(spec, config) — 在直方图上附加回归叠加（支持 kde 和 ecdf）
• appendScatterRegressionLineConfig(spec, config) — 在散点图上附加回归线

柱图回归线

示例

使用 appendBarRegressionLineConfig 为柱图添加回归线：

配置类型定义

其中回归线配置的类型定义如下：

{
  /**
   * 多项式的阶数
   */
  degree?: number;
  /**
   * 颜色值
   */
  color?: string;
  /**
   * 回归线配置
   */
  line?: {
    /**
     * 是否显示系列标签
     * @default true
     */
    visible?: boolean;
    /**
     * 线样式
     */
    style?: ILineGraphicAttribute;
  };
  /**
   * 回归线公式标签
   */
  label?: {
    /**
     * 是否显示标签
     */
    visible?: boolean;
    /**
     * 标签文本
     */
    text: string;
    /**
     * 标签样式
     */
    style?: ITextGraphicAttribute;
  };
  /**
   * 置信区间
   */
  confidenceInterval?: {
    visible?: boolean;
    style?: IAreaGraphicAttribute;
  };
}

直方图示例（KDE / ECDF）

示例

直方图回归支持在直方图上叠加 KDE 或 ECDF 曲线。请确保数据经过 bin 变换，且正确配置 xField/x2Field/yField。

配置类型定义

其中回归线配置的类型定义如下：

{
  /**
   * 回归线的类型
   */
  type: 'kde' | 'ecdf';
  /**
   * 颜色值
   */
  color?: string;
  /**
   * 回归线配置
   */
  line?: {
    /**
     * 是否显示系列标签
     * @default true
     */
    visible?: boolean;
    /**
     * 线样式
     */
    style?: ILineGraphicAttribute;
  };
  /**
   * 回归线公式标签
   */
  label?: {
    /**
     * 是否显示标签
     */
    visible?: boolean;
    /**
     * 标签文本
     */
    text: string;
    /**
     * 标签样式
     */
    style?: ITextGraphicAttribute;
  };
}

散点图/序列示例

示例

使用 appendScatterRegressionLineConfig 为散点图添加回归叠加，可配置 degree、type、样式等：

配置类型定义

其中回归线配置的类型定义如下：

{
  /**
   * 回归线的类型
   */
  type: 'linear' | 'logisitc' | 'lowess' | 'polynomial';
  /**
   * 多项式回归的阶数，仅当 type 为 polynomial 时有效
   */
  polynomialDegree?: number;
  /**
   * 颜色值
   */
  color?: string;
  /**
   * 回归线配置
   */
  line?: {
    /**
     * 是否显示系列标签
     * @default true
     */
    visible?: boolean;
    /**
     * 线样式
     */
    style?: ILineGraphicAttribute;
  };
  /**
   * 回归线公式标签
   */
  label?: {
    /**
     * 是否显示标签
     */
    visible?: boolean;
    /**
     * 标签文本
     */
    text: string;
    /**
     * 标签样式
     */
    style?: ITextGraphicAttribute;
  };
  /**
   * 置信区间
   */
  confidenceInterval?: {
    visible?: boolean;
    style?: IAreaGraphicAttribute;
  };
}

注意事项与建议

• 直方图回归依赖 bin 输出字段（例如 x0/x1/count），确保 transforms 中 bin 的 outputNames 与回归组件期望一致。
• 置信区间计算会带来额外开销，大数据集或交互更新时建议关闭。
• append* 方法会直接修改传入的 spec，如需保留原始 spec，请先深拷贝后再操作。