gis-view-webgl2 0.1.3 → 0.1.4

package/dist/index.d.ts

@@ -2886,7 +2886,7 @@ export interface GisViewClickPayload extends GisViewPickResult {
 	selection: GisViewSelectionInfo
 	/**
 	 * 这一次点击的判读：type 为 'select'（点中要素、选中已生效）或 'click'（没开选中时的普通点击），
-	 * double 为 true 说明这一下是双击里的第二下。点空白处的载荷是 null，
+	 * 多选取反生效时是 'toggleSelect'；double 为 true 说明这一下是双击里的第二下。点空白处的载荷是 null，
 	 * 「点了空白」这件事看 onPointerDown / onPointerUp 的 action.target（'empty'）与 selectChange。
 	 */
 	action: GisViewPointerAction
@@ -3681,6 +3681,8 @@ export type GisViewDataChangeType =
 	| 'addLines'
 	| 'removePoints'
 	| 'removeLines'
+	/** 删除型筛选（filter.mode: 'remove'）把不命中的要素从数据里删掉 */
+	| 'filterRemove'
 	| 'removeSelected'
 	| 'removeLine'
 	| 'removeChannel'
@@ -3704,6 +3706,8 @@ export interface GisViewDataChangePayload {
 	/** 动到 / 删掉的节点下标（单点更新是那一个，删除是删除前的下标升序，新增是它们在数组里的位置） */
 	index?: number
 	indexes?: number[]
+	/** 这一次删掉的节点下标（删除前它们在 points 里的位置，升序；removeSelected / filterRemove 会带上） */
+	pointIndexes?: number[]
 	/** 这一次调用成没成（addPoints / addLines / removePoints 这类批量接口会带上） */
 	ok?: boolean
 	/** 新增这类动作：这批要素是从哪个下标开始接上去的（就是追加前原数组的长度） */
@@ -3753,8 +3757,14 @@ export interface GisViewDataChangePayload {
 	lineIndex?: number
 	channelId?: string | number | null
 	channelIndex?: number
+	/** filterRemove：这次从数据里删掉的节点数据，顺序与 pointIndexes 对应 */
+	removedPoints?: GisViewPoint[]
+	/** filterRemove：这次从数据里删掉的线路数据，顺序与 removedLineIndexes 对应 */
+	removedLineItems?: GisViewLine[]
 	removedLineIds?: Array<string | number>
 	removedLineIndexes?: number[]
+	/** filterRemove：固定为 'remove'，便于按载荷分流 */
+	mode?: GisViewFilterMode
 	/** 通道分组：这条通道最新的分组声明 */
 	groups?: GisViewChannelGroup[]
 	replaced?: boolean
@@ -4886,19 +4896,29 @@ export interface GisViewTooltipOptions {
  */
 export type GisViewFilterCascade = false | 'binding' | 'coordinate' | 'both'
 
-/** 筛选条件：点、线各一个条件，缺省表示该维度不过滤 */
+/** 筛选模式：hide 只隐藏（缺省）；remove 把不命中的要素从数据里删掉（不可恢复，除非撤销） */
+export type GisViewFilterMode = 'hide' | 'remove'
+
+/**
+ * 筛选条件：点、线各一个条件，缺省表示该维度不过滤。
+ * 缺省 mode: 'hide' 只算「隐藏集合」，不改数据；已经选中的要素被隐藏后仍留在选中集里，
+ * 条件放宽 / 清空后会原样恢复高亮。mode: 'remove' 把筛选结果（hiddenPoints / hiddenLines）
+ * 真正从数据里删掉（走 dataChange('filterRemove')，可用撤销恢复；不会额外按节点联级删线路）。
+ */
 export interface GisViewFilter {
 	points?: GisViewConditionInput<GisViewPoint>
 	lines?: GisViewConditionInput<GisViewLine>
 	/** 联动隐藏，默认 binding */
 	cascade?: GisViewFilterCascade
+	/** 不命中的要素怎么处理：'hide' 只隐藏（默认），'remove' 从数据里删除 */
+	mode?: GisViewFilterMode
 	/** 是否用 Worker 计算，缺省跟随 options.filterWorker */
 	worker?: boolean
 }
 
 /**
  * 筛选条件的简写：只筛节点时可以直接给节点条件，等价于 `{ points: 条件 }`：
- * `view.setFilter({ vn_kv: { gte: 525 } })`。顶层出现 points / lines / cascade / worker
+ * `view.setFilter({ vn_kv: { gte: 525 } })`。顶层出现 points / lines / cascade / mode / worker
  * 任一键时按完整格式解释，因此简写里可以放心使用业务字段名。
  */
 export type GisViewFilterShorthand = GisViewConditionInput<GisViewPoint>
@@ -4906,7 +4926,7 @@ export type GisViewFilterShorthand = GisViewConditionInput<GisViewPoint>
 /** setFilter / options.filter 接受的条件：完整格式，或只筛节点的简写 */
 export type GisViewFilterInput = GisViewFilter | GisViewFilterShorthand
 
-/** 筛选结果：hiddenPoints / hiddenLines 是当前被隐藏的要素下标 */
+/** 筛选结果：hiddenPoints / hiddenLines 是当前被隐藏的要素下标；remove 模式删除完会回到空数组 */
 export interface GisViewFilterResult {
 	filter: GisViewFilter | null
 	hiddenPoints: number[]
@@ -5218,6 +5238,24 @@ export interface GisViewPluginContext {
 
 export type GisViewPlugin = (view: GisViewInstance, context: GisViewPluginContext) => void | { destroy?: () => void }
 
+/** 实例命令的上下文：注册表属于这个视图，handler 里拿它就能继续调实例方法 */
+export interface GisViewCommandContext {
+	readonly view: GisViewInstance
+	/** 这次执行注册时用的命令名（已去掉首尾空白） */
+	readonly name: string
+}
+
+/** 实例命令：同步执行；返回值原样放进 GisViewCommandResult.value */
+export type GisViewCommandHandler<Payload = unknown, Value = unknown> = (payload: Payload, context: GisViewCommandContext) => Value
+
+/** executeCommand 的读数：拿到命令并执行成功时 ok: true；没注册 / 名字非法 / handler 抛错时 ok: false 并给原因 */
+export interface GisViewCommandResult<Value = unknown> {
+	readonly ok: boolean
+	readonly name: string
+	readonly value?: Value
+	readonly reason?: string
+}
+
 /**
  * 快捷键写法（大小写不敏感，多个用 + 连接）：
  * - 纯修饰键：`ctrl` / `meta` / `shift` / `alt` / `mod`（`ctrl` 同时认 macOS 的 ⌘），按住 + 操作；
@@ -6025,6 +6063,12 @@ export interface GisViewWebGLLayer {
 	draw(context: GisViewWebGLLayerDrawContext): void
 }
 
+/**
+ * 选中触发方式：'click'（缺省）在第一次单击时改选中集；'dblClick' 等到双击的第二下才改，
+ * 第一下仍照常派发 onClick。两种方式下 onDblClick 都会在双击第二下派发。
+ */
+export type GisViewSelectTrigger = 'click' | 'dblClick'
+
 export interface GisViewOptions {
 	/**
 	 * 功能开关：预设名（'edit' / 'view' / 'static'）、开关表或布尔值 ——
@@ -6288,6 +6332,12 @@ export interface GisViewOptions {
 	 * 关着时多选仍走框选（boxSelect）与按住多选快捷键（默认 Ctrl / ⌘）。
 	 */
 	multiSelect?: boolean
+	/**
+	 * 选中触发方式：缺省 'click'（单击选中）；写 'dblClick' 后第一次点击只派发 onClick，
+	 * 第二次（双击判定命中）才更新选中集，并同时派发 onClick 与 onDblClick。
+	 * Ctrl / ⌘ 多选与 multiSelect 在双击模式下同样等到第二下才取反。运行时走 updateOptions({ selectTrigger })。
+	 */
+	selectTrigger?: GisViewSelectTrigger
 	/**
 	 * 框选 / Ctrl 多选允许收哪几类要素：'point' 节点、'line' 独立线路、'channel' 通道回线，
 	 * 可写数组任意组合，'all' / true 全开，false / null 全关。
@@ -6510,37 +6560,63 @@ export interface GisViewOptions {
 	onError?: (message: string) => void
 }
 
-/** 搜索范围：节点 / 线路 / 通道（通道会连成员回线一起搜） */
-export type GisViewSearchScope = 'points' | 'lines' | 'channels'
+/** 搜索范围（规范化后的键）：节点 / 线路 / 通道 / 通道分组（通道会连成员回线一起搜） */
+export type GisViewSearchScope = 'points' | 'lines' | 'channels' | 'groups'
+
+/** scope 的入参写法：复数的规范化键，或与 focusOn 目标一致的 point / line / channel / group 单数别名 */
+export type GisViewSearchScopeInput = GisViewSearchScope | 'point' | 'line' | 'channel' | 'group'
 
 export interface GisViewSearchOptions {
 	/** 关键字：空格分隔多个词时要在同一个字段里全部出现才命中，不区分大小写 */
 	keyword?: string
-	/** 搜索范围，缺省三类都搜 */
-	scope?: GisViewSearchScope | GisViewSearchScope[]
+	/**
+	 * 搜索范围，缺省四类都搜。复数的 points / lines / channels / groups 与单数别名
+	 * point / line / channel / group 都收；写错或空数组会回落到四类全搜。
+	 */
+	scope?: GisViewSearchScopeInput | GisViewSearchScopeInput[]
 	/** 限定参与匹配的字段路径（如 ['name', 'props.vn_kv']），缺省用要素的全部字段 */
 	fields?: string[]
 	/** 每类要素的命中上限，缺省 200，0 表示不限 */
 	limit?: number
 }
 
+/**
+ * 分组搜索命中里的 item：与 getChannelGroups() 的读数同源，但只保留搜索与定位需要的轻量字段
+ * （不带骨架 / 回线几何）。groupIndex 是这一组在所属通道里的序号（从 0 起）。
+ */
+export interface GisViewSearchGroupItem {
+	channelId: string | number
+	channelIndex: number
+	id: string | number
+	groupIndex: number
+	lineIndexes: number[]
+	lineIds: Array<string | number>
+	lineCount: number
+	anchored: boolean
+	edited: boolean
+}
+
 /** 一条搜索命中：field / value 是命中的那一项，bounds 用来居中或适应视图 */
 export interface GisViewSearchHit {
-	kind: 'point' | 'line' | 'channel'
-	/** 点 / 线在数据里的下标；通道是通道下标 */
+	kind: 'point' | 'line' | 'channel' | 'group'
+	/** 点 / 线在数据里的下标；通道是通道下标；分组是 groups 结果里的下标 */
 	index: number
 	id?: string | number
-	item: GisViewPoint | GisViewLine | GisViewChannel
+	item: GisViewPoint | GisViewLine | GisViewChannel | GisViewSearchGroupItem
 	field: string
 	value: string
 	bounds: GisViewBounds
-	/** 要素属于某条通道时给出通道下标（线路命中，或通道命中自身字段） */
+	/** 要素属于某条通道时给出通道下标（线路 / 分组命中，或通道命中自身字段） */
 	channelIndex?: number
 	/** 通道内第几条回线（0 开始） */
 	memberIndex?: number
 	/** 通道命中来自回线时，该回线在 lines 里的下标与 id */
 	memberLineIndex?: number
 	memberLineId?: string | number
+	/** 分组命中：分组 id（与 focusOn / selectFeatures 的 groupId 同一口径） */
+	groupId?: string | number
+	/** 分组命中：这一组在所属通道里的序号（从 0 起） */
+	groupIndex?: number
 }
 
 export interface GisViewSearchResult {
@@ -6549,7 +6625,8 @@ export interface GisViewSearchResult {
 	points: GisViewSearchHit[]
 	lines: GisViewSearchHit[]
 	channels: GisViewSearchHit[]
-	/** 三类命中的合集，顺序是节点、线路、通道 */
+	groups: GisViewSearchHit[]
+	/** 四类命中的合集，顺序是节点、线路、通道、分组 */
 	hits: GisViewSearchHit[]
 	total: number
 	/** 命中数达到上限被截断 */
@@ -6575,13 +6652,15 @@ export type GisViewFocusTarget = GisViewSearchHit | GisViewFeatureKey | GisViewS
 export type GisViewFocusTargets = GisViewFocusTarget | GisViewFocusTarget[]
 
 export interface GisViewFocusOptions {
-	/** 直接设成这个比例（像素 / 世界单位）；不给就按目标范围适应视图 */
+	/** 直接设成这个比例（像素 / 世界单位）；优先级高于 zoom */
 	scale?: number
-	/** 只把中心挪到目标上、比例一点不动（聚焦一个点又不想改缩放时用） */
+	/** 显式要求按目标范围适应视图；**缺省不缩放**，只把中心移到目标上 */
+	zoom?: boolean
+	/** 显式只居中、比例一点不动（与缺省行为一致，保留旧写法） */
 	center?: boolean
-	/** 按范围适应视图时四周的留白（CSS 像素），缺省 40 */
+	/** 按范围适应视图（zoom: true）时四周的留白（CSS 像素），缺省 40 */
 	padding?: number
-	/** 适应视图时最多放大到多少比例：单个节点 / 一条直线没有面积，靠它决定要不要放大 */
+	/** 适应视图（zoom: true）时最多放大到多少比例：单个节点 / 一条直线没有面积，靠它决定要不要放大 */
 	maxZoom?: number
 	/**
 	 * 顺手把这些被聚焦的要素变成选中状态：`true` 选中这次聚焦的这批（通常配合搜索命中），
@@ -8083,6 +8162,16 @@ export interface GisViewInstance {
 	 * 调它就把这个插件返回的 `destroy` 清掉（重复调用只清一次；实例销毁之后再调也安全）
 	 */
 	use(plugin: GisViewPlugin): () => void
+	/**
+	 * 注册一个实例命令：`handler(payload, context)` 同步执行，`context.view` 就是这个视图。
+	 * 同名覆盖（后注册的生效）；返回幂等的注销函数，同名被后注册覆盖后旧卸载函数不会误删新命令。
+	 * 名字空 / handler 不是函数只报一条 onWarning；实例销毁后注册不生效。
+	 */
+	registerCommand<Payload = unknown, Value = unknown>(name: string, handler: GisViewCommandHandler<Payload, Value>): () => void
+	/** 执行一个实例命令：成功给 `{ ok: true, name, value }`；没注册 / 名字非法 / handler 抛错给 `{ ok: false, name, reason }` */
+	executeCommand<Value = unknown>(name: string, payload?: unknown): GisViewCommandResult<Value>
+	/** 当前注册着哪些实例命令（按注册顺序；同名覆盖不改变原来的位置） */
+	listCommands(): string[]
 	/**
 	 * 注册一个自定义图元：名字写进数据的 `symbol` 字段（`symbol: '三角'`），画法交给一支画笔
 	 * （`painter(context, info)`，读数见 `GisViewSymbolPainterInfo`）。注册完（或换一支画笔之后）
@@ -8234,6 +8323,8 @@ export interface GisViewEngineOptions {
 	zoom?: boolean
 	hover?: boolean
 	select?: boolean
+	/** 选中触发方式：'click'（缺省）或 'dblClick'，见 GisViewSelectTrigger */
+	selectTrigger?: GisViewSelectTrigger
 	contextMenu?: boolean
 	/**
 	 * 右键默认把浏览器的系统菜单收掉（组件接住右键时 preventDefault contextmenu）。
@@ -8379,6 +8470,10 @@ export interface GisViewEngine {
 	getChannels(): GisViewChannelInfo[]
 	/** 单条通道运行时状态：只复制这一组；channelId 找不到时可按 channels 下标兜底 */
 	getChannel(channelId?: string | number | null, channelIndex?: number): GisViewChannelInfo | null
+	/** 单条通道的范围：按当前骨架与每条回线的折线计算，不复制几何；channelId 找不到时可按 channels 下标兜底 */
+	getChannelBounds(channelId?: string | number | null, channelIndex?: number): GisViewBounds | null
+	/** 一个分组的范围：按这一组当前骨架与回线折线计算，不复制几何；没有 channelId 时按通道下标兜底 */
+	getChannelGroupBounds(channelId: string | number | null | undefined, groupId: string | number, channelIndex?: number): GisViewBounds | null
 	/** 通道成员表：成员回线下标与各自的横向偏移，不复制几何（自建覆盖层按通道分流绘制用它） */
 	getChannelMembers(): GisViewChannelMembers[]
 	/** 通道分组现状：不传 channelId 返回所有分组 */