构建高性能Canvas时间线：深入TypeScript虚拟化渲染实战

引言

在数据驱动的时代，时间线（Timeline）是展示事件序列、历史记录、项目计划的常见方式。然而，当数据量达到数千甚至数万条时，传统的DOM渲染方式会变得极其缓慢，页面卡顿、内存飙升成为常态。

想象一下，你需要在一个甘特图中展示一个大型软件项目的所有任务——成百上千个任务条，跨越数月甚至数年的时间跨度。如果每个任务都作为一个DOM元素渲染，浏览器需要维护庞大的DOM树，计算布局、样式，这无疑会成为性能灾难。

这就是我们今天要解决的痛点：如何利用Canvas的强大绘制能力，并结合虚拟化渲染技术，在浏览器中高效、流畅地可视化海量时间线数据？

我们将深入探索一个用TypeScript构建的Canvas时间线可视化库的核心原理。本文不是对该库的简单介绍，而是一次从零到一的深度解析。你将学到：

Canvas渲染引擎的核心原理：如何用requestAnimationFrame实现丝滑动画。
虚拟化渲染的精髓：只绘制视口内可见的元素，无论数据量多大。
TypeScript架构设计：如何用面向对象和泛型构建可扩展的库。
交互系统实现：如何在Canvas上实现拖拽、缩放、点击等复杂交互。
性能优化最佳实践：离屏Canvas、对象池、脏矩形等高级技巧。

读完本文，你将不仅能理解这个库的设计哲学，更能将其中的技巧应用到你自己的高性能可视化项目中。

核心概念：Canvas与虚拟化渲染

为什么是Canvas？

Web上有多种渲染技术，选择Canvas而非SVG或DOM，是出于性能的极致追求。

渲染技术	优点	缺点	适用场景
DOM/SVG	易于交互，可访问性好，样式丰富	元素数量多时（>1000），布局计算和重绘开销巨大	元素少、交互复杂的界面
Canvas	像素级控制，渲染性能与元素数量无关，适合海量数据	交互需手动实现，可访问性差，无内置DOM事件	图表、游戏、海量数据可视化
WebGL	利用GPU加速，性能极高	API复杂，开发成本高，主要用于3D	3D场景、复杂数据可视化

对于时间线这种可能包含数万个“任务条”的场景，Canvas是最佳选择。 因为无论你绘制1000个还是100000个矩形，Canvas的绘制开销主要取决于像素的填充面积，而不是“对象”的数量。

什么是虚拟化渲染？

虚拟化（Virtualization）或称“窗口化”（Windowing），是一种仅渲染视口（Viewport）内可见内容的技术。这在长列表、大型表格、时间线中至关重要。

没有虚拟化的时间线渲染流程：

数据（10000个事件） -> 计算所有事件位置 -> 创建10000个DOM元素/绘制10000个Canvas图形 -> 一次性渲染 -> 浏览器崩溃 💥

有虚拟化的时间线渲染流程：

数据（10000个事件） -> 只计算视口内（比如50个）事件的位置 -> 只绘制这50个事件 -> 用户滚动/缩放时，动态计算并绘制新的可见事件 -> 流畅运行 ✅

下面是一个简单的概念图，展示了虚拟化的工作原理：

+------------------+
| 可视区域 (Viewport) |  <-- 只绘制这部分包含的事件
| +----+ +----+   |
| | E1 | | E2 |   |  <-- E1, E2 被绘制
| +----+ +----+   |
+------------------+
| 不可见区域 |  <-- 这里的事件 (E3, E4...) 不被绘制，节省大量资源
|  E3, E4 ...     |
+------------------+

核心数据结构：时间线与事件

在开始编码前，我们需要定义核心的数据结构。一个清晰的数据模型是所有上层功能的基础。

// 事件接口定义。每个事件都有一个唯一的ID、开始时间、结束时间、标签和可选的颜色。
interface TimelineEvent {
  id: string; // 唯一标识符，如 'event-1'
  start: Date | number; // 开始时间，支持Date对象或时间戳
  end: Date | number;   // 结束时间
  label: string;        // 显示的标签，如 “产品需求评审”
  color?: string;       // 事件条颜色，如 '#4CAF50'
  metadata?: any;       // 任意附加数据
}

