规范（Spec）

规范（Specification）是 JSON 格式的可视化描述定义。如下所示：

{
  token: {
    backgroundColor: '#fff',
  },
  layout: 'lg-1*1',
  data: [
    {
      values: [
        {
          "name": "光线传媒",
          "profitability": 89.0266204080834,
          "date": "2024-01-01"
        },
        {
          "name": "光线传媒",
          "profitability": 31.755979924764176,
          "date": "2023-01-01"
        },
        {
          "name": "光线传媒",
          "profitability": 83.85676611503831,
          "date": "2022-01-01"
        }
      ]
    }
  ],
  view: {
    main: {
      layers: [
        {
          type: 'line',
          encoding: {
            x: 'date',
            y: 'profitability'
          }
        }
      ]
    }，
    secondary: {
      data: [
        { name: '同花顺', code: 300033, market: '33' },
        { name: '东方财富', code: 300059, market: '33' },
        { name: '光线传媒', code: 300251, market: '33' }
      ]
    }
  }
}

参考

关于规范设计，详细信息请查看架构概述。

提示

关于 token 和 hook，请查看设计 Token 和 Hook APIs。

实时调试预览

布局

layout

• 类型

  type Layout =
    | 'sm-1*1'
    | 'sm-2*1'
    | 'sm-1*2'
    | 'lg-1*1'
    | 'lg-3*2';

• 默认值 'lg-1*1'

布局。

数据集

data

• 类型

  type Data = {
    metadata?: unknown;
    values: { [key: string]: string | number }[];
  }[];

数据集（values）格式要求必须为标准的表格数据集（即一维对象数组）。

示例：

{
  values: [
    {
      "name": "光线传媒",
      "profitability": 89.0266204080834,
      "date": "2024-01-01"
    },
    {
      "name": "光线传媒",
      "profitability": 31.755979924764176,
      "date": "2023-01-01"
    },
    {
      "name": "光线传媒",
      "profitability": 83.85676611503831,
      "date": "2022-01-01"
    }
  ]
}

数据集的元信息

数据集的元信息（metadata）格式是自定义的，其需要根据指定 Hook API 实现解析逻辑。

视区块

视区块与层

视区块是整体布局上的抽象概念，每个视区块最终需要配置层来完成渲染，目前视区块分为StandardChartView、HXKLineView、NormalView及ExternalView（基于第三方库的视区块）。

• 类型

  type View = {
    /** 主图 */
    main: NormalViewSpec | StandardChartViewSpec | HXKLineViewSpec ｜ ExternalViewSpec;
    /** 副图 */
    secondary?: SimpleKLineViewSpec;
  }[];

视区块，其中主图视区（main）是必须的。

示例：

{
  main: {
    layers: [
      {
        type: 'line',
        encoding: {
          x: 'date',
          y: 'profitability'
        }
      }
    ]
  }
}

层

提示

层是每个视区块的渲染实体，是一类可视化效果（单一类型图表组件）渲染的基本单位。

根据不同层底层依赖的绘图库的不同，将其区分为多个大类。

StandardChartViewSpec

基于标准范式图表库开发的层。

line

interface Spec {
  encoding: {
    x: string;
    y: string;
    z?: string;
  };
  /** 是否堆叠 */
  dvStack?: boolean;
  /** 色板，比全局色板更高的优先级 */
  dvColor?: string[];
}

const dataRequire = {
  x: {
    itemType: [DEFINE.DATE],
    category: DEFINE.SINGLE,
    priority: DEFINE.DATE,
  },
  y: {
    itemType: [DEFINE.NUMBER],
    category: DEFINE.ARRAY,
  },
  z: {
    itemType: [DEFINE.STR],
    category: DEFINE.SINGLE,
    priority: DEFINE.STR,
    optional: true,
  },
};

bandedIntervalTrendLine

interface Spec {
  encoding: {
    x: string;
    y: string;
    y2: string;
    y3: string;
  };
}

const dataRequire = {
  x: {
    itemType: [DEFINE.DATE],
    category: DEFINE.SINGLE,
    priority: DEFINE.DATE,
  },
  y: {
    itemType: [DEFINE.NUMBER],
    category: DEFINE.SINGLE,
  },
  y2: {
    itemType: [DEFINE.NUMBER],
    category: DEFINE.SINGLE,
  },
  y3: {
    itemType: [DEFINE.NUMBER],
    category: DEFINE.SINGLE,
  },
};

