@damoqiongqiu/ice-chart 0.30.0 → 0.30.2

package/dist/types/internal.d.mts

@@ -118,7 +118,36 @@ export interface SeriesRawPoints {
     yDomain: [number, number] | null;
     xMonotonic: boolean;
     sizeExtent: [number, number] | null;
+    /**
+     * **去重后的 x 类目**（按首次出现顺序）与它们的出现次数 —— 增量维护。
+     *
+     * 为什么要有它：类目轴每次归一化都要这张表（`buildCategoryValues` / `buildXDomain`），
+     * 而滚动窗口的追加只动**两头**。不增量维护的话，10 万根的窗口每 tick 要重扫两趟 O(n)
+     * （实测：K 线环形追加 4.8ms/tick，其中 ~3ms 就是这两趟）。
+     * 追加 / 淘汰时各 O(1) 更新：新 key 追加到尾部，计数归零的 key 从表里摘掉。
+     */
+    categories: any[];
+    categoryCounts: Map<string, number>;
+    /**
+     * **类目 → 绝对序号**（首次出现在当前窗口里时分配的单调递增号）—— 增量维护。
+     *
+     * 为什么不把「下标」当值：滚动窗口每 tick 从头部淘汰一项，所有下标都要减一，
+     * 那样的表每帧都得整体重写（O(n)）。存**绝对序号**之后，淘汰只删一个 key，
+     * 「下标」由一个基准量相减得到（见 `rawCategoryIndex`）。
+     */
+    categorySeq: Map<string, number>;
+    /** 下一个要分配的绝对序号。不变式：`首项序号 + 类目数`。 */
+    categoryNext: number;
 }
