gis-view-webgl2 0.1.2 → 0.1.3

package/docs/steps/selftest-demos.html

@@ -25,6 +25,7 @@
 			import { createApp } from 'vue'
 			import App from '/src/App.vue'
 			import { channelDraftArrowPlacement } from '/src/gis-view/engine.js'
+			import { createMinimap } from '/src/gis-view/minimap.js'
 			const results = []
 			const flush = () => { document.getElementById('out').textContent = results.join('\n') }
 			const check = (name, ok, extra = '') => {
@@ -90,8 +91,8 @@
 				// 1. 外壳：默认综合示例，页签齐全
 				const loaded = await canvasReady()
 				check('演示外壳把默认演示（综合示例）挂起来了', Boolean(loaded), loaded ? 'canvas 就绪' : '没等到 canvas')
-				check('页签列出全部演示（20 个：19 个功能 + 综合）', tabs().length === 20, `${tabs().length} 个页签：${tabs().map(tab => tab.textContent.trim()).join(' / ')}`)
-				check('页头的演示数量直接跟随注册表（20 个）', (document.querySelector('.page-header__count')?.textContent ?? '').includes('20 个'), document.querySelector('.page-header__count')?.textContent?.trim() ?? '没有页头计数')
+				check('页签列出全部演示（22 个：21 个功能 + 综合）', tabs().length === 22, `${tabs().length} 个页签：${tabs().map(tab => tab.textContent.trim()).join(' / ')}`)
+				check('页头的演示数量直接跟随注册表（22 个）', (document.querySelector('.page-header__count')?.textContent ?? '').includes('22 个'), document.querySelector('.page-header__count')?.textContent?.trim() ?? '没有页头计数')
 				check('默认页签是综合示例', (document.querySelector('.demo-shell__tab--active')?.textContent ?? '').includes('综合'), document.querySelector('.demo-shell__tab--active')?.textContent?.trim() ?? '')
 				check('默认页签写进地址栏（刷新还停在同一个演示）', location.search.includes('demo=full'), location.search)
 				check('综合示例的面板照旧在（拆分没有动它）', document.querySelectorAll('.demo-panel-buttons button').length >= 6, `${document.querySelectorAll('.demo-panel-buttons button').length} 个面板按钮`)
@@ -121,7 +122,7 @@
 				const afterBack = document.querySelector('.demo-shell__tab--active')?.textContent.trim() ?? ''
 				check('键盘 [ 往回翻（基础视图回到综合示例）', afterBack.includes('综合'), afterBack)
 				const eyebrow = document.querySelector('.demo-shell__eyebrow')?.textContent.trim() ?? ''
-				check('当前演示显示分组与序号（综合 · 20 / 20）', eyebrow.includes('综合') && eyebrow.includes('20 / 20'), eyebrow)
+				check('当前演示显示分组与序号（综合 · 22 / 22）', eyebrow.includes('综合') && eyebrow.includes('22 / 22'), eyebrow)
 				document.querySelector('[data-demo=demo-next]')?.click()
 				await wait(60)
 				const afterStepNext = document.querySelector('.demo-shell__tab--active')?.textContent.trim() ?? ''
@@ -133,10 +134,93 @@
 				document.body.appendChild(keyGuard)
 				keyGuard.dispatchEvent(new KeyboardEvent('keydown', { key: ']', bubbles: true }))
 				await wait(60)
-				const afterGuard = document.querySelector('.demo-shell__tab--active')?.textContent.trim() ?? ''
-				keyGuard.remove()
-				check('焦点在输入框里时键盘 [ / ] 不抢键', afterGuard.includes('综合'), afterGuard)
-				// 2. 每个功能演示都切一遍：画布起得来、说明与读数有东西
+				const afterGuard = document.querySelector('.demo-shell__tab--active')?.textContent.trim() ?? ''
+				keyGuard.remove()
+				check('焦点在输入框里时键盘 [ / ] 不抢键', afterGuard.includes('综合'), afterGuard)
+				// 1.2 鹰眼图线路层：同一份数据补画命中缓存，固定范围外的线路不投影 / 不建路径
+				const miniHost = document.createElement('div')
+				miniHost.style.cssText = 'position:absolute;left:-9999px;width:180px;height:120px'
+				document.body.append(miniHost)
+				const miniData = {
+					points: [{ x: 50, y: 50 }],
+					lines: [
+						{ path: [[0, 0], [100, 0]], minX: 0, minY: 0, maxX: 100, maxY: 0 },
+						{ path: [[1000, 1000], [1100, 1000]], minX: 1000, minY: 1000, maxX: 1100, maxY: 1000 }
+					]
+				}
+				const mini = createMinimap(miniHost, {
+					enabled: true,
+					width: 180,
+					height: 120,
+					background: null,
+					extent: { minX: 0, minY: 0, maxX: 100, maxY: 100 },
+					maxPixelRatio: 1
+				}, {
+					getData: () => miniData,
+					getCamera: () => ({ center: [50, 50], scale: 1 }),
+					getViewport: () => ({ width: 180, height: 120, pixelRatio: 1, displayScale: 1 }),
+					getFallbackBounds: () => ({ minX: 0, minY: 0, maxX: 100, maxY: 100 }),
+					getZoomBaseScale: () => 0,
+					getBackground: () => null
+				})
+				await wait(220)
+				const miniFirst = mini.getPaintStats()
+				check('鹰眼图线路层：首帧只铺固定范围里的线路（范围外那条被跳过）',
+					miniFirst.lineRasterDraws > 0 && miniFirst.linePathsDrawn === miniFirst.lineRasterDraws,
+					JSON.stringify(miniFirst))
+				mini.refresh()
+				await wait(100)
+				const miniRepeat = mini.getPaintStats()
+				check('鹰眼图线路层：同一份数据补画命中缓存（不再重复投影 / stroke）',
+					miniRepeat.lineRasterHits > miniFirst.lineRasterHits && miniRepeat.lineRasterDraws === miniFirst.lineRasterDraws,
+					JSON.stringify({ first: miniFirst, repeat: miniRepeat }))
+				mini.setZoom(2)
+				await wait(100)
+				const miniZoomed = mini.getPaintStats()
+				check('鹰眼图线路层：小图自身缩放变化时只重铺线路层一次（范围外线路仍被裁剪）',
+					miniZoomed.lineRasterDraws === miniRepeat.lineRasterDraws + 1 && miniZoomed.linePathsDrawn === miniRepeat.linePathsDrawn,
+					JSON.stringify({ repeat: miniRepeat, zoomed: miniZoomed }))
+				mini.destroy()
+				miniHost.remove()
+				// 节点抗锯齿：单独一个无底图 / 无线路的小图，边缘应出现 0 < alpha < 255 的覆盖率像素。
+				const aaHost = document.createElement('div')
+				aaHost.style.cssText = 'position:absolute;left:-9999px;width:180px;height:120px'
+				document.body.append(aaHost)
+				const aaData = { points: [{ x: 50, y: 50, size: 5.5, color: '#ff0000' }], lines: [] }
+				const aa = createMinimap(aaHost, {
+					enabled: true,
+					width: 180,
+					height: 120,
+					background: null,
+					extent: { minX: 0, minY: 0, maxX: 100, maxY: 100 },
+					maxPixelRatio: 1
+				}, {
+					getData: () => aaData,
+					getCamera: () => ({ center: [50, 50], scale: 1 }),
+					getViewport: () => ({ width: 180, height: 120, pixelRatio: 1, displayScale: 1 }),
+					getFallbackBounds: () => ({ minX: 0, minY: 0, maxX: 100, maxY: 100 }),
+					getZoomBaseScale: () => 0,
+					getBackground: () => null
+				})
+				await wait(180)
+				const aaCanvas = aaHost.querySelector('canvas')
+				const aaPixels = aaCanvas.getContext('2d').getImageData(0, 0, aaCanvas.width, aaCanvas.height).data
+				let aaSolid = 0
+				let aaSoft = 0
+				for (let offset = 3; offset < aaPixels.length; offset += 4) {
+					if (aaPixels[offset] === 255) {
+						aaSolid += 1
+					}
+					else if (aaPixels[offset] > 0) {
+						aaSoft += 1
+					}
+				}
+				check('鹰眼图：节点边缘按像素覆盖率抗锯齿（既有实心像素也有半透明边缘）',
+					aaSolid > 0 && aaSoft > 0,
+					`实心 ${aaSolid} px / 半透明 ${aaSoft} px`)
+				aa.destroy()
+				aaHost.remove()
+				// 2. 每个功能演示都切一遍：画布起得来、说明与读数有东西
 				const demoSpecs = [
 					{ tab: '基础视图', id: 'basic' },
 					{ tab: '标签交互', id: 'labels' },
@@ -153,6 +237,7 @@
 					{ tab: '扩展能力', id: 'extension' },
 					{ tab: '编辑与保存', id: 'backend' },
 					{ tab: '性能与质量', id: 'perf' },
+					{ tab: '点聚合', id: 'cluster' },
 					{ tab: '动画效果', id: 'effects' },
 					{ tab: '扩展图形', id: 'graphic' }
 				]
@@ -162,10 +247,82 @@
 					const panel = document.querySelector('.dv-demo .dv-panel')
 					const active = document.querySelector('.demo-shell__tab--active')?.textContent.trim() ?? ''
 					check(`切到「${spec.tab}」：画布与读数面板都起来了`, Boolean(ready) && Boolean(panel) && active === spec.tab, `${ready ? 'canvas 就绪' : '没有 canvas'} / ${panel ? `${panel.querySelectorAll('.dv-group').length} 组读数` : '没有面板'} / 当前页签 ${active}`)
-					await wait(260)
+					await wait(260)
 					check(`「${spec.tab}」把演示 id 写进地址栏（?demo=${spec.id}）`, location.search.includes(`demo=${spec.id}`), location.search)
 				}
 