positiveAndNegativeDoubleIndicatorComparisonLine

interface Spec {
  encoding: {
    x: string;
    y: string;
    y2: string;
  };
}

const dataRequire = {
  x: {
    itemType: [DEFINE.STR, DEFINE.DATE],
    category: DEFINE.SINGLE,
    priority: DEFINE.DATE,
  },
  y: {
    itemType: [DEFINE.NUMBER],
    category: DEFINE.SINGLE,
  },
  y2: {
    itemType: [DEFINE.NUMBER],
    category: DEFINE.SINGLE,
  },
};

dynamicLine

interface Spec {
  encoding: {
    x: string;
    y: string;
  };
}

const dataRequire = {
  x: {
    itemType: [DEFINE.DATE],
    category: DEFINE.SINGLE,
  },
  y: {
    itemType: [DEFINE.NUMBER],
    category: DEFINE.SINGLE,
  },
};

dynamicRankingLine

interface Spec {
  encoding: {
    x: string;
    y: string;
    z: string;
  };
}

const dataRequire = {
  x: {
    itemType: [DEFINE.DATE],
    category: DEFINE.SINGLE,
  },
  y: {
    itemType: [DEFINE.NUMBER, DEFINE.STR],
    category: DEFINE.SINGLE,
  },
  z: { itemType: [DEFINE.STR], category: DEFINE.SINGLE },
};

bar

interface Spec {
  encoding: {
    x: string;
    y: string[];
    z?: string;
  };
  showBackground?: boolean;
  dvHorizontal?: boolean;
  /** 是否堆叠 */
  dvStack?: boolean;
  /** 色板，比全局色板更高的优先级 */
  dvColor?: string[];
}

const dataRequire = {
  x: {
    itemType: [DEFINE.STR, DEFINE.DATE],
    category: DEFINE.SINGLE,
    priority: DEFINE.DATE,
  },
  y: {
    itemType: [DEFINE.NUMBER],
    category: DEFINE.ARRAY,
  },
  z: {
    itemType: [DEFINE.DATE, DEFINE.STR],
    category: DEFINE.SINGLE,
    priority: DEFINE.STR,
    optional: true,
  },
};

polarBar

interface Spec {
  encoding: {
    x: string;
    y: string;
  };
}

const dataRequire = {
  x: {
    itemType: [DEFINE.STR, DEFINE.DATE],
    category: DEFINE.SINGLE,
  },
  y: {
    itemType: [DEFINE.NUMBER],
    category: DEFINE.SINGLE,
  },
};

groupedStackedBar

interface Spec {
  encoding: {
    x: string;
    y: string;
    group: string;
    group2: string;
  };
}

const dataRequire = {
  x: {
    itemType: [DEFINE.STR, DEFINE.DATE],
    category: DEFINE.SINGLE,
    priority: DEFINE.DATE,
  },
  y: {
    itemType: [DEFINE.NUMBER],
    category: DEFINE.SINGLE,
  },
  group: {
    itemType: [DEFINE.STR, DEFINE.DATE],
    category: DEFINE.SINGLE,
  },
  group2: {
    itemType: [DEFINE.STR, DEFINE.DATE],
    category: DEFINE.SINGLE,
  },
};

waterfall

interface Spec {
  encoding: {
    x: string;
    y: string;
    y2: string;
  };
}

const dataRequire = {
  x: {
    itemType: [DEFINE.STR],
    category: DEFINE.SINGLE,
  },
  y: {
    itemType: [DEFINE.NUMBER],
    category: DEFINE.SINGLE,
  },
  y2: {
    itemType: [DEFINE.DATE],
    category: DEFINE.SINGLE,
  },
};

positiveAndNegativeDoubleIndicatorSumBar

interface Spec {
  encoding: {
    x: string;
    y: string;
    y2: string;
  };
}

const dataRequire = {
  x: {
    itemType: [DEFINE.STR, DEFINE.DATE],
    category: DEFINE.SINGLE,
    priority: DEFINE.DATE,
  },
  y: {
    itemType: [DEFINE.NUMBER],
    category: DEFINE.SINGLE,
  },
  y2: {
    itemType: [DEFINE.NUMBER],
    category: DEFINE.SINGLE,
  },
};

