类型与接口

本页面记录了从 @kanaries/graphic-walker 导出的核心 TypeScript 类型。导入它们以实现类型安全的使用：

import type {
  IMutField,
  IChart,
  DraggableFieldState,
  IVisualConfigNew,
  IVisualLayout,
  IFilterRule,
  IComputationFunction,
  IThemeKey,
  IDarkMode,
  IUIThemeConfig,
  IChannelScales,
} from '@kanaries/graphic-walker';

字段类型

ISemanticType

type ISemanticType = 'quantitative' | 'nominal' | 'ordinal' | 'temporal';

描述字段中数据的性质。

值	说明	示例
`'quantitative'`	连续数值	营收、温度、计数
`'nominal'`	无序分类	产品名称、国家
`'ordinal'`	有序分类	评级等级、学历等级
`'temporal'`	日期/时间值	订单日期、时间戳

IAnalyticType

type IAnalyticType = 'dimension' | 'measure';

决定字段在聚合中的使用方式。

值	说明
`'dimension'`	用于分组（GROUP BY）
`'measure'`	用于聚合（SUM、AVG 等）

IMutField

interface IMutField {
  fid: string;                          // Field ID — must match a key in your data objects
  name?: string;                        // Display name shown in the UI
  semanticType: ISemanticType;          // Data type classification
  analyticType: IAnalyticType;          // Analysis role
  basename?: string;                    // Base name for derived fields
  disable?: boolean;                    // Hide this field from the UI
  path?: string[];                      // Path for nested data
  offset?: number;                      // Timezone offset for temporal fields
}

IViewField

扩展 IField 并添加排序功能：

interface IViewField extends IField {
  sort?: 'none' | 'ascending' | 'descending';
}

IFilterField

扩展 IViewField 并添加筛选规则：

interface IFilterField extends IViewField {
  rule: IFilterRule | null;
  enableAgg?: boolean;
}

图表规格

IChart

单个图表的完整规格：

interface IChart {
  visId: string;                        // Unique identifier for this chart
  name?: string;                        // Display name
  encodings: DraggableFieldState;       // Field-to-channel mappings
  config: IVisualConfigNew;             // Visualization config
  layout: IVisualLayout;                // Layout config
}

DraggableFieldState

将字段映射到视觉编码通道：

interface DraggableFieldState {
  dimensions: IViewField[];             // Available dimension fields
  measures: IViewField[];               // Available measure fields
  rows: IViewField[];                   // Y-axis encoding
  columns: IViewField[];                // X-axis encoding
  color: IViewField[];                  // Color encoding
  opacity: IViewField[];                // Opacity encoding
  size: IViewField[];                   // Size encoding
  shape: IViewField[];                  // Shape encoding
  theta: IViewField[];                  // Angle encoding (for pie/donut charts)
  radius: IViewField[];                 // Radius encoding
  longitude: IViewField[];              // Longitude for maps
  latitude: IViewField[];               // Latitude for maps
  geoId: IViewField[];                  // Geographic ID for choropleth
  details: IViewField[];                // Detail level (no visual encoding)
  filters: IFilterField[];              // Active filters
  text: IViewField[];                   // Text labels
}

IVisualConfigNew

控制可视化行为：

interface IVisualConfigNew {
  defaultAggregated: boolean;           // Whether to aggregate measures by default
  geoms: string[];                      // Geometry types: 'bar', 'line', 'area', 'point', 'circle', 'tick', 'rect', 'arc', 'boxplot', 'table', 'poi', 'choropleth'
  coordSystem?: 'generic' | 'geographic'; // Coordinate system
  limit: number;                        // Row limit (-1 for no limit)
  folds?: string[];                     // Fields to fold/unpivot
  timezoneDisplayOffset?: number;       // Timezone offset for display
}

IVisualLayout

控制图表布局和外观：

interface IVisualLayout {
  showTableSummary: boolean;
  format: {
    numberFormat?: string;
    timeFormat?: string;
    normalizedNumberFormat?: string;
  };
  primaryColor?: string;
  colorPalette?: string;
  scale?: IConfigScaleSet;
  resolve: {
    x?: boolean;
    y?: boolean;
    color?: boolean;
    opacity?: boolean;
    shape?: boolean;
    size?: boolean;
  };
  size: {
    mode: 'auto' | 'fixed' | 'full';
    width: number;
    height: number;
  };
  useSvg?: boolean;
  interactiveScale: boolean;
  stack: IStackMode;
  showActions: boolean;
  zeroScale: boolean;
  background?: string;
  scaleIncludeUnmatchedChoropleth?: boolean;
  showAllGeoshapeInChoropleth?: boolean;
  renderer?: 'vega-lite' | 'observable-plot';
  geoMapTileUrl?: string;
  geojson?: FeatureCollection;
  geoKey?: string;
  geoUrl?: { type: 'GeoJSON' | 'TopoJSON'; url: string };
}

筛选类型

IFilterRule