+				// 2.0 点聚合：控件齐全、聚合圆点击只发 clusterClick，maxZoom 展开后又回来
+				if (await clickTab('点聚合')) {
+					const ready = await canvasReady()
+					await wait(500)
+					const demo = document.querySelector('.dv-demo')
+					const setup = demo?.__vueParentComponent?.setupState
+					const view = await until(() => setup?.view, 8000)
+					const text = key => document.querySelector(`[data-demo=${key}]`)?.textContent.trim() ?? ''
+					const canvas = demo?.querySelector('canvas.gis-view__canvas') ?? demo?.querySelector('canvas')
+					const toggle = document.querySelector('[data-demo=cluster-toggle]')
+					const radiusInput = document.querySelector('[data-demo=cluster-radius]')
+					const minPointsSelect = document.querySelector('[data-demo=cluster-min-points]')
+					const maxZoomSelect = document.querySelector('[data-demo=cluster-max-zoom]')
+					const countSelect = document.querySelector('[data-demo=cluster-count]')
+					const anchor = await until(() => {
+						const node = document.querySelector('[data-demo=cluster-first-client]')
+						return node?.dataset.clientX !== '' && node?.dataset.clientY !== '' ? node : null
+					}, 8000)
+					if (ready && view && canvas && toggle && radiusInput && minPointsSelect && maxZoomSelect && countSelect) {
+						const initialClusters = view.getClusters().filter(item => item.count > 1)
+						check('点聚合：配置控件齐全，初始数据已聚合并给出读数',
+							initialClusters.length > 0 && text('cluster-stats').includes('原始点') && text('cluster-stats').includes('个聚合圆'),
+							`${initialClusters.length} 个多成员圆 / ${text('cluster-stats')}`)
+						const selectedBefore = view.getSelections().map(entry => entry.item?.id ?? entry.index).join(',')
+						const clientX = Number(anchor?.dataset.clientX)
+						const clientY = Number(anchor?.dataset.clientY)
+						if (Number.isFinite(clientX) && Number.isFinite(clientY)) {
+							tap(canvas, { clientX, clientY })
+							await wait(180)
+						}
+						const selectedAfter = view.getSelections().map(entry => entry.item?.id ?? entry.index).join(',')
+						check('点聚合：点中聚合圆只增加 clusterClick，普通 click 为 0、选中集不变',
+							text('cluster-click-count').includes('0 次普通点击 / 1 次聚合点击') && text('cluster-event').includes('clusterClick') && selectedBefore === selectedAfter,
+							`${text('cluster-click-count')} / ${text('cluster-event')} / 选中 ${selectedBefore || '空'} → ${selectedAfter || '空'}`)
+						maxZoomSelect.value = '2'
+						maxZoomSelect.dispatchEvent(new Event('change', { bubbles: true }))
+						await wait(220)
+						view.zoomBy(3)
+						await wait(380)
+						const zoomed = view.getPointCluster()
+						check('点聚合：maxZoom 控件生效，放大超过阈值后展开原始点',
+							zoomed?.active === false && view.getStats().clusterCount === 0,
+							`active=${zoomed?.active} clusterCount=${view.getStats().clusterCount} maxZoom=${zoomed?.maxZoom}`)
+						document.querySelector('[data-demo=cluster-fit]')?.click()
+						await wait(420)
+						check('点聚合：适应全部后回到聚合档，聚合圆重新出现',
+							view.getPointCluster()?.active === true && view.getStats().clusterCount > 0,
+							`active=${view.getPointCluster()?.active} clusterCount=${view.getStats().clusterCount}`)
+						radiusInput.value = '24'
+						radiusInput.dispatchEvent(new Event('input', { bubbles: true }))
+						radiusInput.dispatchEvent(new Event('change', { bubbles: true }))
+						await wait(220)
+						countSelect.value = '2000'
+						countSelect.dispatchEvent(new Event('change', { bubbles: true }))
+						document.querySelector('[data-demo=cluster-rebuild]')?.click()
+						const rebuilt = await until(() => view.getData().points.length === 2000, 8000)
+						await wait(260)
+						check('点聚合：半径可调、重建到 2000 点后统计跟着换',
+							Boolean(rebuilt) && view.getPointCluster()?.radius === 24 && view.getStats().pointCount === 2000 && view.getStats().clusterCount > 0,
+							`radius=${view.getPointCluster()?.radius} pointCount=${view.getStats().pointCount} clusterCount=${view.getStats().clusterCount}`)
+						toggle.checked = false
+						toggle.dispatchEvent(new Event('change', { bubbles: true }))
+						await wait(300)
+						check('点聚合：关掉开关后原始点恢复、聚合统计归零',
+							view.getPointCluster()?.enabled === false && view.getStats().clusterCount === 0 && view.getStats().clusterPointCount === 0,
+							JSON.stringify({ cluster: view.getPointCluster(), stats: { count: view.getStats().clusterCount, points: view.getStats().clusterPointCount } }))
+					}
+					else {
+						check('点聚合：演示页、实例与六个控件都起来了', false, ready ? '缺少 demo / setupState.view / 控件' : '没有 canvas')
+					}
+				}
+
 				// 2.0 动态装饰器：吸附方式与位置来源正交，两种吸附方式都能选三种位置
 				if (await clickTab('动态装饰器')) {
 					await canvasReady()
@@ -1546,7 +1703,7 @@
 						}
 					}
 					const channelMenuNode = channelDemo.querySelector('.dv-channel-menu')