// 视口状态接口。它定义了时间线当前“看”到的时间范围和像素尺寸。
interface ViewportState {
  startDate: Date;      // 视口左边界对应的时间
  endDate: Date;        // 视口右边界对应的时间
  width: number;        // Canvas 的宽度（像素）
  height: number;       // Canvas 的高度（像素）
}

// 时间线配置接口。
interface TimelineConfig {
  container: HTMLElement; // 容器DOM元素
  events: TimelineEvent[]; // 所有事件数据
  initialViewport?: Partial<ViewportState>; // 初始视口状态
  // ... 其他配置，如行高、字体、颜色等
}

关键点：将时间映射到像素坐标是核心。我们需要一个函数 timeToPixel(time, viewport): number，它能将时间戳转换为在Canvas上的X坐标。

基础用法：从零构建一个最小时间线

让我们从最简单的部分开始，一步步搭建我们的时间线。我们将创建一个 TimelineRenderer 类。

步骤1：初始化Canvas和基础绘制

// timeline-renderer.ts
import { TimelineEvent, ViewportState, TimelineConfig } from './types';

class TimelineRenderer {
  private canvas: HTMLCanvasElement;
  private ctx: CanvasRenderingContext2D;
  private config: TimelineConfig;
  private viewport: ViewportState;

  constructor(config: TimelineConfig) {
    this.config = config;
    this.canvas = document.createElement('canvas'); // 创建Canvas元素
    this.ctx = this.canvas.getContext('2d')!; // 获取2D绘图上下文
    
    // 将Canvas添加到容器中
    this.config.container.appendChild(this.canvas);
    this.setupCanvas(); // 设置Canvas尺寸
    this.initializeViewport(); // 初始化视口
    this.render(); // 首次渲染
  }

  // 设置Canvas的物理尺寸（分辨率），并考虑高DPI屏幕（Retina）
  private setupCanvas(): void {
    const dpr = window.devicePixelRatio || 1; // 获取设备像素比
    const rect = this.config.container.getBoundingClientRect();
    
    // 设置Canvas元素在页面中的CSS尺寸
    this.canvas.style.width = `${rect.width}px`;
    this.canvas.style.height = `${rect.height}px`;
    
    // 设置Canvas的绘图表面尺寸（物理像素），以支持高清屏
    this.canvas.width = rect.width * dpr;
    this.canvas.height = rect.height * dpr;
    
    // 根据设备像素比缩放绘图上下文，这样我们就可以使用CSS像素作为坐标单位
    this.ctx.scale(dpr, dpr);
  }

  // 初始化视口状态，默认显示最近7天
  private initializeViewport(): void {
    const now = new Date();
    const sevenDaysAgo = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000);
    const rect = this.config.container.getBoundingClientRect();
    
    this.viewport = {
      startDate: this.config.initialViewport?.startDate || sevenDaysAgo,
      endDate: this.config.initialViewport?.endDate || now,
      width: rect.width,
      height: rect.height,
    };
  }

  // 核心渲染方法
  public render(): void {
    const { ctx, viewport } = this;
    const { width, height } = viewport;

    // 1. 清空画布
    ctx.clearRect(0, 0, width, height);

    // 2. 绘制背景（可选）
    ctx.fillStyle = '#f8f9fa';
    ctx.fillRect(0, 0, width, height);

    // 3. 绘制时间轴标尺（这里简化为一条线）
    ctx.strokeStyle = '#dee2e6';
    ctx.lineWidth = 1;
    ctx.beginPath();
    ctx.moveTo(0, 50); // 假设时间轴在y=50的位置
    ctx.lineTo(width, 50);
    ctx.stroke();

    // 4. 绘制事件（核心部分！）
    this.drawEvents();
  }

  // 将时间转换为X坐标的核心函数
  private timeToPixel(time: Date): number {
    const { startDate, endDate, width } = this.viewport;
    const timeRange = endDate.getTime() - startDate.getTime();
    if (timeRange === 0) return 0;
    
    // 计算时间点在时间范围内的比例，然后乘以宽度
    const proportion = (time.getTime() - startDate.getTime()) / timeRange;
    return proportion * width;
  }

  // 绘制所有可见事件
  private drawEvents(): void {
    const { ctx, viewport, config } = this;
    const rowHeight = 40; // 每行事件的高度
    const topPadding = 60; // 距离顶部的间距
    
    // 遍历所有事件（在虚拟化优化前，我们先遍历全部）
    config.events.forEach((event, index) => {
      // 计算事件在画布上的位置
      const startX = this.timeToPixel(new Date(event.start));
      const endX = this.timeToPixel(new Date(event.end));
      const y = topPadding + (index * rowHeight);
      
      // 只绘制在视口内的事件（简单的裁剪优化）
      if (endX < 0 || startX > viewport.width) {
        return; // 事件完全在视口外，跳过
      }
      
      // 绘制事件条
      const eventWidth = endX - startX;
      ctx.fillStyle = event.color || '#2196F3';
      ctx.fillRect(startX, y, eventWidth, rowHeight - 4);
      
      // 绘制事件标签
      ctx.fillStyle = '#ffffff';
      ctx.font = '12px Arial';
      ctx.textBaseline = 'middle';
      // 标签位置：事件条内部，居左对齐，留出一些内边距
      ctx.fillText(event.label, startX + 4, y + (rowHeight - 4) / 2);
    });
  }
}