dynamicRankingTwoWayHorizontalBar

interface Spec {
  encoding: {
    x: string;
    x2: string;
    y: string;
    group: string;
  };
  animationDuration: number;
}

const dataRequire = {
  x: {
    itemType: [DEFINE.NUMBER],
    category: DEFINE.SINGLE,
  },
  x2: {
    itemType: [DEFINE.NUMBER],
    category: DEFINE.SINGLE,
  },
  y: {
    itemType: [DEFINE.STR],
    category: DEFINE.SINGLE,
  },
  group: { itemType: [DEFINE.DATE], category: DEFINE.SINGLE },
};

dynamicRankingHorizontalBar

interface Spec {
  encoding: {
    x: string;
    y: string;
    group: string;
  };
}

const dataRequire = {
  x: {
    itemType: [DEFINE.NUMBER],
    category: DEFINE.SINGLE,
  },
  y: {
    itemType: [DEFINE.STR],
    category: DEFINE.SINGLE,
  },
  group: { itemType: [DEFINE.DATE], category: DEFINE.SINGLE },
};

pie

interface Spec {
  encoding: {
    x: string;
    y: string;
  };
  roseType?: unknown;
  radius?: unknown;
}

const dataRequire = {
  x: {
    itemType: [DEFINE.STR],
    category: DEFINE.SINGLE,
  },
  y: {
    itemType: [DEFINE.NUMBER],
    category: DEFINE.SINGLE,
  },
};

doublePie

interface Spec {
  encoding: {
    x: string;
    y: string;
    x2: string;
    y2: string;
  };
}

const dataRequire = {
  x: {
    itemType: [DEFINE.STR],
    category: DEFINE.SINGLE,
  },
  y: { itemType: [DEFINE.NUMBER], category: DEFINE.SINGLE },
  x2: {
    itemType: [DEFINE.STR],
    category: DEFINE.SINGLE,
  },
  y2: { itemType: [DEFINE.NUMBER], category: DEFINE.SINGLE },
};

multiIndicatorRingGauge

interface Spec {
  encoding: {
    x: string;
  };
}

const dataRequire = {
  x: {
    itemType: [DEFINE.NUMBER],
    category: DEFINE.ARRAY,
  },
};

dynamicVoronoi

interface Spec {
  encoding: {
    x: string;
    y: string;
    group: string;
  };
  animationDuration: number;
}

const dataRequire = {
  x: {
    itemType: [DEFINE.STR],
    category: DEFINE.SINGLE,
  },
  y: {
    itemType: [DEFINE.NUMBER],
    category: DEFINE.SINGLE,
  },
  group: {
    itemType: [DEFINE.DATE],
    category: DEFINE.SINGLE,
  },
};

scatter

interface Spec {
  encoding: {
    x: string;
    y: string;
    size?: string;
    color?: string;
  };
}

const dataRequire = {
  x: {
    itemType: [DEFINE.NUMBER],
    category: DEFINE.SINGLE,
  },
  y: { itemType: [DEFINE.NUMBER], category: DEFINE.SINGLE },
  size: { itemType: [DEFINE.NUMBER], category: DEFINE.SINGLE, optional: true },
  color: { itemType: [DEFINE.STR], category: DEFINE.SINGLE, optional: true },
};

dynamicBeeSwarm

interface Spec {
  encoding: {
    x: string;
    y: string;
    y2: string;
  };
  animationDuration: string;
}

const dataRequire = {
  xAttribute: {
    itemType: [DEFINE.STR],
    category: DEFINE.SINGLE,
  },
  y: {
    itemType: [DEFINE.NUMBER],
    category: DEFINE.ARRAY,
  },
  groupAttribute: { itemType: [DEFINE.DATE], category: DEFINE.SINGLE },
};

dynamicBubble

interface Spec {
  encoding: {
    name: string;
    value: string;
    group: string;
  };
  animationDuration: string;
}

const dataRequire = {
  name: { itemType: [DEFINE.STR], category: DEFINE.SINGLE },
  value: {
    itemType: [DEFINE.NUMBER],
    category: DEFINE.ARRAY,
  },
  group: { itemType: [DEFINE.DATE], category: DEFINE.SINGLE },
};

bar3D

interface Spec {
  encoding: {
    x: string;
    y: string;
    z: string;
  };
}