-					check('通道与数据：右键通道回线弹出交互框（features.channelMenu）', Boolean(menuPayload) && Boolean(channelMenuNode) && channelView.getOptions().features?.channelMenu === true, menuPayload ? '通道 ' + menuPayload.channelId + ' · 命中回线 ' + menuPayload.lineId + ' · 共 ' + menuPayload.groupCount + ' 组' : '没弹出')
+					check('通道与数据：右键通道回线弹出交互框（onContextMenu.channelContext + features.contextMenu）', Boolean(menuPayload) && Boolean(channelMenuNode) && channelView.getFeatures().contextMenu === true, menuPayload ? '通道 ' + menuPayload.channelId + ' · 命中回线 ' + menuPayload.lineId + ' · 共 ' + menuPayload.groupCount + ' 组' : '没弹出')
 					const groupsBeforeSplit = channelView.getChannelGroups(menuPayload?.channelId).length
 					const channelAction = text => [...channelDemo.querySelectorAll('.dv-channel-menu__actions button')].find(node => node.textContent.trim() === text)
 					check('通道与数据：交互框列出 6 个 runChannelAction 动作（含取消该分组选中），拐点编辑已开（waypointEditable）', channelDemo.querySelectorAll('.dv-channel-menu__actions button').length === 6 && Boolean(channelAction('加拐点')) && !channelAction('加拐点').disabled && Boolean(channelAction('取消该分组选中')), [...channelDemo.querySelectorAll('.dv-channel-menu__actions button')].map(node => node.textContent.trim() + (node.disabled ? '(灰)' : '')).join(' / '))