// 使用示例
const events: TimelineEvent[] = [
  { id: '1', start: '2023-10-01', end: '2023-10-05', label: '需求分析', color: '#4CAF50' },
  { id: '2', start: '2023-10-03', end: '2023-10-10', label: 'UI设计', color: '#FF9800' },
  { id: '3', start: '2023-10-08', end: '2023-10-15', label: '前端开发', color: '#2196F3' },
];

const container = document.getElementById('timeline')!;
const renderer = new TimelineRenderer({ container, events });

上面代码的解释：

setupCanvas：这是处理高DPI屏幕的关键。我们通过 devicePixelRatio 设置Canvas的实际像素尺寸，然后用CSS控制其显示尺寸，最后用 ctx.scale 确保绘制时使用的是CSS像素单位，避免图形模糊。
timeToPixel：这是时间映射的核心。它计算一个时间点在当前视口时间范围内的比例，然后乘以画布宽度，得到X坐标。
drawEvents：遍历事件，计算其像素坐标。这里有一个初步的虚拟化思想：if (endX < 0 || startX > viewport.width) return; 跳过完全在视口外的事件。

步骤2：实现交互——缩放与平移

一个静态的时间线是没用的。我们需要让用户能够缩放（改变时间范围）和平移（滚动时间）。

// 在 TimelineRenderer 类中添加以下方法
private isDragging = false;
private lastX = 0;
private startViewportStartDate?: Date;

// 初始化交互事件监听
private setupInteractions(): void {
  this.canvas.addEventListener('wheel', this.handleWheel.bind(this));
  this.canvas.addEventListener('mousedown', this.handleMouseDown.bind(this));
  this.canvas.addEventListener('mousemove', this.handleMouseMove.bind(this));
  this.canvas.addEventListener('mouseup', this.handleMouseUp.bind(this));
}

// 处理鼠标滚轮事件（缩放）
private handleWheel(event: WheelEvent): void {
  event.preventDefault(); // 阻止页面默认滚动
  
  const { viewport } = this;
  const mouseX = event.offsetX; // 鼠标在Canvas上的X坐标
  
  // 计算鼠标位置对应的时间点
  const timeRange = viewport.endDate.getTime() - viewport.startDate.getTime();
  const proportion = mouseX / viewport.width;
  const mouseTime = new Date(viewport.startDate.getTime() + proportion * timeRange);
  
  // 计算缩放因子，deltaY负值表示向上滚动（放大）
  const zoomFactor = event.deltaY > 0 ? 1.1 : 0.9;
  
  // 计算新的时间范围，保持鼠标指向的时间点不动
  const newTimeRange = timeRange * zoomFactor;
  const newStartDate = new Date(mouseTime.getTime() - (proportion * newTimeRange));
  const newEndDate = new Date(newStartDate.getTime() + newTimeRange);
  
  // 更新视口状态
  this.viewport = {
    ...viewport,
    startDate: newStartDate,
    endDate: newEndDate,
  };
  
  // 重新渲染
  this.render();
}

// 处理鼠标按下事件（开始平移）
private handleMouseDown(event: MouseEvent): void {
  this.isDragging = true;
  this.lastX = event.offsetX;
  this.startViewportStartDate = new Date(this.viewport.startDate);
  this.canvas.style.cursor = 'grabbing';
}

