Skip to content

docs(source): 补全兼容性说明与弃用提示，修正 en 文档 embed 引用 #2883

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lzxue merged 1 commit into from
Jul 23, 2026
Merged

docs(source): 补全兼容性说明与弃用提示，修正 en 文档 embed 引用 #2883

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 35 additions & 0 deletions docs/refactoring/source/PROGRESS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,41 @@

---

## [合并] PR #2882 — 阶段 0–6 渐进式重构合入 master（merge `cd654c1`）

- **事件**：PR #2882 `refactor(source): @antv/l7-source 渐进式重构（阶段 0-6，happy path 零行为变化）`
由作者本人合并，merge commit `cd654c1`（2026-07-23 07:43）。
- **范围**：阶段 0（清理）/ 1（拆 God Class：`ClusterManager` / `ParserRegistry`）/ 2（注册机制 +
`@deprecated` wrapper）/ 3（raster 4 loader 集成测试）/ 4（异步生命周期 `ready` + `error` 事件 +
`dataVersion` + premature-resolve 修复）/ 5（包边界 re-export transitional）/ 6（transform 不可变 +
raster 单测 + 脆弱断言改造 + `stats()` 快照）。
- **兼容性结论（逐项代码核查）**：旧 `new Source(data, cfg)` / `cluster: true` / 全局 `getParser` 等
全部兼容（见下条「兼容性核查」）。4 处 strictly-better minor 行为变化（ParserNotFoundError 精准化、
premature-resolve 修复、`error` 事件、clusterTransform deprecation warn）均非回归。
- **验证基线**：jest source 133 + layers 57 passed 1 skipped = 零回归；tsc source 0 / layers 229（基线）。

## [文档] API 文档补全 — 新公开方法 + error 事件（commit `1831635`）

- **改了什么**：`site/docs/api/source/source.{zh,en}.md` 补全重构引入的公开 API —— `create` /
`createSource` / `ready` / `stats()` / `dataVersion` / `error` 事件，与代码签名严格对齐。
- **注**：本 commit 在 PR 合并后直接推 `master`（作者本人合 PR 与补文档为连续动作），非常规 PR 流程，
最终状态正确（`origin/master` 顶部 `1831635` → `cd654c1`）。

## [文档] 兼容性说明 + 弃用提示 + en embed 修正（本轮 `docs/source-post-merge` 分支）

- **改了什么**：
- `source.{zh,en}.md` 新增「兼容性 / Compatibility」小节：明确旧 `new Source(data, cfg)` /
`cluster: true` / `ISourceCFG` 旧字段 / `'update'` 事件全部向后兼容，新 API 为可选迁移路径。
- `cluster` 段补弃用提示：`transforms: [{ type: 'cluster' }]` 已弃用，改用 `cluster: true`。
- 修正 en 文档 embed 引用 bug：`source.en.md` / `mvt.en.md` / `raster_tile.en.md` 原嵌入
`method.zh.md`（中文）→ 改为 `method.en.md`（英文版早已存在）。该 bug 为既有问题（commit
`1d5c5fa`），非本次重构引入，本轮顺手修正。
- **为什么**：用户反复确认「兼容原来写法」—— 文档需给出明确可查的兼容性结论，而非仅靠口头核查；
弃用项需在 API 文档留痕，避免用户见 warn 不知所措。
- **验证**：纯文档改动，零代码 / 测试影响。

---

## [阶段 6.4] `Source.stats()` 只读快照 — `ISourceStats` 类型 + stats() 方法 + 7 case spec（commit 0c37617）

- **改了什么（1 新 API + 1 新类型 + 1 新 spec，纯增量，零行为变化）**：
Expand Down
6 changes: 4 additions & 2 deletions docs/refactoring/source/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,9 +13,11 @@

## 当前状态

- **工作分支**：`refactor/source-progressive`（基于 `master` @ `3f81df9`）
- **起始日期**：2026-07-20
- **当前阶段**：阶段 0 — 低风险清理
- **合并状态**：PR #2882 已合并到 `master`（merge commit `cd654c1`，2026-07-23）
- **当前阶段**：阶段 0–6 全部落地并合并；阶段 7（class 层级 / pipeline / geojsonvt-decoder）为可选长期项
- **文档同步**：API 文档 `source.{zh,en}.md` 已补全新公开方法与兼容性说明（commit `1831635`）；本轮再补兼容性 / 弃用提示 + 修 en 文档 embed 引用
- **测试基线**：jest source 133 + layers 57 passed 1 skipped = 零回归；tsc source 0 / layers 229（基线）
- **进度概览**：见 [PROGRESS.md](./PROGRESS.md) 顶部