+/**
+ * 类目在**当前** `categories` 里的下标 —— O(1)，给类目轴的 `BandScale.indexOf` 当查表口。
+ *
+ * 依据：绝对序号按「首次出现顺序」分配，而 `categories` 正是按首次出现顺序排的，
+ * 所以存活类目的序号是**连续的一段**（头部淘汰只让这段整体后移；万一出现空洞，
+ * `removeCategory` 会就地压紧）。于是「下标 = 自己的序号 − 首项序号」。
+ * 调用方负责把类目 `String` 化（与 `BandScale` 的查表契约一致）。
+ */
+export declare function rawCategoryIndex(store: SeriesRawPoints, key: string): number;
 export interface InternalSeries {
     id: string;
     index: number;
@@ -247,6 +276,23 @@ export declare function toNumber(value: any): number | null;
  * 「惰性原始点」存储（`rawAccessors`）。两边必须是同一份规则 —— 否则「普通系列」与
  * 「virtual 系列」合成出来的 `xValue / y / name / size` 会分叉，提示框和命中跟着漂。
  */
+export declare function readGenericPointInto(item: any, index: number, option: {
+    type?: string;
+    xField?: string;
+    yField?: string;
+}, out: {
+    xValue: any;
+    y: number | null;
+    size?: number;
+    name?: string;
+    explicitX: boolean;
+}): typeof out;
+/**
+ * 取点（分配版）：普通系列与列存的 `pointAt` 用。
+ *
+ * **热循环请用 `readGenericPointInto` + 复用同一个 scratch**：这个版本每次调用都会
+ * new 一个对象，10 万项的域重算就是每 tick 10 万个短命对象（实测过，GC 直接顶上来）。
+ */
 export declare function readGenericPoint(item: any, index: number, option: {
     type?: string;
     xField?: string;
@@ -294,6 +340,14 @@ export interface InternalAxis {
     index: number;
     /** y 轴位置（x 轴为 left，不使用）。 */
     position: 'left' | 'right';
+    /**
+     * 类目轴的**现成查表口**（可选）：`类目 key → 下标`，O(1)。
+     *
+     * 只有「域原样来自某个增量维护的类目表、且没有被视窗裁剪」时才给得出来
+     * （见 `buildXDomain`）。给了它等于告诉 `BandScale`：不必自己重建索引表 ——
+     * 10 万类目的滚动窗口每帧重建一次那张 Map，曾是整条流水线最大的一笔。
+     */
+    categoryLookup?: (key: string) => number;
 }
 export interface NormalizedOption {
     /** 场景类型：直角坐标 / 极坐标（饼图）/ 雷达图 / 桑基图。 */
@@ -360,6 +414,16 @@ export interface AxisLayout {
     ticks: any[];
     /** 刻度标签文本。 */
     labels: string[];
+    /**
+     * **惰性格式化**：`labels[i] === ''` 且给了这个函数时，第 i 颗的文本要现算（可选）。
+     *
+     * 类目轴一个数据点一个刻度，而真正画得出来的只有抽稀后那几百颗 —— 稠密轴（> 512 颗）
+     * 因此只在布局那一趟格式化**量宽度用的样本**，其余留空，抽稀定稿后由
+     * `thinXAxisLabels` 按留下来的下标现算。数值 / 时间轴刻度本来就少，走全量那条路。
+     */
+    formatLabel?: (index: number) => string;
+    /** 布局那一趟按样本量到的最大标签宽度（惰性格式化时 `labels` 里只有样本，不能再抽样）。 */
+    sampledLabelWidth?: number;
     /** 该轴相对绘图区边缘外扩的像素距离（多轴时同侧的轴逐层外移）。 */
     offset: number;
     /** 刻度标签的最大宽度 / 高度（像素）。 */

package/dist/types/internal.d.ts

@@ -118,7 +118,36 @@ export interface SeriesRawPoints {
     yDomain: [number, number] | null;
     xMonotonic: boolean;
     sizeExtent: [number, number] | null;
+    /**
+     * **去重后的 x 类目**（按首次出现顺序）与它们的出现次数 —— 增量维护。
+     *
+     * 为什么要有它：类目轴每次归一化都要这张表（`buildCategoryValues` / `buildXDomain`），
+     * 而滚动窗口的追加只动**两头**。不增量维护的话，10 万根的窗口每 tick 要重扫两趟 O(n)
+     * （实测：K 线环形追加 4.8ms/tick，其中 ~3ms 就是这两趟）。
+     * 追加 / 淘汰时各 O(1) 更新：新 key 追加到尾部，计数归零的 key 从表里摘掉。
+     */
+    categories: any[];
+    categoryCounts: Map<string, number>;
+    /**
+     * **类目 → 绝对序号**（首次出现在当前窗口里时分配的单调递增号）—— 增量维护。
+     *
+     * 为什么不把「下标」当值：滚动窗口每 tick 从头部淘汰一项，所有下标都要减一，
+     * 那样的表每帧都得整体重写（O(n)）。存**绝对序号**之后，淘汰只删一个 key，
+     * 「下标」由一个基准量相减得到（见 `rawCategoryIndex`）。
+     */
+    categorySeq: Map<string, number>;
+    /** 下一个要分配的绝对序号。不变式：`首项序号 + 类目数`。 */
+    categoryNext: number;
 }
+/**
+ * 类目在**当前** `categories` 里的下标 —— O(1)，给类目轴的 `BandScale.indexOf` 当查表口。
+ *
+ * 依据：绝对序号按「首次出现顺序」分配，而 `categories` 正是按首次出现顺序排的，
+ * 所以存活类目的序号是**连续的一段**（头部淘汰只让这段整体后移；万一出现空洞，
+ * `removeCategory` 会就地压紧）。于是「下标 = 自己的序号 − 首项序号」。
+ * 调用方负责把类目 `String` 化（与 `BandScale` 的查表契约一致）。
+ */
+export declare function rawCategoryIndex(store: SeriesRawPoints, key: string): number;
 export interface InternalSeries {
     id: string;
     index: number;
@@ -247,6 +276,23 @@ export declare function toNumber(value: any): number | null;
  * 「惰性原始点」存储（`rawAccessors`）。两边必须是同一份规则 —— 否则「普通系列」与
  * 「virtual 系列」合成出来的 `xValue / y / name / size` 会分叉，提示框和命中跟着漂。
  */
+export declare function readGenericPointInto(item: any, index: number, option: {
+    type?: string;
+    xField?: string;
+    yField?: string;
+}, out: {
+    xValue: any;
+    y: number | null;
+    size?: number;
+    name?: string;
+    explicitX: boolean;
+}): typeof out;
+/**
+ * 取点（分配版）：普通系列与列存的 `pointAt` 用。
+ *
+ * **热循环请用 `readGenericPointInto` + 复用同一个 scratch**：这个版本每次调用都会
+ * new 一个对象，10 万项的域重算就是每 tick 10 万个短命对象（实测过，GC 直接顶上来）。
+ */
 export declare function readGenericPoint(item: any, index: number, option: {
     type?: string;
     xField?: string;
@@ -294,6 +340,14 @@ export interface InternalAxis {
     index: number;
     /** y 轴位置（x 轴为 left，不使用）。 */
     position: 'left' | 'right';
+    /**
+     * 类目轴的**现成查表口**（可选）：`类目 key → 下标`，O(1)。
+     *
+     * 只有「域原样来自某个增量维护的类目表、且没有被视窗裁剪」时才给得出来
+     * （见 `buildXDomain`）。给了它等于告诉 `BandScale`：不必自己重建索引表 ——
+     * 10 万类目的滚动窗口每帧重建一次那张 Map，曾是整条流水线最大的一笔。
+     */
+    categoryLookup?: (key: string) => number;
 }
 export interface NormalizedOption {
     /** 场景类型：直角坐标 / 极坐标（饼图）/ 雷达图 / 桑基图。 */
@@ -360,6 +414,16 @@ export interface AxisLayout {
     ticks: any[];
     /** 刻度标签文本。 */
     labels: string[];
+    /**
+     * **惰性格式化**：`labels[i] === ''` 且给了这个函数时，第 i 颗的文本要现算（可选）。
+     *
+     * 类目轴一个数据点一个刻度，而真正画得出来的只有抽稀后那几百颗 —— 稠密轴（> 512 颗）
+     * 因此只在布局那一趟格式化**量宽度用的样本**，其余留空，抽稀定稿后由
+     * `thinXAxisLabels` 按留下来的下标现算。数值 / 时间轴刻度本来就少，走全量那条路。
+     */
+    formatLabel?: (index: number) => string;
+    /** 布局那一趟按样本量到的最大标签宽度（惰性格式化时 `labels` 里只有样本，不能再抽样）。 */
+    sampledLabelWidth?: number;
     /** 该轴相对绘图区边缘外扩的像素距离（多轴时同侧的轴逐层外移）。 */
     offset: number;
     /** 刻度标签的最大宽度 / 高度（像素）。 */

package/dist/types/scale/BandScale.d.mts

@@ -24,6 +24,14 @@ export declare class BandScale implements Scale {
      */
     private indexCache;
     private indexCacheDomain;
+    /**
+     * 归一化交下来的**现成查表口**（可选）。
+     *
+     * 类目表是增量维护的那种轴（惰性原始点 / 滚动窗口）会带上它 —— 那时自建表等于
+     * 每帧重写一遍 10 万条的 Map，实测占整条流水线的一半。给了查表口就走它：
+     * 一个类目的下标是一次 Map 查询加一次减法。
+     */
+    private lookup;
     constructor(domain: any[], range: [number, number], options?: CreateScaleOptions);
     private computeStep;
     private indexOf;

package/dist/types/scale/BandScale.d.ts

@@ -24,6 +24,14 @@ export declare class BandScale implements Scale {
      */
     private indexCache;
     private indexCacheDomain;
+    /**
+     * 归一化交下来的**现成查表口**（可选）。
+     *
+     * 类目表是增量维护的那种轴（惰性原始点 / 滚动窗口）会带上它 —— 那时自建表等于
+     * 每帧重写一遍 10 万条的 Map，实测占整条流水线的一半。给了查表口就走它：
+     * 一个类目的下标是一次 Map 查询加一次减法。
+     */
+    private lookup;
     constructor(domain: any[], range: [number, number], options?: CreateScaleOptions);
     private computeStep;
     private indexOf;

package/dist/types/scale/Scale.d.mts

@@ -34,5 +34,11 @@ export interface CreateScaleOptions {
     logBase?: number;
     /** 时间刻度的期望数量。 */
     tickCount?: number;
+    /**
+     * 类目轴的**现成查表口**：`类目 key → 下标`。给了它 `BandScale` 就不自建索引表。
+     *
+     * 由归一化在「域原样来自增量维护的类目表」时给出（见 `InternalAxis.categoryLookup`）。
+     */
+    categoryLookup?: (key: string) => number;
 }
 export declare function createScale(type: ScaleType, domain: any[], range: [number, number], options?: CreateScaleOptions): Scale;

package/dist/types/scale/Scale.d.ts

@@ -34,5 +34,11 @@ export interface CreateScaleOptions {
     logBase?: number;
     /** 时间刻度的期望数量。 */
     tickCount?: number;
+    /**
+     * 类目轴的**现成查表口**：`类目 key → 下标`。给了它 `BandScale` 就不自建索引表。
+     *
+     * 由归一化在「域原样来自增量维护的类目表」时给出（见 `InternalAxis.categoryLookup`）。
+     */
+    categoryLookup?: (key: string) => number;
 }
 export declare function createScale(type: ScaleType, domain: any[], range: [number, number], options?: CreateScaleOptions): Scale;

package/package.json

@@ -1,7 +1,7 @@
 {
   "author": "大漠穷秋",
   "name": "@damoqiongqiu/ice-chart",
-  "version": "0.30.0",
+  "version": "0.30.2",
   "license": "MIT",
   "description": "基于 ice-render Canvas 引擎的交互式图表库：命中测试与事件派发由引擎承担，图表层只做「数据 ↔ 像素 ↔ 语义事件」。",
   "keywords": [