// 处理鼠标移动事件（执行平移）
private handleMouseMove(event: MouseEvent): void {
  if (!this.isDragging) return;
  
  const deltaX = event.offsetX - this.lastX;
  const { startDate, endDate, width } = this.viewport;
  const timeRange = endDate.getTime() - startDate.getTime();
  
  // 将像素偏移量转换为时间偏移量
  const timeOffset = (deltaX / width) * timeRange;
  
  // 计算新的开始时间，保持时间范围不变
  const newStartDate = new Date(this.startViewportStartDate!.getTime() - timeOffset);
  const newEndDate = new Date(newStartDate.getTime() + timeRange);
  
  // 更新视口状态
  this.viewport = {
    ...this.viewport,
    startDate: newStartDate,
    endDate: newEndDate,
  };
  
  // 重新渲染
  this.render();
}

// 处理鼠标松开事件（结束平移）
private handleMouseUp(): void {
  this.isDragging = false;
  this.canvas.style.cursor = 'default';
}

交互实现原理：

缩放：监听 wheel 事件。计算鼠标位置对应的“锚点”时间，然后按比例调整时间范围，实现以鼠标位置为中心的缩放。
平移：监听 mousedown、mousemove、mouseup。在 mousemove 中，计算鼠标的像素移动量，并将其转换为时间偏移量，更新视口的起止时间，实现拖拽平移。

进阶技巧：真正的虚拟化与性能优化

上面的 drawEvents 方法遍历了所有事件，即使大多数不在视口内。当事件数达到十万级别时，遍历本身就会成为瓶颈。我们需要更智能的虚拟化。

技巧1：基于空间索引的事件筛选

我们可以使用空间索引快速找到视口内的事件。一个简单有效的索引是按行分组或基于时间的网格。这里我们采用更通用的基于时间的二分查找。

// 假设我们的事件数组已经按 `start` 时间排好序（这是关键前提！）
private sortedEvents: TimelineEvent[] = [];

// 初始化时排序
constructor(config: TimelineConfig) {
  // ... 其他初始化
  this.sortedEvents = [...config.events].sort((a, b) => 
    new Date(a.start).getTime() - new Date(b.start).getTime()
  );
}

// 使用二分查找找到视口内第一个可能可见的事件索引
private findFirstVisibleEventIndex(): number {
  const { startDate } = this.viewport;
  let low = 0;
  let high = this.sortedEvents.length - 1;
  let result = this.sortedEvents.length; // 默认没有找到
  
  while (low <= high) {
    const mid = Math.floor((low + high) / 2);
    const event = this.sortedEvents[mid];
    if (new Date(event.start) >= startDate) {
      result = mid;
      high = mid - 1; // 继续在左半部分寻找更早的
    } else {
      low = mid + 1;
    }
  }
  return result;
}

// 优化后的drawEvents方法
private drawEvents(): void {
  // ... 清空画布等步骤
  
  // 1. 找到第一个可能在视口内的事件（其结束时间 >= 视口开始时间）
  const startIndex = this.findFirstVisibleEventIndex();
  
  // 2. 从这个索引开始，只遍历可能可见的事件
  for (let i = startIndex; i < this.sortedEvents.length; i++) {
    const event = this.sortedEvents[i];
    const eventStart = new Date(event.start);
    const eventEnd = new Date(event.end);
    
    // 3. 如果事件的开始时间已经晚于视口结束时间，后续事件都不可见，提前终止循环
    if (eventStart > this.viewport.endDate) {
      break;
    }
    
    // 4. 检查事件是否真的与视口有重叠（考虑事件可能很长）
    if (eventEnd < this.viewport.startDate) {
      continue; // 事件在视口之前，跳过
    }
    
    // ... 计算位置并绘制事件（同上）
  }
}

优化效果：对于10万个事件，视口内可能只有50个。优化前遍历10万次，优化后只需遍历大约50-100次（找到起始点后的连续事件），性能提升可达1000倍。

技巧2：离屏Canvas与分层渲染

频繁重绘整个画布仍然很消耗性能。我们可以将渲染分成不同层，每层使用不同的刷新频率。

class LayeredTimelineRenderer {
  private bgCanvas: HTMLCanvasElement; // 背景层：网格、刻度
  private eventCanvas: HTMLCanvasElement; // 事件层：事件条、标签
  private interactionCanvas: HTMLCanvasElement; // 交互层：拖拽选框、悬停高亮
  