type IFilterRule =
  | { type: 'range'; value: [number | null, number | null] }
  | { type: 'temporal range'; value: [number | null, number | null]; offset?: number; format?: string }
  | { type: 'one of'; value: any[] }
  | { type: 'not in'; value: any[] }
  | { type: 'regexp'; value: string; caseSensitive?: boolean };

类型	说明	示例
`'range'`	数值范围筛选	`{ type: 'range', value: [0, 100] }`
`'temporal range'`	日期范围筛选	`{ type: 'temporal range', value: [startTs, endTs] }`
`'one of'`	包含匹配的值	`{ type: 'one of', value: ['A', 'B'] }`
`'not in'`	排除匹配的值	`{ type: 'not in', value: ['C'] }`
`'regexp'`	正则表达式匹配	`{ type: 'regexp', value: '^test' }`

IVisFilter

interface IVisFilter {
  fid: string;           // Field ID to filter on
  rule: IFilterRule;      // The filter rule
}

计算类型

IComputationFunction

服务端计算的函数签名：

type IComputationFunction = (payload: IDataQueryPayload) => Promise<IRow[]>;

IDataQueryPayload

interface IDataQueryPayload {
  workflow: IDataQueryWorkflowStep[];   // Processing pipeline
  limit?: number;
  offset?: number;
}

工作流步骤

计算管道由若干顺序步骤组成：

// Filter step — apply row-level filters
interface IFilterWorkflowStep {
  type: 'filter';
  filters: IVisFilter[];
}
 
// Transform step — compute derived fields
interface ITransformWorkflowStep {
  type: 'transform';
  transform: IFieldTransform[];
}
 
// View step — aggregate or select fields
interface IViewWorkflowStep {
  type: 'view';
  query: IViewQuery[];  // IAggQuery | IFoldQuery | IBinQuery | IRawQuery
}
 
// Sort step — order results
interface ISortWorkflowStep {
  type: 'sort';
  sort: 'ascending' | 'descending';
  by: string[];
}

聚合类型

IAggregator

type IAggregator = 'sum' | 'count' | 'max' | 'min' | 'mean' | 'median' | 'variance' | 'stdev' | 'distinctCount' | 'expr';

外观类型

IThemeKey

type IThemeKey = 'vega' | 'g2' | 'streamlit';

IDarkMode

type IDarkMode = 'media' | 'light' | 'dark';

IStackMode

type IStackMode = 'none' | 'stack' | 'normalize' | 'zero' | 'center';

IUIThemeConfig

亮色和暗色模式的自定义 UI 颜色：

interface IUIThemeConfig {
  light: IColorSet;
  dark: IColorSet;
}
 
interface IColorSet {
  background: string;
  foreground: string;
  primary: string;
  'primary-foreground': string;
  muted: string;
  'muted-foreground': string;
  border: string;
  ring: string;
  // Optional overrides
  card?: string;
  'card-foreground'?: string;
  popover?: string;
  'popover-foreground'?: string;
  secondary?: string;
  'secondary-foreground'?: string;
  accent?: string;
  'accent-foreground'?: string;
  destructive?: string;
  'destructive-foreground'?: string;
  dimension?: string;
  measure?: string;
  input?: string;
}

IChannelScales

视觉通道的自定义比例尺：

interface IChannelScales {
  row?: IScale | ((info: IFieldInfos) => IScale);
  column?: IScale | ((info: IFieldInfos) => IScale);
  color?: IColorScale | ((info: IFieldInfos) => IColorScale);
  opacity?: IScale | ((info: IFieldInfos) => IScale);
  size?: IScale | ((info: IFieldInfos) => IScale);
  radius?: IScale | ((info: IFieldInfos) => IScale);
  theta?: IScale | ((info: IFieldInfos) => IScale);
}

地理类型

IGeographicData

type IGeographicData =
  | { type: 'GeoJSON'; data: FeatureCollection }
  | { type: 'TopoJSON'; data: Topology; objectKey?: string };

IGeoDataItem

type IGeoDataItem = {
  type: 'GeoJSON' | 'TopoJSON';
  name: string;
  url: string;
};

图表导出类型

IChartExportResult

interface IChartExportResult<T extends 'svg' | 'data-url'> {
  mode: T;
  title: string;
  nCols: number;
  nRows: number;
  charts: {
    colIndex: number;
    rowIndex: number;
    width: number;
    height: number;
    canvasWidth: number;
    canvasHeight: number;
    data: string;                       // SVG string or data URL
    canvas(): HTMLCanvasElement | SVGSVGElement | null;
  }[];
  container(): HTMLDivElement | null;
  chartType?: string;
}

IGWHandler

interface IGWHandler {
  chartCount: number;
  chartIndex: number;
  openChart: (index: number) => void;
  renderStatus: 'computing' | 'rendering' | 'idle' | 'error';
  onRenderStatusChange: (cb: (status: IRenderStatus) => void) => () => void;
  exportChart: (mode?: 'svg' | 'data-url') => Promise<IChartExportResult>;
  exportChartList: (mode?: 'svg' | 'data-url') => AsyncGenerator<IChartListExportResult>;
}