const dataRequire = {
  x: {
    itemType: [DEFINE.STR],
    category: DEFINE.SINGLE,
  },
  y: {
    itemType: [DEFINE.STR, DEFINE.DATE],
    category: DEFINE.SINGLE,
    priority: DEFINE.DATE,
  },
  z: {
    itemType: [DEFINE.NUMBER],
    category: DEFINE.SINGLE,
  },
};

scatter3D

interface Spec {
  encoding: {
    x: string;
    y: string;
    z: string;
    size?: string;
    color?: string;
  };
}

const dataRequire = {
  x: {
    itemType: [DEFINE.STR],
    category: DEFINE.SINGLE,
  },
  y: {
    itemType: [DEFINE.DATE],
    category: DEFINE.SINGLE,
  },
  z: {
    itemType: [DEFINE.NUMBER],
    category: DEFINE.SINGLE,
  },
  size: {
    itemType: [DEFINE.NUMBER],
    category: DEFINE.SINGLE,
    optional: true,
  },
  color: {
    itemType: [DEFINE.NUMBER],
    category: DEFINE.SINGLE,
    optional: true,
  },
};

HXKLineViewSpec

基于核新行情图组件库开发的层。

hxKLine

interface Spec {
  /**
   * 股票
   * @see https://khtest.10jqka.com.cn/kodexplorer/data/User/wangyifan/home/HXKlineChart/docs/guide/datafeed-datasource.html
   */
  stocks: { code: string; name: string; market: string }[];
}

hxKLineAndMultiIndicatorLine

interface Spec {
  /** 折线图使用的数据集索引，默认为 0 */
  dataIndex?: number;
  /** 折线图数据编码 */
  encoding: {
    x: string;
    y: string[];
  };
  stocks: { code: string; name: string; market: string }[];
}

hxKLineAndBar

interface Spec {
  /** 柱状图使用的数据集索引，默认为 0 */
  dataIndex?: number;
  /** 柱状图数据编码 */
  encoding: {
    x: string;
    y: string;
  };
  stocks: { code: string; name: string; market: string }[];
}

hxKLineAndBar

interface Spec {
  /** 折线图使用的数据集索引，默认为 0 */
  dataIndex?: number;
  /** 折线图数据编码 */
  encoding: {
    x: string;
    y: string[];
  };
  stocks: { code: string; name: string; market: string }[];
}

NormalViewSpec

常规 DOM 开发的简单非可视化图表效果的层。

table

interface Spec {
  /** 使用的数据集索引，默认为 0 */
  dataIndex?: number;
  encoding: {
    x: string[];
  };
}

const dataRequire = {
  x: {
    itemType: [DEFINE.STR, DEFINE.DATE, DEFINE.NUMBER],
    category: DEFINE.ARRAY,
  },
};

verticalTable

interface Spec {
  /** 使用的数据集索引，默认为 0 */
  dataIndex?: number;
  encoding: {
    x: string[];
  };
}

const dataRequire = {
  x: {
    itemType: [DEFINE.STR, DEFINE.DATE, DEFINE.NUMBER],
    category: DEFINE.ARRAY,
  },
};

summaryText

interface Spec {
  /** 使用的数据集索引，默认为 0 */
  dataIndex?: number;
  encoding: {
    x: string;
  };
}

const dataRequire = {
  x: { itemType: [DEFINE.STR, DEFINE.NUMBER], category: DEFINE.SINGLE },
};

timeList

interface Spec {
  /** 使用的数据集索引，默认为 0 */
  dataIndex?: number;
  encoding: {
    time: string;
    title: string;
    label: string;
    url: string;
  };
  customEvent?: (url: string) => void;
}

const dataRequire = {
  time: {
    itemType: [DEFINE.DATE],
    category: DEFINE.SINGLE,
  },
  title: {
    itemType: [DEFINE.STR],
    category: DEFINE.SINGLE,
  },
  label: {
    itemType: [DEFINE.STR],
    category: DEFINE.SINGLE,
  },
  url: {
    itemType: [DEFINE.STR],
    category: DEFINE.SINGLE,
  },
};

SimpleKLineViewSpec

基于核新行情图组件库开发的层。

simpleKLine

interface Spec {
  stocks: { code: string; name: string; market: string }[];
}

ExternalViewSpec

基于业务方第三方库自由实现的层，可搭配注册机制实现自定义组件。