  // 背景层更新频率低，只在缩放或窗口大小改变时重绘
  private renderBackground(): void {
    // 绘制固定背景、时间刻度网格
  }
  
  // 事件层在视口变化时重绘
  private renderEvents(): void {
    // 绘制事件条
  }
  
  // 交互层只在用户交互时（如鼠标移动）重绘，频率最高但内容最少
  private renderInteraction(): void {
    // 绘制悬停效果等
  }
}

分层渲染的好处：当用户只是移动鼠标时，我们只需要重绘交互层（可能只绘制一个小小的高亮框），而事件层和背景层保持不变，节省了大量绘制指令。

技巧3：对象池（Object Pool）减少GC压力

在JavaScript中，频繁创建和销毁对象会导致垃圾回收（GC）暂停，造成卡顿。我们可以使用对象池来重用对象。

// 一个简单的对象池实现
class ObjectPool<T> {
  private pool: T[] = [];
  private factory: () => T;

  constructor(factory: () => T, initialSize: number = 10) {
    this.factory = factory;
    // 预创建对象
    for (let i = 0; i < initialSize; i++) {
      this.pool.push(factory());
    }
  }

  // 获取对象
  acquire(): T {
    if (this.pool.length === 0) {
      return this.factory(); // 池空了就创建新的
    }
    return this.pool.pop()!;
  }

  // 释放对象，归还到池中
  release(obj: T): void {
    this.pool.push(obj);
  }
}

// 在时间线中，我们可能需要频繁创建临时点对象
type Point = { x: number; y: number };
const pointPool = new ObjectPool<Point>(() => ({ x: 0, y: 0 }), 100);

// 使用示例
function processPoints() {
  const points = [];
  for (let i = 0; i < 1000; i++) {
    const p = pointPool.acquire(); // 从池中获取，而不是 new
    p.x = Math.random();
    p.y = Math.random();
    points.push(p);
  }
  
  // ... 处理点
  
  // 使用完毕，全部归还
  points.forEach(p => pointPool.release(p));
}

实战案例：构建一个完整的项目时间线

让我们将所有概念整合起来，构建一个展示软件项目开发进度的完整时间线。这个时间线将支持：

多行显示（不同行代表不同开发阶段）
时间刻度（天、周、月）
鼠标悬停显示详情
响应式布局

完整代码实现

// project-timeline.ts
import { TimelineEvent, ViewportState } from './types';

class ProjectTimeline {
  // ... 省略部分初始化代码，与之前类似
  
  private renderTimeAxis(): void {
    const { ctx, viewport } = this;
    const { startDate, endDate, width } = viewport;
    const timeRange = endDate.getTime() - startDate.getTime();
    
    // 根据时间范围动态选择刻度间隔
    let tickInterval: number; // 毫秒
    let format: (d: Date) => string;
    
    if (timeRange < 2 * 24 * 60 * 60 * 1000) { // < 2天，每小时一个刻度
      tickInterval = 60 * 60 * 1000;
      format = (d) => `${d.getHours()}:00`;
    } else if (timeRange < 14 * 24 * 60 * 60 * 1000) { // < 2周，每天一个刻度
      tickInterval = 24 * 60 * 60 * 1000;
      format = (d) => `${d.getMonth() + 1}/${d.getDate()}`;
    } else { // 大于2周，每周一个刻度
      tickInterval = 7 * 24 * 60 * 60 * 1000;
      format = (d) => `${d.getMonth() + 1}/${d.getDate()}`;
    }
    
    // 计算第一个刻度的位置
    let tickTime = new Date(Math.ceil(startDate.getTime() / tickInterval) * tickInterval);
    
    ctx.strokeStyle = '#ced4da';
    ctx.fillStyle = '#868e96';
    ctx.font = '10px Arial';
    ctx.textAlign = 'center';
    
    // 绘制刻度线和标签
    while (tickTime <= endDate) {
      const x = this.timeToPixel(tickTime);
      
      // 绘制垂直刻度线
      ctx.beginPath();
      ctx.moveTo(x, 0);
      ctx.lineTo(x, this.viewport.height);
      ctx.stroke();
      
      // 绘制时间标签
      ctx.fillText(format(tickTime), x, 15);
      
      tickTime = new Date(tickTime.getTime() + tickInterval);
    }
  }