@@ -1590,10 +1747,10 @@
 					// getChannelGroups 每一项只给 lineIds（lineCount 是 getChannelContext().group 的字段），回线数按 lineIds.length 算
 					const targetLineCount = targetGroup?.lineIds?.length ?? 0
 					check('通道与数据：点分组 = setCurrentChannelGroup + 选中它的回线', Boolean(targetGroup) && switchedContext?.groupId === targetGroup.id && channelView.getSelections().length === targetLineCount, switchedContext ? '当前「' + switchedContext.groupId + '」/ 选中 ' + channelView.getSelections().length + ' 回线（目标「' + (targetGroup?.id ?? '—') + '」' + targetLineCount + ' 回）' : '没有上下文')
-					// 右键落到节点上：通道回调收到 null，框自己收掉
-					channelRightClick(fromScreen)
-					await wait(200)
-					check('通道与数据：右键落到节点上时回调收到 null，框收掉', !channelDemo.querySelector('.dv-channel-menu') && channelSetup.channelMenu === null, '')
+					// 右键落到节点上：onContextMenu 不带 channelContext，框自己收掉
+					channelRightClick(fromScreen)
+					await wait(200)
+					check('通道与数据：右键落到节点上时 channelContext 为空，框收掉', !channelDemo.querySelector('.dv-channel-menu') && channelSetup.channelMenu === null, '')
 					// 再右键回回线上、按 Esc 也能收
 					channelRightClick(menuScreen)
 					const reopenedMenu = await until(() => channelDemo.querySelector('.dv-channel-menu'), 5000)
@@ -2009,19 +2166,80 @@
 				else {
 					check('编辑与保存：画布与视图都起来了', false, '没等到 canvas 或 view')
 				}