## 重构原则
Expand Down
2 changes: 1 addition & 1 deletion site/docs/api/source/mvt.en.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ callback parameters

Customize the tile data acquisition method, trial business scenarios require data authentication, or special processing scenarios

<embed src="@/docs/api/common/source/tile/method.zh.md"></embed>
<embed src="@/docs/api/common/source/tile/method.en.md"></embed>

## Example

Expand Down
2 changes: 1 addition & 1 deletion site/docs/api/source/raster_tile.en.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -139,4 +139,4 @@ const rasterSource = new Source(
);
```

<embed src="@/docs/api/common/source/tile/method.zh.md"></embed>
<embed src="@/docs/api/common/source/tile/method.en.md"></embed>
18 changes: 17 additions & 1 deletion site/docs/api/source/source.en.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,19 @@ const source = new Source(data, option);
- parser data parsing configuration
- transforms data processing configuration

## Compatibility

This progressive refactor (phases 0–6) keeps the **public API fully backward compatible** — existing code works unchanged:

- `new Source(data, cfg)` and `new Source(data)` keep working (`cfg` and `registry` are both optional).
- `cluster: true` silently uses the new `ClusterManager` direct path — **no warning**.
- Legacy `ISourceCFG` fields (`cluster` / `clusterOptions` / `parser` / `transforms` / `autoRender`) are all preserved.
- The `'update' { type: 'inited' | 'update' }` event behavior is unchanged; the new `'error'` event only surfaces failures explicitly (silent when no listener).

`Source.create` / `createSource` / `source.ready` / `source.stats()` / `source.dataVersion` are optional, better paths — existing code can migrate gradually, not required.

> `{ type: 'cluster' }` in the `transforms` option is deprecated (warns once at runtime, but still works). Use the top-level `cluster: true` option for aggregation, see [cluster](#cluster) below.

## data

Different parser types correspond to different data types
Expand Down Expand Up @@ -224,6 +237,9 @@ layer

`cluster`Indicates whether to aggregate data. Currently, only point layers support it.

> Prefer the top-level `cluster: true` option to enable aggregation.
> `transforms: [{ type: 'cluster' }]` is deprecated (corrupts `source.data` semantics and warns); kept only for backward compatibility.

### clusterOption optional

- radius: aggregate radius**number**default 40
Expand Down Expand Up @@ -454,7 +470,7 @@ For details, see[Layer](/api/base_layer/base/#setdata)
layer.setData(data);
```

<embed src="@/docs/api/common/source/tile/method.zh.md"></embed>
<embed src="@/docs/api/common/source/tile/method.en.md"></embed>

### type of data

Expand Down
16 changes: 16 additions & 0 deletions site/docs/api/source/source.zh.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,19 @@ const source = new Source(data, option);
- parser 数据解析配置
- transforms 数据处理配置

## 兼容性

本次渐进式重构（阶段 0–6）保证**对外 API 完全向后兼容**，旧写法无需改动即可继续工作：

- `new Source(data, cfg)` 与 `new Source(data)` 写法保持不变（`cfg` 与 `registry` 均可选）。
- `cluster: true` 配置静默走新 `ClusterManager` 直调路径，**无任何 warning**。
- `ISourceCFG` 旧字段（`cluster` / `clusterOptions` / `parser` / `transforms` / `autoRender`）全部保留。
- 事件 `'update' { type: 'inited' | 'update' }` 行为不变；新增 `'error'` 事件仅用于显式 surfacing 失败（无监听即静默）。

新增的 `Source.create` / `createSource` / `source.ready` / `source.stats()` / `source.dataVersion` 为可选的更优路径，旧代码可按需逐步迁移，非强制。

> `transforms` 配置项中 `{ type: 'cluster' }` 已弃用（运行时会 warn 一次，但仍可工作）。聚合请改用顶层 `cluster: true` 配置项，详见下方 [cluster](#cluster)。

## data

不同 parser 类型对应不同 data 类型
Expand Down Expand Up @@ -227,6 +240,9 @@ layer.source(data, {

`cluster` 表示是否对数据进行聚合操作， 目前只有点图层支持。

> 推荐使用 `cluster: true` 顶层配置项开启聚合。
> `transforms: [{ type: 'cluster' }]` 已弃用（会破坏 `source.data` 语义并 warn），仅为向后兼容保留。

### clusterOption 可选

- radius: 聚合半径 **number** default 40
Expand Down
Loading