  // 绘制事件，支持多行
  private drawEvents(): void {
    const { ctx, viewport } = this;
    const rowHeight = 30;
    const topPadding = 30; // 时间轴高度
    
    // 按行（阶段）分组事件
    const eventsByRow = new Map<number, TimelineEvent[]>();
    this.sortedEvents.forEach(event => {
      // 假设事件有一个 `row` 属性表示所在行
      const row = (event as any).row || 0;
      if (!eventsByRow.has(row)) {
        eventsByRow.set(row, []);
      }
      eventsByRow.get(row)!.push(event);
    });

    // 逐行绘制
    eventsByRow.forEach((events, rowIndex) => {
      const y = topPadding + (rowIndex * rowHeight);
      
      // 绘制行背景（交替颜色）
      ctx.fillStyle = rowIndex % 2 === 0 ? '#f8f9fa' : '#e9ecef';
      ctx.fillRect(0, y, viewport.width, rowHeight);
      
      // 绘制该行内的事件（使用之前的虚拟化逻辑）
      this.drawEventsInRow(events, y, rowHeight);
    });
  }

  // 鼠标悬停效果
  private handleMouseMove(event: MouseEvent): void {
    // ... 平移逻辑（如果正在拖拽）
    
    // 计算鼠标位置对应的事件
    const mouseX = event.offsetX;
    const mouseY = event.offsetY;
    const { topPadding } = this.layout;
    const { rowHeight } = this.layout;
    
    // 计算鼠标所在行
    const rowIndex = Math.floor((mouseY - topPadding) / rowHeight);
    
    // 在该行内查找鼠标下的事件
    const eventsInRow = this.eventsByRow.get(rowIndex) || [];
    let hoveredEvent: TimelineEvent | null = null;
    
    for (const event of eventsInRow) {
      const startX = this.timeToPixel(new Date(event.start));
      const endX = this.timeToPixel(new Date(event.end));
      
      if (mouseX >= startX && mouseX <= endX) {
        hoveredEvent = event;
        break;
      }
    }
    
    // 更新悬停状态并重绘交互层
    this.hoveredEvent = hoveredEvent;
    this.renderInteractionLayer();
  }

  // 绘制悬停详情弹窗
  private renderInteractionLayer(): void {
    const { interactionCtx } = this;
    interactionCtx.clearRect(0, 0, this.viewport.width, this.viewport.height);
    
    if (!this.hoveredEvent) return;
    
    const event = this.hoveredEvent;
    const startX = this.timeToPixel(new Date(event.start));
    const endX = this.timeToPixel(new Date(event.end));
    const y = this.getEventY(event);
    
    // 绘制高亮边框
    interactionCtx.strokeStyle = '#000';
    interactionCtx.lineWidth = 2;
    interactionCtx.strokeRect(startX, y, endX - startX, this.layout.rowHeight - 4);
    
    // 绘制详情弹窗
    const popupX = startX + 10;
    const popupY = y - 10;
    const popupWidth = 200;
    const popupHeight = 60;
    
    // 弹窗背景
    interactionCtx.fillStyle = 'rgba(0, 0, 0, 0.8)';
    interactionCtx.roundRect(popupX, popupY - popupHeight, popupWidth, popupHeight, 4);
    interactionCtx.fill();
    
    // 弹窗文字
    interactionCtx.fillStyle = '#fff';
    interactionCtx.font = '12px Arial';
    interactionCtx.fillText(`任务: ${event.label}`, popupX + 10, popupY - popupHeight + 20);
    interactionCtx.fillText(`开始: ${new Date(event.start).toLocaleDateString()}`, popupX + 10, popupY - popupHeight + 35);
    interactionCtx.fillText(`结束: ${new Date(event.end).toLocaleDateString()}`, popupX + 10, popupY - popupHeight + 50);
  }
}

响应式处理

时间线需要适应容器大小的变化，例如浏览器窗口调整大小或移动设备旋转。

// 在 ProjectTimeline 类中
private setupResizeObserver(): void {
  const resizeObserver = new ResizeObserver(entries => {
    for (const entry of entries) {
      if (entry.target === this.config.container) {
        this.handleResize(entry.contentRect);
      }
    }
  });
  
  resizeObserver.observe(this.config.container);
}

