# d3kline-engine 用户指南

## 1. 范围说明

本文档说明如何从 GitHub 启动仓库，以及在 renderer 迁移后使用当前对外 API。

当前公开能力：

- `@d3kline/core`：共享契约与基础工具
- `@d3kline/renderer`：从 quant-web `d3Kline` 迁移而来的图表运行时
- `@d3kline/engine`：聚合包，统一导出 core + renderer

## 2. 环境要求

- Node.js 20+
- pnpm 10+

## 3. 克隆并启动

```bash
git clone https://github.com/RookieTao998/d3kline-engine.git
cd d3kline-engine
pnpm install
pnpm typecheck
pnpm build
pnpm test
pnpm dev:examples
```

启动后在浏览器打开 Vite 输出地址。

## 4. 包使用方式

### 4.1 使用 `@d3kline/renderer`

```ts
import { D3KlineChart, type KLineData } from '@d3kline/renderer'

const host = document.getElementById('chart')!
const chart = new D3KlineChart(host, { theme: 'dark' })

const bars: KLineData[] = [
  { timestamp: 1712000000000, open: 100, high: 105, low: 98, close: 103, volume: 1200 },
  { timestamp: 1712000060000, open: 103, high: 108, low: 102, close: 107, volume: 980 },
]

chart.resetData(bars)
chart.loadIndicator({ name: 'MA' })
chart.loadIndicator({ name: 'VOL', isMain: false, height: 120 })
```

### 4.2 使用 `@d3kline/core`

`@d3kline/core` 现阶段聚焦共享契约与基础工具（types/period/options/events/chart-state），不再提供指标注册运行时。

```ts
import type { KLineBar, PeriodType } from '@d3kline/core'

const bar: KLineBar = {
  timestamp: Date.now(),
  open: 1,
  high: 2,
  low: 0.5,
  close: 1.4,
}

const period: PeriodType = 'M1'
```

## 5. 指标使用方式

- 内置指标通过 `chart.loadIndicator(...)` 按名称加载。
- 自定义指标数据流可通过 `chart.createIndicator(...)` 与 `chart.updateIndicator(...)` 注入 `CalcResult` 形状数据。

## 6. API 参考

- 基于 quant-web 源码整理的 API/参数参考：
  - `docs/technical-notes/d3kline-api-reference-from-quant-web.md`

## 7. 已发布包

已发布到 npm 的包：

- `@d3kline/core`
- `@d3kline/renderer`
- `@d3kline/engine`

`@d3kline/examples` 仅用于本地开发，不发布到 npm。

## 8. 常见问题

### 8.1 报错 `Cannot find module '@d3kline/...`

执行：

```bash
pnpm install
pnpm build
```

### 8.2 示例端口被占用

执行：

```bash
pnpm dev:examples -- --port 5174
```