Uh oh!
There was an error while loading. Please reload this page.
docs(plugin-map): README 按现码重写,不再教包里不存在的那套 API (#5002) - #5021
Merged
Conversation
`packages/plugin-map/README.md` 教的是一个不存在的组件:作者手写的 `markers`
数组、`layers`、`height`、`useGeolocation`、`center: { lat, lng }` 对象、
`zoom` 的「Default: 10」,以及 `import { mapComponents }` + `Object.entries()`
的手动注册。这些键在 `packages/plugin-map/src` 里没有任何读取点,`mapComponents`
这个导出不存在。照抄任一片段的结果:上下文里有 dataSource 时是一张空地图且
零诊断(不会有「记录坐标无效」提示——根本没有记录进入管线),没有 dataSource
时反而弹一条指向别处的 `Error: DataSource required for object/api providers`。
两种情况下都没有任何一层告诉作者他写的键从未被读。
组件真正读的是查询(`objectName` / `staticData` / `data`,`filter` 与 `sort`
是查询自己的过滤与排序)加上注册时声明的 `map` 块(`latitudeField`、
`longitudeField`、`locationField`、`titleField`、`descriptionField`、`zoom`、
`center` 为 `[latitude, longitude]` 元组、`style`),注册是 import 的副作用。
相机语义按 #4941 / PR #5000:没有默认 zoom,未声明相机即取景到记录集(48px
padding、城市级 zoom 上限 12,包围盒沿最短弧度量),空集开在整个世界,声明的
一半胜出、另一半推导,读不出来的 `center` 被诊断而不被适配、也不夺走取景。
## 形态:对齐重写,但按减法做
新文比旧文短 116 行。完整的作者参考只留一份 ——
`content/docs/plugins/plugin-map.mdx`,它被 `check-doc-component-types` 扫、
且刚由 PR #5000 校正过;README 只保留包本地的事实:注册了什么、导出了什么、
两种 provider 各一个能跑的 schema、相机规则,以及读者无法自行推断的两个陷阱:
- `map` 块**替换**字段名默认值而不是与之合并 —— `map: { titleField: 'name' }`
单独写就没有命名任何坐标字段,放不下任何 marker;
- 不是二元数组的 `center` 会被 `MapConfigSchema` 拒绝并告警,不被适配。
在一份没有门禁的第二副本里重述整个 schema,正是这次漂移的生成器(与 #3881
同形),所以没有把 docs 页的参考再抄一遍。另加一节「本组件不读什么」,直接
点名旧文那批虚构键,让照着旧文(或照着记住了旧文的模型)写的读者能立刻对上。
## 核实方式
README 里每一行断言都对着 `packages/plugin-map/src` 逐条核过,并用一份临时
探针(未入库)把每个片段与每条断言在真包上跑了一遍:22 例全绿,含两个片段的
渲染、`$filter`/`$orderby` 透传且无 `$top`、`map` 块不合并默认值、`Marker`
兜底标题、fit 的 padding/上限、跨反经线取景、空集世界视图、`center` 的
[lat, lng] 顺序、半声明相机的两种推导、对象形 `center` 的告警且保 fit、
`locationField` 三种坐标形态、越界记录被排除并计数、`markers`/`layers`/
`height`/`useGeolocation` 全部无效果、导出面恰为 `ObjectMap` 与
`ObjectMapRenderer`、`object-map` 与 `map` 两个类型的自注册、聚合在 100 个
marker 以上自动开启、以及 schema 上直接写 `onMarkerClick` 经 `SchemaRenderer`
的属性摊平确实到达组件。
反向验证(方向先判后跑):把旧 README 的片段逐字跑一遍,预判是 0 个 marker
且不提及那些键 —— 6 例全绿,并修正了 issue 正文一处措辞:「空地图且零诊断」
只在上下文有 dataSource 时成立,没有 dataSource 时是上面那条指错方向的报错。
兄弟包 README 巡查按裁定只查不改,同族漂移另立单:#5010(calendar)、
#5011(form)、#5012(gantt)、#5013(grid)、#5014(view)、#5015(dashboard)、
#5016(report);顺带记账 #5017(顶层 `style` 与 `BaseSchema.style` 撞车)、
#5018(`ObjectMapSchema` 未建模 `map` 块)、#5019(docs 页两处残留不符)、
#5020(`clusterRadius` 单位注释,观察类)。
Co-authored-by: Claude <noreply@anthropic.com>Contributor
✅ Console Performance Budget
📦 Bundle Size Report
Size Limits
|
上一版把两个注册写成「`map` —— `ObjectView` / `ViewSwitcher` 用的 view-type 别名」,那句是比着 `plugin-tree/README.md` 的同位说法写的,而它在本包上查不出 消费者:`ObjectView` 的 `case 'map'` 把地图视图编译成 `type: 'object-map'` 节点(`packages/plugin-view/src/ObjectView.tsx:770-776`)再交 `SchemaRenderer`, `ViewSwitcher` 那侧的 `map` 只是标签与图标(`ViewSwitcher.tsx:65`/`:79`); 全仓除本包测试外没有任何地方构造 `type: 'map'` 的组件节点。 改成能钉住的两条:`map` 是 spec `ViewTypeSchema` 的成员名 (`packages/types/src/zod/views.zod.ts:25`),给直接用该名字写的节点用;并写明 `ObjectView` 里的 map 视图会被编译成 `object-map`,两个拼法落到同一个组件。 这份 README 的全部意义就是每行都能对上代码,所以宁可把话说窄。 Co-authored-by: Claude <noreply@anthropic.com>
Contributor
✅ Console Performance Budget
📦 Bundle Size Report
Size Limits
|
yinlianghui
commented
Aug 17, 2026
CollaboratorAuthor
PM 验收 ✅ ACCEPT(#5002,批次 20 收官单) 实物核验(merge-base CI 亲读:19/19 check runs completed,零失败(两项 path-filter skipped 计绿;label 首跑 429/503 基础设施红,按「同签名 + 前一提交绿」认签名重跑收绿,处置合规)。 卡面证伪的处理:对照表第 5 行(onMarkerClick 只是 React prop)被探针实测推翻 —— SchemaRenderer 把非元数据属性摊平成 props,schema 键通道真实存在;新 README 写明通道而非按卡面否定,正确。issue 措辞「空地图零诊断」被收窄为有条件成立(有 dataSource 时成立;无 dataSource 时有诊断但指向无关事项)—— 两种情况都不告诉作者键从未被读,缺陷成立。旧 README 片段逐字跑 6 例(0 marker)是本卡最直接的反向验证。 兄弟巡查产出超预期:19 包里 11 包干净、7 包同类虚构 API 各立卡(#5010–#5016,含 #5013 的「改路径也仍然错」与 #5015 的「本族不能按名字模式批量断言」两条防误修笔记),另出 #5017(style 撞车)、#5018(map 块整体未建模 + undraft + auto-merge(squash)。 Generated by Claude Code |
yinlianghui
marked this pull request as ready for review
August 17, 2026 15:50
Uh oh!
There was an error while loading. Please reload this page.
This was referenced Aug 17, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes#5002
前提复核:成立,并修正 issue 正文一处措辞
按「issue 正文是线索不是规格」先把卡面对照表逐行对着
origin/main@25819c42c核了一遍。七行里六行准确;第五行需要修正,而且是往反方向修正的:center: { lat, lng }对象形失败并被忽略MapConfigSchema.center是z.tuple([z.number(), z.number()])(ObjectMap.tsx:48);对象形safeParse失败 → 告警(:224)→center?.[0]取不到数 → 不构成已声明相机(:599-603),取景照做markers从不被读:514-545)layers/height从不被读h-[300px] … lg:h-[600px](:670)mapComponents导出不存在ObjectMap与ObjectMapRenderer;object-map/map自注册(index.tsx:62,72)zoom没有默认值了:237-244)onMarkerClick只是 React prop,不是 schema 键SchemaRenderer会把节点的非元数据属性摊平成 props(packages/react/src/SchemaRenderer.tsx:575解构、:619展开),实测在 schema 上写onMarkerClick会带着记录被调用。docs 页把它记为 schema 键是对的,所以新 README 没有按卡面去否定它,而是写明这条通道「照抄即空地图且无诊断」也需要一处补充,见下面的反向验证。
形态选择:对齐重写,但按减法做(不是指针式)
两个候选形态里选了 ①对齐重写,并按 #3881 / PR #4939 的减法路数执行 —— 新文比旧文短 116 行,完整作者参考只留一份。
package.json的files含README.md),它就是这个包的 npm 落地页;只留一条「看文档站」对 npm 读者是净损失。而且包本地有三件事 docs 页没有、也不该由 docs 页承担:注册了哪两个类型、导出面是什么、map.style这个键(docs 页的 MapConfig 表里没有它)。README_SHADCN_SYNC.md的第二份清单)同形。所以完整参考指向content/docs/plugins/plugin-map.mdx(被check-doc-component-types扫,且刚由 PR fix(plugin-map): 首帧相机取景到查询记录集,经度取短弧 (#4941) #5000 校正过相机语义),README 只保留包本地的事实。plugin-tree/README.md—— 近期被验收过的那份写法(是什么 / 注册了哪两个类型 / 一段能跑的 usage / 一张小配置表 / 一条"不会静默丢东西"的说明 / License)。plugin-detail、plugin-list那两份仍是长文旧体例,没有拿它们做样板。新文另加一节「What this component does not read」,点名旧文那批虚构键。理由:旧文已经进过训练语料,照着旧文(或照着记住旧文的模型)写的读者需要一条能立刻对上的否定清单;这类否定陈述在功能不新增时是稳定的,不构成新的漂移面。
每个片段的核实方式
README 里没有一行是从旧文或卡面搬的。除逐行对源码坐标外,用一份临时探针(未入库,已删)把每个片段与每条断言在真包上跑了一遍,22 例全绿:
两个 schema 片段各自渲染出 marker;
filter/sort透传为$filter/$orderby且不发$top;map块不与默认字段名合并(map: { titleField: 'name' }单独写 → 0 marker + 排除提示);块内省略titleField→ 标题兜底Marker;fit 的 padding 48 与上限 12,且不附带合成 zoom;跨反经线取景为[[179,-18],[181,-16]];空集开在 0,0 / zoom 2;center按[latitude, longitude]读;半声明相机的两种推导(zoom 单独 → 记录集中心;center 单独 → 大陆级 zoom 3);对象形center告警且保 fit;locationField的对象 / 字符串 / 数组三形态(含latitude/longitude、lon别名);越界记录被排除并计数;markers/layers/height/useGeolocation全部无效果;导出面恰为两项;object-map与map两个类型自注册;聚合在 100 marker 以上自动开启;Edit / Delete 只在传了处理器时出现;schema 上写onMarkerClick确实到达组件。一处没有照抄源码注释的地方:
clusterRadius的 doc comment 写「in pixels」,而实现是radius / 2 ** zoom的坐标度数网格(:326)。README 写实际语义,并把这条注释单据记为 #5020。反向验证(方向先判后跑)
文档单的等价物:把旧 README 的片段逐字跑一遍。预判方向 —— 0 个 marker,且不出现任何提及那些键的诊断。6 例全绿,并得到一条对 issue 措辞的修正:
center/zoom完全没参与。这就是 issue 说的形态。Error: DataSource required for object/api providers—— 有诊断,但指向完全无关的另一件事,地图根本没挂载。所以「every snippet renders an empty map with no diagnostic」是有条件成立,不是无条件的;PR 描述与 commit 都按实测写。
关键断言 → 源码坐标
center是[latitude, longitude]元组:packages/plugin-map/src/ObjectMap.tsx:48(center: z.tuple([z.number(), z.number()]).optional())+:599-600(center?.[0]取纬度、center?.[1]取经度)ObjectMap.tsx:237-244(默认分支只回 5 个字段名)+:612-620(markerBounds && !hasDeclaredCamera→ 交bounds)+camera.ts:44(padding 48)/:52(上限 12)/:55(空集 zoom 2)/:62(半声明 zoom 3)map块替换而非合并默认值::217-227(有块则{ ...config, style }原样返回)对比:237-244验证
pnpm exec vitest run(在packages/plugin-map/内跑,该包 setupFiles 是 cwd 相对的)→ 7 files / 43 passed。跑之前先pnpm --filter '@object-ui/plugin-map^...' build—— 新 worktree 里不建依赖,@object-ui/react解析不到,红得像是改坏了导入node scripts/check-doc-links.mjs→Links are valid across 13 scan roots.(packages/*/README.md确实在扫描面内:scripts/check-doc-links.mjs:477,rule: 'disk')node scripts/check-control-bytes.mjs→ OK(4470 个文本文件,零命中);另做门禁盲区自扫grep -naP控制字节 → 零命中.changeset/plugin-map-readme-truth-5002.md,按ban-package-self-import.md的空 frontmatter 先例(无代码/类型/运行时变化 → 不声明发布;文内写明校正后的 README 随@object-ui/plugin-map下次发布到达 npm)兄弟 README 巡查(按裁定只查不改)
对 19 个
packages/plugin-*/README.md的自包命名导入与各包真实导出面做了比对,命中 8 个包(不含本单的 map),各立一单交分诊:#5010 calendar、#5011 form、#5012 gantt、#5013 grid、#5014 view、#5015 dashboard、#5016 report。方法学备注:第一版用「标识符在
src/是否出现」近似,会被注释里的名字放过(#5015 的DashboardSchema只在注释里),也会误报export * as X(plugin-chatbot 的AIElements是真导出)。改成对导出面取名集合后才稳定;多行 import 块仍只按单行匹配,所以报出的范围是下限。顺带记账(均不在本 PR 修):#5017 顶层
style被当 MapLibre style 读、与BaseSchema.style(内联 CSS)撞车,而 types 里mapStyle这个名字正是为避开它才起的;#5018ObjectMapSchema没有建模map块,组件 props 类型写的是ObjectGridSchema、每处 map 读取走as any;#5019 docs 页两处残留不符(MapConfig不从 types 导出、API provider 示例是未实现分支)—— 这一单因为新 README 把读者指向那一页而更值得修;#5020clusterRadius单位注释(观察类,带finding标签)。Generated by Claude Code