-				// 2.9 综合示例的「实例方法速查」面板：整份清单、搜索、点一条填表达式、求值、options 清单
-				if (await clickTab('综合')) {
-					const ready = await canvasReady()
-					// 面板在弹层里（v-show）：先切到「开关 · 历史」页签，再点出「实例方法速查」那一块
-					;[...document.querySelectorAll('.demo-tabs button')].find(node => node.textContent.includes('开关'))?.click()
+				// 2.9 综合示例的「实例方法速查」面板：整份清单、搜索、点一条填表达式、求值、options 清单
+				if (await clickTab('综合')) {
+					const ready = await canvasReady()
+					// 级联高亮与合并样式：综合示例的「交互」面板里现场开关、点画布看读数，并确认合并样式不是额外 API
+					const cascadeDemo = document.querySelector('.demo-view')
+					const cascadeSetup = cascadeDemo?.__vueParentComponent?.setupState
+					const cascadeView = await until(() => cascadeSetup?.viewRef, 8000)
+					const cascadeCanvas = cascadeDemo?.querySelector('canvas.gis-view__canvas') ?? cascadeDemo?.querySelector('canvas')
+					if (ready && cascadeView && cascadeCanvas) {
+						;[...document.querySelectorAll('.demo-tabs button')].find(node => node.textContent.includes('视图 · 交互'))?.click()
+						await wait(80)
+						;[...document.querySelectorAll('.demo-panel-buttons button')].find(node => node.textContent.includes('交互开关与快捷键'))?.click()
+						await wait(100)
+						const cascadeToggle = document.querySelector('[data-demo=cascade-highlight-enabled]')
+						const cascadeScope = document.querySelector('[data-demo=cascade-highlight-scope]')
+						const cascadeReadoutNode = document.querySelector('[data-demo=cascade-highlight-readout]')
+						check('级联高亮 demo：交互面板有开关、范围下拉与读数，默认开启且范围为节点 + 线路',
+							Boolean(cascadeToggle && cascadeScope && cascadeReadoutNode) && cascadeToggle.checked && cascadeScope.value === 'both' && cascadeReadoutNode.textContent.includes('级联高亮'),
+							`${cascadeToggle?.checked} / ${cascadeScope?.value} / ${cascadeReadoutNode?.textContent.trim() ?? '没有读数'}`)
+						const cascadeData = cascadeView.getData()
+						const cascadeLine = cascadeData.lines.find(line => line.from !== undefined && line.to !== undefined)
+						let cascadeTarget = cascadeData.points.find(point => String(point.id) === String(cascadeLine?.from))
+						if (!cascadeTarget && Array.isArray(cascadeLine?.path) && cascadeLine.path.length >= 2) {
+							const [x, y] = cascadeLine.path[0]
+							cascadeTarget = cascadeData.points.find(point => Math.abs(Number(point.x) - Number(x)) < 1e-9 && Math.abs(Number(point.y) - Number(y)) < 1e-9)
+						}
+						const cascadePoint = cascadeTarget ? cascadeView.getPoint(cascadeTarget.id) : null
+						if (cascadePoint?.screen) {
+							const cascadeRect = cascadeCanvas.getBoundingClientRect()
+							tap(cascadeCanvas, { clientX: cascadeRect.left + cascadePoint.screen[0], clientY: cascadeRect.top + cascadePoint.screen[1] })
+							await wait(220)
+						}
+						const cascadeInfo = cascadeView.getCascadeHighlight()
+						check('级联高亮 demo：点节点后画布进入级联态，面板读数给出节点 / 线路条数',
+							cascadeInfo?.origin?.target === 'point' && cascadeInfo.pointIndexes.length >= 1 && cascadeInfo.lineIndexes.length >= 1 && cascadeReadoutNode.textContent.includes('不改选中集'),
+							JSON.stringify({ origin: cascadeInfo?.origin?.item?.id, points: cascadeInfo?.pointIndexes, lines: cascadeInfo?.lineIndexes, readout: cascadeReadoutNode.textContent.trim() }))
+						cascadeScope.value = 'points'
+						cascadeScope.dispatchEvent(new Event('change', { bubbles: true }))
+						await wait(140)
+						const cascadePointsOnly = cascadeView.getCascadeHighlight()
+						check('级联高亮 demo：范围切到 points 后只亮节点，面板与 getOptions 同步',
+							cascadeView.getOptions().cascadeHighlight?.scope === 'points' && cascadePointsOnly?.scope === 'points' && cascadePointsOnly.lineIndexes.length === 0,
+							JSON.stringify({ scope: cascadePointsOnly?.scope, lines: cascadePointsOnly?.lineIndexes, option: cascadeView.getOptions().cascadeHighlight?.scope }))
+						cascadeToggle.click()
+						await wait(140)
+						check('级联高亮 demo：关掉开关后 getCascadeHighlight() 归零，读数写明已关闭',
+							cascadeView.getOptions().cascadeHighlight === false && cascadeView.getCascadeHighlight() === null && cascadeReadoutNode.textContent.includes('关闭'),
+							`${cascadeView.getOptions().cascadeHighlight} / ${cascadeView.getCascadeHighlight()} / ${cascadeReadoutNode.textContent.trim()}`)
+						// 还原成默认开 + both，别把后面的综合示例断言带进一个关掉的状态
+						cascadeScope.value = 'both'
+						cascadeScope.dispatchEvent(new Event('change', { bubbles: true }))
+						cascadeToggle.click()
+						await wait(100)
+
+						;[...document.querySelectorAll('.demo-panel-buttons button')].find(node => node.textContent.includes('复制与合并'))?.click()
+						await wait(100)
+						const mergeHint = document.querySelector('[data-demo=merge-style-hint]')
+						check('合并样式 demo：读数明确说明它是最终 size / symbol，并给出规则与改写入口',
+							Boolean(mergeHint) && mergeHint.textContent.includes('合并样式') && mergeHint.textContent.includes('不是一项额外配置') && mergeHint.textContent.includes('尺寸取双方较大值') && mergeHint.textContent.includes('merge.createItem'),
+							mergeHint?.textContent.trim() ?? '没有合并样式读数')
+					}
+					else {
+						check('级联高亮 demo：画布与视图都起来了', false, ready ? '没有 setupState.viewRef' : '没有 canvas')
+					}
+					// 面板在弹层里（v-show）：先切到「开关 · 历史」页签，再点出「实例方法速查」那一块
+					;[...document.querySelectorAll('.demo-tabs button')].find(node => node.textContent.includes('开关'))?.click()
 					await wait(80)
 					;[...document.querySelectorAll('.demo-panel-buttons button')].find(node => node.textContent.includes('实例方法速查'))?.click()
 					await wait(150)
 					const apiItems = () => [...document.querySelectorAll('.demo-api-list:not(.demo-api-list--options) .demo-api-item')]
 					const optionItems = () => [...document.querySelectorAll('.demo-api-list--options .demo-api-item')]
-					check('实例方法速查：整份成员清单按分组列全（16 组 / 249 个成员）',
-						Boolean(ready) && document.querySelectorAll('.demo-api-group').length === 16 && apiItems().length === 249,
-						`${document.querySelectorAll('.demo-api-group').length} 组 / ${apiItems().length} 个成员`)
+					check('实例方法速查：整份成员清单按分组列全（16 组 / 253 个成员）',
+						Boolean(ready) && document.querySelectorAll('.demo-api-group').length === 16 && apiItems().length === 253,
+						`${document.querySelectorAll('.demo-api-group').length} 组 / ${apiItems().length} 个成员`)
 					const apiNames = apiItems().map(node => node.querySelector('b')?.textContent)
 					const roundNames = ['registerSymbol', 'unregisterSymbol', 'listSymbols']
 					check('实例方法速查：本轮新增的三个方法都在清单里（registerSymbol / unregisterSymbol / listSymbols）',
@@ -2035,7 +2253,7 @@
 					check('实例方法速查：这一轮拆出来的方法也在清单里（addChannelGroupLines / joinChannelGroupLines / endAddChannel）',
 						roundNames1597.every(name => apiNames.includes(name)),
 						roundNames1597.filter(name => !apiNames.includes(name)).join(' / ') || '三个都在')
-					check('实例方法速查：options 折叠清单列全 92 个键', optionItems().length === 92, `${optionItems().length} 个键`)
+					check('实例方法速查：options 折叠清单列全 95 个键', optionItems().length === 95, `${optionItems().length} 个键`)
 					const apiSearch = document.querySelector('.demo-api-search input[type="search"]')
 					apiSearch.value = 'focusOn'
 					apiSearch.dispatchEvent(new Event('input', { bubbles: true }))
@@ -2120,7 +2338,7 @@
 						const openChannelPanel = async () => {
 							;[...document.querySelectorAll('.demo-panel-buttons button')].find(node => node.textContent.trim() === '通道与拐点')?.click()
 							await wait(140)
-							return [...document.querySelectorAll('.demo-popover button')].find(node => node.textContent.trim() === '新建通道（点两个节点）') ?? null
+							return [...document.querySelectorAll('.demo-panel-inline button')].find(node => node.textContent.trim() === '新建通道（点两个节点）') ?? null
 						}
 						let beginDraftButton = await openChannelPanel()
 						if (!beginDraftButton) {
@@ -2208,10 +2426,152 @@
 						check('新增通道：综合示例的实例拿得到（setupState.viewRef）', false, '没有 setupState.viewRef')
 					}
 				}
-				else {
-					check('实例方法速查：综合示例的页签在', false, '没找到「综合」页签')
-				}
-				// 2.10 假后端契约：头 / body 必须一致，同 opId 换 body 必须报幂等冲突
+				else {
+					check('实例方法速查：综合示例的页签在', false, '没找到「综合」页签')
+				}
+				// 2.9b 接口能力：级联三种触发、通道 / 分组 / 拐点选中、lineFollowsNode 与 focusOn
+				if (await clickTab('接口能力')) {
+					const ready = await canvasReady()
+					const demo = await until(() => [...document.querySelectorAll('.dv-demo')].find(node => node.textContent.includes('级联高亮三种触发')), 8000)
+					const setup = demo?.__vueParentComponent?.setupState
+					const apiView = await until(() => setup?.view?.getSelectionData ? setup.view : null, 8000)
+					if (ready && apiView) {
+						await until(() => apiView.listPoints().length > 0, 5000)
+						const triggerClick = document.querySelector('[data-demo=cascade-trigger-click]')
+						const triggerMulti = document.querySelector('[data-demo=cascade-trigger-multi]')
+						const triggerBox = document.querySelector('[data-demo=cascade-trigger-box]')
+						check('接口能力 demo：三种级联触发都有控件，默认全部打开并写进 getOptions',
+							Boolean(triggerClick && triggerMulti && triggerBox) && triggerClick.checked && triggerMulti.checked && triggerBox.checked &&
+								apiView.getOptions().cascadeHighlight?.triggerOnClick === true &&
+								apiView.getOptions().cascadeHighlight?.triggerOnMultiSelect === true &&
+								apiView.getOptions().cascadeHighlight?.triggerOnBoxSelect === true,
+							`${triggerClick?.checked} / ${triggerMulti?.checked} / ${triggerBox?.checked} · ${JSON.stringify(apiView.getOptions().cascadeHighlight)}`)
+						triggerBox.click()
+						await wait(100)
+						check('接口能力 demo：triggerOnBoxSelect 可以单独关掉，不影响另外两路',
+							apiView.getOptions().cascadeHighlight?.triggerOnBoxSelect === false &&
+								apiView.getOptions().cascadeHighlight?.triggerOnClick === true &&
+								apiView.getOptions().cascadeHighlight?.triggerOnMultiSelect === true,
+							JSON.stringify(apiView.getOptions().cascadeHighlight))
+						triggerBox.click()
+						document.querySelector('[data-demo=select-channel]')?.click()
+						await wait(100)
+						const channelSelection = apiView.getSelectionData()
+						check('接口能力 demo：selectFeatures 显式选中整条通道，getSelectionData 读回通道计数',
+							channelSelection.count > 0 && channelSelection.channelCount > 0 && channelSelection.lineCount > 0,
+							JSON.stringify({ count: channelSelection.count, channels: channelSelection.channelCount, lines: channelSelection.lineCount }))
+						document.querySelector('[data-demo=select-group]')?.click()
+						await wait(100)
+						const groupSelection = apiView.getSelectionData()
+						check('接口能力 demo：selectFeatures 显式选中分组，读回只落在这一组的回线上',
+							groupSelection.count > 0 && groupSelection.channelCount > 0 && groupSelection.lineCount > 0,
+							JSON.stringify({ count: groupSelection.count, channels: groupSelection.channelCount, lines: groupSelection.lineCount }))
+						document.querySelector('[data-demo=select-waypoint]')?.click()
+						await wait(120)
+						const waypointSelection = apiView.getSelectionData()
+						const waypointLine = apiView.listLines().find(line => String(line.item?.id) === 'line-0')
+						check('接口能力 demo：selectWaypoint 补出中间点并同时选中所在线路',
+							Boolean(waypointLine) && apiView.getWaypoints(waypointLine.index).length >= 1 && waypointSelection.lineCount >= 1,
+							JSON.stringify({ waypoints: waypointLine ? apiView.getWaypoints(waypointLine.index).length : -1, lines: waypointSelection.lineCount }))
+						const linesBeforeHide = apiView.listLines({ visibleOnly: true }).length
+						const toggleEndpoint = document.querySelector('[data-demo=toggle-endpoint]')
+						const lineFollows = document.querySelector('[data-demo=line-follows-node]')
+						toggleEndpoint?.click()
+						await wait(260)
+						const linesWhileFollowing = apiView.listLines({ visibleOnly: true }).length
+						lineFollows?.click()
+						await wait(260)
+						const linesWithoutFollowing = apiView.listLines({ visibleOnly: true }).length
+						check('接口能力 demo：lineFollowsNode 开时隐藏端点会带走绑定线路，关掉后线路保留',
+							linesWhileFollowing < linesBeforeHide && linesWithoutFollowing > linesWhileFollowing && apiView.getOptions().lineFollowsNode === false,
+							`线路 ${linesBeforeHide} → 跟随 ${linesWhileFollowing} → 不跟随 ${linesWithoutFollowing}`)
+						lineFollows?.click()
+						toggleEndpoint?.click()
+						await wait(260)
+						const cameraBefore = apiView.getCamera()
+						document.querySelector('[data-demo=focus-channel]')?.click()
+						await wait(120)
+						const cameraAfter = apiView.getCamera()
+						check('接口能力 demo：focusOn({ type: channel }) 走统一包围盒适配并更新相机',
+							cameraAfter.scale > 0 && (cameraAfter.scale !== cameraBefore.scale || cameraAfter.center[0] !== cameraBefore.center[0] || cameraAfter.center[1] !== cameraBefore.center[1]),
+							`scale ${cameraBefore.scale} → ${cameraAfter.scale} · center ${JSON.stringify(cameraBefore.center)} → ${JSON.stringify(cameraAfter.center)}`)
+						document.querySelector('[data-demo=style-apis]')?.click()
+						await wait(80)
+						const styledOptions = apiView.getOptions()
+						const styleReadout = document.querySelector('[data-demo=advanced-readout]')?.textContent ?? ''
+						check('接口能力 demo：updatePointStyle / updateLineStyle 字段级合并并给出读数',
+							styledOptions.pointStyle?.color === '#fde68a' && styledOptions.lineStyle?.color === '#fbbf24' && styleReadout.includes('updatePointStyle / updateLineStyle'),
+							JSON.stringify({ point: styledOptions.pointStyle, line: styledOptions.lineStyle }))
+						document.querySelector('[data-demo=style-apis]')?.click()
+						await wait(80)
+						document.querySelector('[data-demo=point-decoration-apis]')?.click()
+						document.querySelector('[data-demo=line-decoration-apis]')?.click()
+						await wait(120)
+						const decorationReadout = document.querySelector('[data-demo=advanced-readout]')?.textContent ?? ''
+						check('接口能力 demo：节点 / 线路装饰的 add、update、remove 三个入口都能收尾',
+							decorationReadout.includes('线路装饰 CRUD') && decorationReadout.includes('updateLineDecoration size=20') && apiView.getPointDecorations('node-0').length === 0 && apiView.getLineDecorations('line-0').length === 0,
+							decorationReadout.slice(-160))
+						document.querySelector('[data-demo=channel-line-apis]')?.click()
+						await wait(120)
+						const channelApiReadout = document.querySelector('[data-demo=advanced-readout]')?.textContent ?? ''
+						check('接口能力 demo：通道线宽、getChannelBetween、线路对账与 removeLines 同屏跑通',
+							channelApiReadout.includes('setChannelLineWidth=3.4→2.6') && channelApiReadout.includes('getChangedLines=1 条') && channelApiReadout.includes('removeLines=ok') && !apiView.getData().lines.some(line => String(line.id) === 'api-temp-line'),
+							channelApiReadout.slice(-180))
+						document.querySelector('[data-demo=geo-background-apis]')?.click()
+						await wait(160)
+						const geoReadout = document.querySelector('[data-demo=advanced-readout]')?.textContent ?? ''
+						check('接口能力 demo：updateBackground 后能读 getBackgroundLabels / getGeoProjection / mapDataToGeoJson',
+							Boolean(apiView.getGeoProjection()) && (apiView.getBackgroundLabels()?.length ?? 0) > 0 && geoReadout.includes('mapDataToGeoJson=') && geoReadout.includes('节点'),
+							geoReadout.slice(-180))
+						document.querySelector('[data-demo=geo-background-apis]')?.click()
+						await wait(120)
+						check('接口能力 demo：再次 updateBackground({}) 恢复透明底、投影读数回到 null', apiView.getGeoProjection() === null, String(apiView.getGeoProjection()))
+						const pointsBeforeAdvanced = apiView.getData().points.length
+						document.querySelector('[data-demo=history-apis]')?.click()
+						await wait(120)
+						const historyReadout = document.querySelector('[data-demo=advanced-readout]')?.textContent ?? ''
+						check('接口能力 demo：undo / canRedo / redo、合并收尾、落点预览与 isLayoutReady 都有读数',
+							historyReadout.includes('canRedo=true') && historyReadout.includes('isLayoutReady=') && historyReadout.includes('getDropPreview=point') && apiView.getDropPreview() === null,
+							historyReadout.slice(-220))
+						document.querySelector('[data-demo=copy-apis]')?.click()
+						await wait(120)
+						const copyReadout = document.querySelector('[data-demo=advanced-readout]')?.textContent ?? ''
+						check('接口能力 demo：beginCopyPoint / updateCopyPoint / commitPointCopy 演示完会清理临时复制品',
+							copyReadout.includes('updateCopyPoint=接口复制预览') && copyReadout.includes('commitPointCopy=ok') && copyReadout.includes('removePoints=ok') && apiView.getData().points.length === pointsBeforeAdvanced,
+							copyReadout.slice(-180))
+						document.querySelector('[data-demo=remove-apis]')?.click()
+						await wait(120)
+						const removeReadout = document.querySelector('[data-demo=advanced-readout]')?.textContent ?? ''
+						check('接口能力 demo：requestRemove → getRemoveRequest → cancel，再走 removeSelected',
+							removeReadout.includes('getRemoveRequest=pending') && removeReadout.includes('cancel=cleared') && removeReadout.includes('removeSelected=1 个节点') && !apiView.getData().points.some(point => String(point.id) === 'api-remove-node'),
+							removeReadout.slice(-180))
+						document.querySelector('[data-demo=once-api]')?.click()
+						await wait(80)
+						check('接口能力 demo：once 只触发一次', (document.querySelector('[data-demo=advanced-readout]')?.textContent ?? '').includes('只触发 1 次'), document.querySelector('[data-demo=advanced-readout]')?.textContent ?? '')
+						document.querySelector('[data-demo=webgl-apis]')?.click()
+						await wait(80)
+						check('接口能力 demo：clearWebGLLayers 清空临时层', apiView.getWebGLLayers().length === 0 && (document.querySelector('[data-demo=advanced-readout]')?.textContent ?? '').includes('剩余 0 层'), document.querySelector('[data-demo=advanced-readout]')?.textContent ?? '')
+						document.querySelector('[data-demo=registry-apis]')?.click()
+						await wait(80)
+						const registryReadout = document.querySelector('[data-demo=advanced-readout]')?.textContent ?? ''
+						check('接口能力 demo：unregisterSymbol / unregisterOperator 注销临时注册项',
+							registryReadout.includes('unregisterSymbol=true') && registryReadout.includes('unregisterOperator=true') && !apiView.listSymbols().includes('api-ring') && !apiView.listOperators().includes('api-even'),
+							registryReadout.slice(-180))
+						document.querySelector('[data-demo=initial-options]')?.click()
+						await wait(60)
+						const optionsReadout = document.querySelector('[data-demo=advanced-readout]')?.textContent ?? ''
+						check('接口能力 demo：初始化 options 的 ariaLabel / labelRender / gridSize / fitOnInit 等能读回',
+							optionsReadout.includes('ariaLabel=接口能力演示画布') && optionsReadout.includes('labelRender=dom') && optionsReadout.includes('gridSize=96') && optionsReadout.includes('fitOnInit=true') && optionsReadout.includes('progressiveInit=true'),
+							optionsReadout.slice(-220))
+					}
+					else {
+						check('接口能力 demo：画布与 view 都起来了', false, ready ? '没拿到 view' : '没等到 canvas')
+					}
+				}
+				else {
+					check('接口能力 demo：页签在', false, '没找到「接口能力」页签')
+				}
+				// 2.10 假后端契约：头 / body 必须一致，同 opId 换 body 必须报幂等冲突
 				{
 					const { createFakeBackend } = await import('../demos/shared/fakeBackend.js')
 					const backend = createFakeBackend({ initialVersion: 12, latency: 0, prefix: 'contract' })

package/docs/steps/selftest-docs.html

@@ -518,8 +518,8 @@
 				if (check('API 速查：挂上了 __gisApi 钩子（数据来自 api-index.js，没钩子多半是 file:// 打开的）', Boolean(apiHook))) {
 					const apiDoc = apiFrame.contentDocument
 					const summary = apiHook.summary
-					check('API 速查：清单来自 api-index（249 个成员 / 92 个 options / 16 个分组）',
-						summary.members === 249 && summary.options === 92 && summary.sections === 16,
+					check('API 速查：清单来自 api-index（253 个成员 / 95 个 options / 16 个分组）',
+						summary.members === 253 && summary.options === 95 && summary.sections === 16,
 						JSON.stringify(summary))
 					check('API 速查：左侧分组有当前项，滚动 / 点选时会跟着亮', apiHook.activeGroup() !== null, String(apiHook.activeGroup()))
 					check('API 速查：分组都渲染出来（16 组 + options 一组）',
@@ -530,8 +530,8 @@
 						`${apiDoc.querySelectorAll('.api-member').length} 张卡片 / 属性 ${apiDoc.querySelectorAll('.api-member[data-kind="property"]').length} 张`)
 					const noExample = [...apiDoc.querySelectorAll('.api-member')].filter(node => Number(node.dataset.examples) < 1)
 					check('API 速查：每个成员都带至少一段示例（不出现空卡片）', noExample.length === 0,
-						noExample.length ? noExample.map(node => node.dataset.name).join(' / ') : '249 张卡片都有示例')
-					check('API 速查：92 个 options 都列全（名字 / 类型 / 默认值 / 说明四件套）',
+						noExample.length ? noExample.map(node => node.dataset.name).join(' / ') : '253 张卡片都有示例')
+					check('API 速查：95 个 options 都列全（名字 / 类型 / 默认值 / 说明四件套）',
 						apiDoc.querySelectorAll('.api-option').length === summary.options && [...apiDoc.querySelectorAll('.api-option')].every(node => node.querySelector('.name code') && node.querySelector('.type') && node.querySelector('.def') && node.querySelector('.doc')),
 						`${apiDoc.querySelectorAll('.api-option').length} 个`)
 					const statCards = [...apiDoc.querySelectorAll('#stats .api-stat')]