private handleResize(rect: DOMRectReadOnly): void {
  // 更新视口尺寸
  this.viewport.width = rect.width;
  this.viewport.height = rect.height;
  
  // 更新所有Canvas的尺寸
  this.setupCanvas(this.bgCanvas, rect);
  this.setupCanvas(this.eventCanvas, rect);
  this.setupCanvas(this.interactionCanvas, rect);
  
  // 重新渲染所有层
  this.renderBackground();
  this.renderEvents();
}

常见问题（FAQ）

1. Canvas渲染的文字在高DPI屏幕上模糊怎么办？

答：必须正确处理 devicePixelRatio。关键步骤：

const dpr = window.devicePixelRatio || 1;
canvas.width = width * dpr;  // 设置物理像素
canvas.height = height * dpr;
canvas.style.width = `${width}px`; // 设置CSS像素
canvas.style.height = `${height}px`;
ctx.scale(dpr, dpr); // 缩放绘图上下文

之后所有绘图命令都使用CSS像素作为单位，Canvas内部会自动适配高清屏。

2. 为什么事件条在快速滚动时会“抖动”或“闪烁”？

答：这通常是由于坐标计算精度问题导致的。解决方法：

在 timeToPixel 函数中，使用整数坐标：return Math.round(proportion * width);
使用 requestAnimationFrame 确保渲染与浏览器的刷新率同步，避免在事件处理函数中直接调用 render()。

3. 如何为大量事件实现高性能的拖拽排序或移动？

答：对于海量事件，直接操作事件数据并重绘整个时间线是不现实的。可以采用以下策略：

乐观更新：先在视图中移动事件条（可能使用一个临时的叠加Canvas层），然后在动画结束后再更新数据并重绘。
分块更新：将事件数据按行或时间范围分块，只更新受影响的块对应的Canvas区域。
使用Web Worker：将数据计算和排序等CPU密集型任务移到Web Worker中，保持主线程流畅。

4. 如何支持触摸设备（移动端）？

答：需要添加触摸事件监听器，并正确处理多点触控（用于缩放）。核心是将 touch 事件映射为与 mouse 和 wheel 类似的逻辑。

// 处理触摸事件
this.canvas.addEventListener('touchstart', this.handleTouchStart.bind(this));
this.canvas.addEventListener('touchmove', this.handleTouchMove.bind(this));

private handleTouchMove(event: TouchEvent): void {
  if (event.touches.length === 1) {
    // 单指拖动：平移
    const touch = event.touches[0];
    this.handleDrag(touch.clientX - this.rect.left, touch.clientY - this.rect.top);
  } else if (event.touches.length === 2) {
    // 双指缩放
    const distance = this.getTouchDistance(event.touches);
    this.handlePinchZoom(distance);
  }
  event.preventDefault();
}

总结

构建一个高性能的Canvas时间线可视化库，不仅仅是画几个矩形那么简单。它是一门结合了计算机图形学、数据结构、交互设计和性能优化的艺术。

核心要点回顾：

Canvas选择：当元素数量巨大时，Canvas的绘制性能远超DOM/SVG。
虚拟化渲染：只绘制视口内可见的内容，是应对海量数据的银弹。结合二分查找等算法可以进一步提升性能。
分层架构：将渲染分解为背景层、事件层、交互层，可以实现差异化的更新频率，减少不必要的重绘。
交互设计：在Canvas上实现交互需要手动处理坐标转换和事件检测，但也能获得更精细的控制和更高的性能。
TypeScript优势：强大的类型系统有助于构建可靠、可维护的库，泛型、接口等特性在设计复杂数据流时尤为有用。

延伸阅读建议：

Canvas性能优化：深入学习 OffscreenCanvas、WebGL 基础、脏矩形渲染技术。
空间数据结构：探索R树（R-tree）、四叉树（Quadtree）等高级空间索引，用于超大规模事件的快速查找。
专业图表库源码：阅读 ECharts、D3.js 等优秀库的源码，学习工业级的实现方案。
Web性能指标：了解 Lighthouse、Core Web Vitals 等工具和指标，用数据驱动优化。

构建这样的库是一个充满挑战但极其有收获的过程。它不仅锻炼你的工程能力，更让你对浏览器的工作原理有更深的理解。希望本文为你打开了通往高性能Web可视化世界的大门。

本文基于Reddit帖子 "I built a canvas-based timeline visualisation library with virtualised rendering in TypeScript" 的热点讨论进行深度技术解析与扩展。