gis-view-webgl2 0.1.6 → 0.1.7

package/dist/index.d.ts

@@ -2724,6 +2724,11 @@ export interface GisViewPickResult extends GisViewFeatureKey {
 	groupIndex?: number
 	/** 命中的是通道内的回线时，这一组的读数（成员、拐点数、骨架），结构与 getChannelGroups 的一项一致 */
 	group?: GisViewChannelGroupInfo & { groupIndex: number; lineCount: number; waypointCount: number }
+	/**
+	 * 命中的是通道内的回线时，同一通道全部分组的读数（按声明顺序，每项 groupIndex 是组号）。
+	 * `group` 是当前命中的那一组，`groups` 是整条通道的分组表；通道外的线路没有这两个字段。
+	 */
+	groups?: Array<GisViewChannelGroupInfo & { groupIndex: number; lineCount: number; waypointCount: number }>
 }
 
 /** 点聚合配置：true 等价于开着一份缺省档；对象写法可逐项覆盖。 */
@@ -2792,8 +2797,46 @@ export type GisViewClusterClickPayload = GisViewClusterPickResult & {
 	action: GisViewPointerAction
 }
 
+/**
+ * 一条被选中的通道的上下文：通道本身、当前组与全部分组。
+ * 单通道选中时这些字段直接摊平到选中载荷顶层；多通道时改为 channelContexts 里的一项，不会两处重复。
+ */
+export interface GisViewSelectionChannelContext {
+	channelId: string | number
+	channelIndex: number
+	channel: GisViewChannel
+	/** 当前组：真实点击 / selectAt 是命中的那一组；框选 / 按引用接口是选中集里第一条通道回线所在的组 */
+	groupId: string | number
+	groupIndex: number
+	group: GisViewChannelGroupInfo & { groupIndex: number; lineCount: number; waypointCount: number }
+	/** 同一通道的全部分组（按声明顺序；同一条通道内与其他载荷项共享这一份数组） */
+	groups: Array<GisViewChannelGroupInfo & { groupIndex: number; lineCount: number; waypointCount: number }>
+	/** 本次选中集里属于这条通道的回线下标 / id */
+	lineIndexes: number[]
+	lineIds: Array<string | number>
+}
+
+/** 选中载荷里的通道上下文字段：只有一条通道时摊平，多通道时只保留 channelContexts */
+export interface GisViewSelectionChannelFields {
+	channelId?: string | number
+	channelIndex?: number
+	channel?: GisViewChannel
+	groupId?: string | number
+	groupIndex?: number
+	group?: GisViewChannelGroupInfo & { groupIndex: number; lineCount: number; waypointCount: number }
+	groups?: Array<GisViewChannelGroupInfo & { groupIndex: number; lineCount: number; waypointCount: number }>
+	/** 选中集涉及多条通道时才有（按选中顺序）；单通道不创建这一份，直接读顶层平铺字段 */
+	channelContexts?: GisViewSelectionChannelContext[]
+}
+
+/** describeSelection 的返回值：要素读数 + 与选中载荷同一套通道上下文字段 */
+export interface GisViewDescribedSelection extends GisViewSelectionChannelFields {
+	items: GisViewPickResult[]
+}
+
 /** 选中事件载荷：点击选中为 0 / 1 个要素，Shift 框选为框内全部节点（随 shortcuts.boxSelect 改变） */
-export interface GisViewSelectPayload {
+export interface GisViewSelectPayload extends GisViewSelectionChannelFields {
+	/** 选中项；通道回线只带 channelId / channelIndex / groupId / groupIndex 标量归属，分组读数看顶层或 channelContexts */
 	items: GisViewPickResult[]
 	/** 框选时的画布 CSS 像素矩形，点击选中为 null */
 	box: GisViewRect | null
@@ -2901,7 +2944,8 @@ export interface GisViewSelectionData {
  * 选中集变更载荷：与 onSelect 的区别是这个只在「选中集真的变了」时发一条，
  * 接口选中（select / clearSelection / selectInBox）也会发。
  */
-export interface GisViewSelectChangePayload extends GisViewSelectionInfo {
+export interface GisViewSelectChangePayload extends GisViewSelectionInfo, GisViewSelectionChannelFields {
+	/** 与对应 onSelect 载荷共用同一批对象；通道回线不重复挂 group / groups */
 	items: GisViewPickResult[]
 	/** 框选时的矩形，其余为 null */
 	box: GisViewRect | null
@@ -3136,6 +3180,8 @@ export interface GisViewPointerPayload {
 	groupIndex?: number
 	/** 命中的是通道内的回线时，这一组的读数 */
 	group?: GisViewChannelGroupInfo & { groupIndex: number; lineCount: number; waypointCount: number }
+	/** 命中的是通道内的回线时，同一通道全部分组的读数；`group` 是当前这组，`groups` 是整条通道 */
+	groups?: Array<GisViewChannelGroupInfo & { groupIndex: number; lineCount: number; waypointCount: number }>
 	/** 命中通道回线时的分组上下文：action.target 为 channel，按它直接渲染通道菜单 */
 	channelContext?: GisViewChannelContext
 	/** 命中多成员聚合时：聚合 id、成员数、成员下标 / id、包围盒与屏幕半径 */
@@ -6569,6 +6615,16 @@ export interface GisViewOptions {
 	maxCanvasPixels?: number
 	ariaLabel?: string
 	onReady?: (payload: GisViewReadyPayload) => void
+	/**
+	 * 本次选中操作：真实单击 / Ctrl 与 multiSelect 取反 / 框选 / selectAt 每次成功操作都发；
+	 * selectFeatures / deselect / focusOn({ select }) 等按引用接口只在选中集实际变化时发。
+	 * 清空与取反取没了时载荷是 null。onSelectChange 仍只在选中集实际变化时发。
+	 * 真实点击的派发顺序是 onClick → onSelect → onSelectChange；单通道选中时载荷顶层带
+	 * channelId / group / groups，多通道看 channelContexts。items 里的回线只带 channelId /
+	 * channelIndex / groupId / groupIndex 这些标量归属，不重复挂 group / groups；需要分组读数
+	 * 从顶层或 channelContexts 取。onSelect 与 onSelectChange 各自可独立订阅，两条载荷引用同一份
+	 * items 与分组数组，不会深拷贝；按只读使用，不要在回调里改载荷。
+	 */
 	onSelect?: (payload: GisViewSelectPayload | null) => void
 	/** 单击要素或空白处 */
 	onClick?: (payload: GisViewClickPayload | null) => void
@@ -6644,8 +6700,11 @@ export interface GisViewOptions {
 	 */
 	onDataChange?: (payload: GisViewDataChangePayload) => void
 	/**
-	 * 选中集变化：与 onSelect 的区别有两点 —— 只在选中集真的变了时发一条（框选拖动 / 数据补发不会重复发），
-	 * 并且接口选中（select / clearSelection / selectInBox）也走这里；载荷带 ids / count / 各类型条数与来源 cause。
+	 * 选中集变化：覆盖所有来源（点击 / 框选 / selectFeatures / deselect / selectAt / selectInBox），
+	 * 且只在选中集真的变了时发一条；载荷带 ids / count / 各类型条数与来源 cause。
+	 * 与 onSelect 共用同一份选中集；需要「任何来源只通知一次」时优先订阅这一条。
+	 * 通道上下文与 onSelect 同一份：单通道摊平 channelId / group / groups，多通道给 channelContexts；
+	 * 不与 items 重复，两个事件共享同一批对象引用（按只读使用）。
 	 */
 	onSelectChange?: (payload: GisViewSelectChangePayload) => void
 	/**
@@ -7739,9 +7798,17 @@ export interface GisViewInstance {
 	/**
 	 * 按浏览器客户端坐标拾取（鼠标事件里的 clientX / clientY）：与指针事件载荷同一份读数，另加 target
 	 * （'point' / 'line' / 'channel'）与 lngLat（配了 GeoJSON 底图才有）；没命中返回 null。
+	 * 命中通道回线时给 group（当前这一组）与 groups（同一通道的全部分组）。
 	 * 只读 —— 不改选中、不动光标。自建浮层 / 自定义菜单 / 拖拽放下时「问一下这儿是什么」用它
 	 */
 	pickAt(clientX: number, clientY: number): GisViewPickAtResult | null
+	/**
+	 * 按客户端坐标做一次「普通单击选中」：与画布点击共用命中顺序与选中状态，
+	 * 通道回线按 channelSelectMode 摊开。空白 / 聚合圆返回 null 且不改选中。
+	 * 立即生效，不等待 selectTrigger: 'dblClick'，也不派发 onClick / onDblClick；选中集实际变化时发
+	 * onSelect / onSelectChange。已知节点 / 线路 id 时直接用 selectFeatures，不必先求坐标。
+	 */
+	selectAt(clientX: number, clientY: number): GisViewSelectPayload | null
 	/**
 	 * 程序化悬停（参数就是鼠标事件里的 clientX / clientY）：让指针「停」到这个位置上 ——
 	 * 悬停高亮、光标与 onHover 都按它更新（外部列表 / 表格 hover 到某一行时联动高亮图上的要素）。
@@ -7768,7 +7835,8 @@ export interface GisViewInstance {
 	getLineChannel(ref: GisViewFeatureRef): GisViewLineChannelInfo | null
 	/**
 	 * 让一批东西变成选中状态（接口选中）：与点击选中走同一份 state，因此 getSelections / getSelectionData
-	 * getSelectionData 立刻就能读回来。认这些写法（见 GisViewSelectionRef）：
+	 * 立刻就能读回来。会同步选中样式与读数；选中集实际变化时发 onSelect 与 onSelectChange（cause: api）。
+	 * 认这些写法（见 GisViewSelectionRef）：
 	 * ① 节点：id、`{ type: 'point', index: 3 }`、一批 id 与对象混着写；
 	 * ② 通道：`{ type: 'channel', channelId: 'channel-a' }` 选整条通道的回线，
 	 *    `{ channelId, groupId }` / `{ type: 'group', channelId, groupId }` 选某一组
@@ -7789,7 +7857,8 @@ export interface GisViewInstance {
 	 * 把这些从当前选中集里去掉，其余选中原样留着 —— `deselect('p-1')` 取消一个节点、
 	 * `deselect({ type: 'channel', channelId: 'channel-a' })` 取消整条通道的回线。
 	 * 一个目标都不给（不传 / 传 null）等于取消全部（与 selectFeatures(null) 同一件事），
-	 * 传空数组是「没有目标」，什么都不做；认不出来的条目跳过
+	 * 传空数组是「没有目标」，什么都不做；认不出来的条目跳过。改变选中集时发
+	 * onSelect 与 onSelectChange（cause: api）。
 	 */
 	deselect(refs?: GisViewSelectionRefs): GisViewInstance
 	/** 当前选中集的原始条目（`{ type, index, item, ... }`，与指针载荷同一份口径），不做整理、不读包围盒 */
@@ -8577,11 +8646,17 @@ export interface GisViewEngineOptions {
 	onCursor?: (coordinate: [number, number] | null) => void
 	onHover?: (payload: GisViewHoverPayload) => void
 	/**
+	 * 点击 / 框选路径（真实点击 / Ctrl 多选 / 框选（含 selectInBox）/ 空白清空）与 selectAt 每次成功操作都发；
+	 * selectFeatures / deselect / focusOn({ select }) 等按引用接口只在选中集实际变化时发。
+	 * 要统一监听所有来源并且避免点击同一要素时重复通知，请用 onSelectChange。
+	 * 真实点击的顺序是 onClick → onSelect → onSelectChange；Ctrl / multiSelect 取反与框选没有 onClick，
+	 * 顺序是 onSelect → onSelectChange。单通道选中时载荷顶层带 channelId / group / groups，多通道看 channelContexts。
+	 * items 里的回线只有标量归属，不重复挂 group / groups；两条回调共享同一批对象引用。
 	 * 载荷为 null（没有选中任何要素）时的补充读数：mode 说明这一下是哪一种选中方式 ——
 	 * 'multi' 是 Ctrl 点击取反取没了、'box' 是框选没框到东西；originalEvent 是那一次指针事件
 	 * （载荷里没有它时靠这一份读修饰键）。其余清空路径不带第二个参数
 	 */
-	onSelect?: (payload: GisViewSelectPayload | null, detail?: { mode?: 'single' | 'multi' | 'box'; originalEvent?: Event | null }) => void
+	onSelect?: (payload: GisViewSelectPayload | null, detail?: { mode?: 'single' | 'multi' | 'box'; originalEvent?: Event | null; defer?: boolean }) => void
 	onClick?: (payload: GisViewClickPayload | null) => void
 	/** 点中多成员聚合圆（引擎不选中成员，普通点击回调不会同时触发） */
 	onClusterClick?: (payload: GisViewClusterClickPayload, event: Event) => void
@@ -8628,6 +8703,8 @@ export interface GisViewEngine {
 	describe(selection: GisViewFeatureKey): GisViewPickResult | null
 	/** 批量把要素下标还原成拾取结果，框选与受控选中都用它 */
 	describeAll(selection: GisViewFeatureKey[]): GisViewPickResult[]
+	/** 批量还原并补通道上下文：单通道摊平 channelId / group / groups，多通道给 channelContexts */
+	describeSelection(selection: GisViewFeatureKey[], preferredGroupId?: string | number): GisViewDescribedSelection
 	/** 按画布 CSS 像素矩形框选，返回框内要素；第二段兼容旧的 Event 或 { selectionKinds, originalEvent } */
 	selectInBox(box: GisViewRect, options?: GisViewSelectInBoxOptions | Event | null): GisViewPickResult[]
 	/** 拐点增删改，insertIndex 缺省时按直线上离目标最近的线段插入 */
@@ -8856,6 +8933,8 @@ export interface GisViewEngine {
 	pick(x: number, y: number): GisViewHitResult | null
 	/** 与组件实例的 pickAt 同一份：按浏览器客户端坐标拾取（引擎不等 DOM 事件，直接给 clientX / clientY） */
 	pickAtClient(clientX: number, clientY: number): GisViewHitResult | null
+	/** 与组件实例的 selectAt 同一份：按客户端坐标走一次普通单击选中（通道按 channelSelectMode 摊开） */
+	selectAtClient(clientX: number, clientY: number): GisViewSelectPayload | null
 	/** 程序化悬停（客户端坐标）：让指针「停」在这儿，悬停高亮 / 光标 / onHover 一起更新，返回这一次的读数 */
 	hoverAtClient(clientX: number, clientY: number): GisViewHoverPayload | null
 	/** 取消程序化悬停：清掉高亮与读数并补发 onHover(null) */