gis-view-webgl2 0.1.1 → 0.1.2

package/dist/index.d.ts

@@ -1208,6 +1208,11 @@ export interface GisViewChannelGroup {
 	lineIds: Array<string | number>
 	/** 这一组自己的骨架拐点（两端锚定时只写中间拐点）：新拆分出来的分组不带拐点，就是一条直线 */
 	path?: GisViewCoordinate[]
+	/**
+	 * 刚性拐点偏移：键是分组骨架顶点序号（含首尾端点，从 0 起，只认中间拐点），值是这一组所有成员回线在该顶点的世界坐标增量。
+	 * `channelWaypointDragMode: 'vertex'` 拖出来的结果写在这里；不写或空对象就是普通平行骨架
+	 */
+	waypointOffsets?: Record<string, GisViewCoordinate>
 }
 
 /**
@@ -1219,6 +1224,12 @@ export interface GisViewChannel {
 	id?: string | number
 	/** 通道名：仅作业务标识，组件不渲染 */
 	name?: string
+	/**
+	 * 是否显示这条通道：false 时整条通道与成员回线一起隐藏，数据、分组、拐点与编辑状态都保留，
+	 * 改回 true（或 `showFeatures('channel', ref)`）立即恢复；缺省 true。
+	 * 端点节点 `visible: false` 时通道也会整条隐藏，节点恢复后自动回来
+	 */
+	visible?: boolean
 	/** 通道内的线路 id，顺序即回线顺序（沿骨架左法线方向） */
 	lineIds: Array<string | number>
 	/**
@@ -1300,6 +1311,8 @@ export interface GisViewChannelInfo {
 	to?: string | number
 	/** 两端是否都落在节点上：锚定的通道会跟着节点拖动走 */
 	anchored: boolean
+	/** 分组刚性拐点偏移：与 groups[].waypointOffsets 同一份口径，没有偏移时是空对象 */
+	waypointOffsets: Record<string, [number, number]>
 	/** 整条通道相邻回线的中心间距（世界单位），单回线通道为 0；分组之后各组共用这一套间距 */
 	spacing: number
 }
@@ -1352,6 +1365,8 @@ export interface GisViewChannelGroupInfo {
 	skeleton: Array<[number, number]>
 	/** 骨架换算回声明用的中间拐点（两端锚定时不含首尾节点），可以直接写回 groups[].path */
 	path: Array<[number, number]>
+	/** 刚性拐点偏移：与 groups[].waypointOffsets 同一份口径，可以直接写回声明 */
+	waypointOffsets: Record<string, [number, number]>
 }
 
 /** getChannelGroupWaypoints 里的一条成员回线：偏移之后的折线与拐点（与图上画的一致） */
@@ -1386,6 +1401,8 @@ export interface GisViewChannelGroupWaypoints {
 	skeleton: Array<[number, number]>
 	/** 整组共用的中间拐点：给后端的 channel.group.path 就是这一份 */
 	path: Array<[number, number]>
+	/** 刚性拐点偏移：需要把非平行拖动结果一起回传时写回 groups[].waypointOffsets */
+	waypointOffsets: Record<string, [number, number]>
 	/** 组里每条回线偏移后的折线与拐点（同组同步之后「其他线路的拐点」读它） */
 	lines: GisViewChannelGroupLineWaypoints[]
 }
@@ -1826,6 +1843,102 @@ export interface GisViewMovedPoint {
 	item: GisViewPoint
 }
 
+/** 可整批隐藏 / 显示的要素类型 */
+export type GisViewVisibilityKind = 'point' | 'line' | 'channel'
+
+/** 隐藏 / 显示的引用：单个 id / 下标 / `{ id }` / `{ index }`，一批，或当前选中集 `'selection'` */
+export type GisViewVisibilityRefs = GisViewFeatureRef | 'selection' | Array<GisViewFeatureRef | 'selection'>
+
+/** 隐藏 / 显示时没认出来的引用 */
+export interface GisViewVisibilitySkip {
+	ref: unknown
+	reason: string
+}
+
+/** setFeatureVisible / hideFeatures / showFeatures 的返回：indexes 与 items 按数据顺序一一对应 */
+export interface GisViewSetVisibilityOutcome {
+	ok: boolean
+	reason: string | null
+	kind: GisViewVisibilityKind
+	visible: boolean
+	/** 实际改到的下标（去重、按传入顺序） */
+	indexes: number[]
+	/** 对应的 id；要素没 id 时退回下标 */
+	ids: Array<string | number>
+	items: Array<GisViewPoint | GisViewLine | GisViewChannel>
+	skipped: GisViewVisibilitySkip[]
+}
+
+/** 通道变化里的一组：成员与骨架都是当次读数的可比较快照 */
+export interface GisViewChangedChannelGroup {
+	id: string | number | null
+	lineIds: string[]
+	path: GisViewCoordinate[] | null
+}
+
+/** 通道变化原因 */
+export type GisViewChangedChannelReason = 'groups' | 'members' | 'waypoints' | 'endpoints' | 'visibility' | 'fields'
+
+/** getChangedChannels 的查询选项 */
+export interface GisViewChangedChannelOptions {
+	/** 只返回带这些原因的变化（空数组 = 不返回任何变化）；不传 = 全部原因 */
+	reasons?: GisViewChangedChannelReason[]
+	/**
+	 * 忽略分组结构的新增 / 删除 / 重排：不报 `groups`，也不把整组增删算成拐点变化；
+	 * 基准与当前都存在、且分组 `path` 真变过的，仍报 `waypoints`
+	 */
+	ignoreGroups?: boolean
+}
+
+/** getChangedChannels 的一项：相对上次通道对账发生了哪些变化 */
+export interface GisViewChangedChannel {
+	index: number
+	id: string | number | null
+	item: GisViewChannel
+	/** 当前分组读数（没写 groups 的通道按「一整组」折算） */
+	groups: GisViewChangedChannelGroup[]
+	groupsChanged: boolean
+	waypointsChanged: boolean
+	membersChanged: boolean
+	endpointsChanged: boolean
+	visibilityChanged: boolean
+	fieldsChanged: boolean
+	/** 除 id / lineIds / groups / path / from / to / visible 之外变过的字段名 */
+	fields: string[]
+	/** 变化原因：groups / members / waypoints / endpoints / visibility / fields */
+	reasons: GisViewChangedChannelReason[]
+}
+
+/** 线路变化原因：path（path / start / end）、端点、可见性、其余字段 */
+export type GisViewChangedLineReason = 'path' | 'endpoints' | 'visibility' | 'fields'
+
+/** getChangedLines 的查询选项 */
+export interface GisViewChangedLineOptions {
+	/** 只返回带这些原因的变化（空数组 = 不返回任何变化）；不传 = 全部原因 */
+	reasons?: GisViewChangedLineReason[]
+}
+
+/** getChangedLines 的一项：相对上次线路对账发生了哪些变化 */
+export interface GisViewChangedLine {
+	index: number
+	id: string | number | null
+	item: GisViewLine
+	/** 当前声明的 path（没有 path 时为 null）；线条几何还会看 start / end */
+	path: GisViewCoordinate[] | null
+	start: GisViewCoordinate | null
+	end: GisViewCoordinate | null
+	from: string | number | null
+	to: string | number | null
+	visible: boolean
+	pathChanged: boolean
+	endpointsChanged: boolean
+	visibilityChanged: boolean
+	fieldsChanged: boolean
+	/** 除 id / start / end / path / from / to / visible 之外变过的字段名 */
+	fields: string[]
+	reasons: GisViewChangedLineReason[]
+}
+
 /**
  * addChannels 的返回：results 与传入顺序一一对应（失败的条目也在里面，按各自的 reason 读），
  * count 是成功落地的条数；lineIds / channelIds 只列成功那几条的（顺序与 results 里成功的一致）。
@@ -3269,6 +3382,71 @@ export interface GisViewMergeSelectedOptions {
 	originalEvent?: Event | null
 }
 
+/**
+ * splitPoint 的一份节点定义：节点字段可直接写在顶层（id / x / y / name / style…），也可以放进 item；
+ * lines / channels / channelFrom / channelTo 是会从节点字段里摘出来的分配指令，不会写进节点数据。
+ */
+export interface GisViewSplitPointPart extends Partial<GisViewPoint> {
+	/** 新节点的字段（与顶层的节点字段合并，顶层优先） */
+	item?: Partial<GisViewPoint>
+	/** 分到这一份的线路（id / 下标 / { id } / { index }）：不写时连在原节点上的线路跟第一份 */
+	lines?: GisViewFeatureRef | GisViewFeatureRef[]
+	/** 两端都分到这一份的受影响通道；把同一条通道写进两份时按 from / to 各去一份 */
+	channels?: GisViewFeatureRef | GisViewFeatureRef[]
+	/** 只把通道的 from 端分到这一份 */
+	channelFrom?: GisViewFeatureRef | GisViewFeatureRef[]
+	/** 只把通道的 to 端分到这一份 */
+	channelTo?: GisViewFeatureRef | GisViewFeatureRef[]
+}
+
+/** splitPoint 的选项 */
+export interface GisViewSplitPointOptions {
+	/** 第一份是否沿用来源节点的 id（缺省 true）；false 时也给第一份生成 `${来源 id}-split-1` */
+	keepSourceId?: boolean
+	/** 这一步历史的标签，缺省「拆分节点」 */
+	label?: string
+}
+
+/** 拆分时没认出来的线路 / 通道引用 */
+export interface GisViewSplitPointSkip {
+	ref: unknown
+	reason: string
+}
+
+/**
+ * 一次拆分的完整变更集：removedPoint 是拆分前的来源节点，points 是拆分后的全部节点，
+ * lines / channels 是仍存在且受影响的最终数据，removedLines / removedChannels 是拆分前被删掉的数据。
+ * 可直接作为后端事务的输入。
+ */
+export interface GisViewSplitPointChangeSet {
+	removedPoint: GisViewPoint
+	points: GisViewPoint[]
+	lines: GisViewLine[]
+	removedLines: GisViewLine[]
+	channels: GisViewChannel[]
+	removedChannels: GisViewChannel[]
+}
+
+/** splitPoint 的返回：ok 为 false 时 reason 说明原因，其余数组为空、changes 为 null */
+export interface GisViewSplitPointOutcome {
+	ok: boolean
+	reason: string | null
+	source: { index: number; id: string | number | null; item: GisViewPoint } | null
+	/** 拆分后的节点，第一份在原下标，其余按 indexes 追加 */
+	items: GisViewPoint[]
+	indexes: number[]
+	pointIds: Array<string | number>
+	linesChanged: number
+	removedLines: number
+	removedLineIds: Array<string | number>
+	removedLineIndexes: number[]
+	channelsChanged: number
+	removedChannels: number
+	removedChannelIds: Array<string | number>
+	skipped: { lines: GisViewSplitPointSkip[]; channels: GisViewSplitPointSkip[] }
+	changes: GisViewSplitPointChangeSet | null
+}
+
 /** 定位一个节点：id、数组下标，或带 id / index 的对象（`{ id: 'a' }` / `{ index: 2 }`） */
 export type GisViewPointRef = string | number | { id: string | number } | { index: number }
 
@@ -3347,6 +3525,7 @@ export type GisViewDataChangeType =
 	| 'copyPoint'
 	| 'copyPoints'
 	| 'mergePoints'
+	| 'splitPoint'
 	| 'waypoint'
 	| 'addChannel'
 	| 'addChannels'
@@ -3706,6 +3885,8 @@ export interface GisViewItemLabel {
 	style?: Record<string, string>
 	/** 线路标签是否与线路方向平行（点的标签忽略这一项） */
 	parallel?: boolean
+	/** 这一条是否参与避让：false 时即使全局开启 labelOptimize / avoidOverlap 也始终按候选落点画出；缺省跟随全局 */
+	avoidOverlap?: boolean
 	/**
 	 * 这一条撞上别的标签之后怎么避让：`shift`（默认）主动换锚点 / 沿线挪，`hide` 直接不显示。
 	 * 只在顶层 `labelOptimize: true` 且这条的 `avoidOverlap` 不为 false 时生效；只和底图区域文字重叠时仍按软冲突照画。
@@ -3715,6 +3896,10 @@ export interface GisViewItemLabel {
 	visibility?: GisViewLabelVisibility
 	/** 整条不画（等于 visibility: 'hidden'）；false 表示撤回隐藏覆盖 */
 	hidden?: boolean
+	/** 这一条标签能不能拖：逐条覆盖 options.label / lineLabel 里的同名开关 */
+	draggable?: boolean
+	/** 这一条标签能不能点选：逐条覆盖 options.label / lineLabel 里的同名开关 */
+	editable?: boolean
 	/** 这条标签是运行时加的（addLabel），导出时带上它便于整份回显 */
 	added?: boolean
 	className?: string
@@ -3954,8 +4139,10 @@ export interface GisViewLabelPatch {
 export interface GisViewLabelInfo {
 	/** 这一条要素上的哪一条标签 */
 	id: string
-	/** 当下画出来的文本（DOM 里的那一份：模板 / 函数算完之后的结果） */
+	/** 当下画出来的内容（DOM 里的那一份：模板 / 函数算完之后的结果；html 时保留标记本身） */
 	content: string
+	/** 这一条当下是否按 HTML 渲染（html: true 才有子节点；false 永远是纯文本） */
+	html: boolean
 	/** 当下生效的锚点（点八向 / 线沿线位置），算不出来时是 null */
 	position: GisViewLabelPosition | GisViewLineLabelPosition | null
 	className: string | null
@@ -4120,12 +4307,12 @@ export interface GisViewLabelListItem {
 	id: string
 	/** 这一条是哪来的：'config' 配置里定义的 / 'data' 数据里写的 / 'runtime' 运行时加的（与事件载荷里的 GisViewLabelInfo.source 同一口径） */
 	source: 'config' | 'data' | 'runtime'
-	/** 这一条声明里的内容（模板 / 函数原样给出），没写是 null */
+	/** 这一条当下生效的内容（运行时覆盖优先，模板 / 函数原样给出），没写是 null */
 	content: GisViewLabelContent | GisViewLineLabelContent | null
 	html: boolean
 	className: string | null
 	position: GisViewLabelPosition | GisViewLineLabelPosition | null
-	/** 声明里的偏移（像素），没写是 [0, 0] */
+	/** 当下生效的偏移（像素）：运行时拖出来的优先，否则用声明里的；都没有是 [0, 0] */
 	offset: [number, number]
 	style: Record<string, string> | null
 	/** 线路标签：这一条是否与线路平行；节点标签恒为 false */
@@ -5020,6 +5207,13 @@ export type GisViewChannelSelectMode =
 	/** 整条通道（所有分组的回线）一起选 */
 	| 'channel'
 
+/** 分组拐点拖动模式：普通线路永远只动自己，这里只影响通道里的一组回线 */
+export type GisViewChannelWaypointDragMode =
+	/** 缺省：改共用骨架，组内回线按平行偏移重算；拐角处相邻顶点可能随 miter 微调 */
+	| 'parallel'
+	/** 只把同组同一 pathIndex 的拐点按相同世界增量平移，其他拐点（含相邻顶点）保持不动 */
+	| 'vertex'
+
 /**
  * 框选 / Ctrl 多选允许收哪几类要素：节点、独立线路、通道回线。
  * 通道回线只归 channel 这一档管；通道之外的普通线路归 line，两者可以任意组合。
@@ -5786,6 +5980,14 @@ export interface GisViewOptions {
 	 * 只管「画不画、画哪几条」：`visibility` / `when` / 拖拽 / 编辑 / 样式与动画都不受影响
 	 */
 	labelOptimize?: boolean
+	/**
+	 * 纯文本标签的渲染方式，缺省 `auto`：
+	 * - `auto`：强制显示档下，视口里的纯文本标签达到 1024 条时自动改画到单张 Canvas；
+	 *   需要 DOM 的标签（`html: true`、函数返回元素、可拖拽 / 可编辑）仍逐条建节点。
+	 * - `dom`：始终逐条建 `.gis-view__label`，保持旧行为。
+	 * 画布档不改变标签内容、锚点与显隐，只减少高密度场景的 DOM 数量。
+	 */
+	labelRender?: 'auto' | 'dom'
 	/**
 	 * 标签的运行时状态（`getLabelStates()` 的那一份：拖过的偏移、改过的内容与样式、运行时加的标签、隐藏覆盖）：
 	 * 创建 / `updateOptions` 时喂回来就回显，与 `setLabelStates(states)` 同一条路。
@@ -5928,6 +6130,12 @@ export interface GisViewOptions {
 	 * Ctrl + 点击在 group / channel 下是整批取反，切换走 updateOptions 不用重排场景
 	 */
 	channelSelectMode?: GisViewChannelSelectMode
+	/**
+	 * 分组拐点拖动模式：'parallel'（缺省）沿用共用骨架 + 平行偏移，拐角相邻顶点可能随 miter 微调；
+	 * 'vertex' 只移动当前分组同一 pathIndex 的拐点（组内所有回线按相同世界增量），其他拐点保持不动。
+	 * 普通线路不受影响；切换走 updateOptions({ channelWaypointDragMode })，下一次拖动生效
+	 */
+	channelWaypointDragMode?: GisViewChannelWaypointDragMode
 
 	/**
 	 * 快捷键：框选、多选、加点、复制、粘贴、取消、删除、适应视图都可以在这里改
@@ -7188,6 +7396,14 @@ export interface GisViewInstance {
 	 * 并不了返回 ok: false 并另发一条 `phase: 'merge', ok: false` 的事件
 	 */
 	mergePoints(source: GisViewPointRef, target: GisViewPointRef, options?: { originalEvent?: Event | null; item?: GisViewPoint }): GisViewMergeOutcome
+	/**
+	 * 把一个节点拆成多份（mergePoints 的逆操作）：第一份复用原下标与 id，其余追加到 points 末尾。
+	 * 每份可直接写节点字段或放进 item；lines 分配线路（不写时连在原节点上的线路跟第一份），
+	 * channels / channelFrom / channelTo 分配受影响通道的端点。没显式分配的通道跟随它第一条被分配过的成员线路。
+	 * 拆分后自环 / 零长度线路与两端相同的通道删掉；整次调用只记一条历史、只发一条 `splitPoint` 数据变更。
+	 * 返回 `{ ok, items, indexes, pointIds, linesChanged, removedLines, channelsChanged, removedChannels, changes, skipped }`
+	 */
+	splitPoint(source: GisViewPointRef, parts: GisViewSplitPointPart[], options?: GisViewSplitPointOptions): GisViewSplitPointOutcome
 	/**
 	 * 框选 / 多选之后一步把选中的节点并到一个目标上（接口调用）：不指定 target 就自动挑「绑定线路最多」的那一个
 	 * （一样多取画得大的、再一样取下标小的）；来源默认是除目标之外的选中节点，也可以直接用 options.sources 给定，
@@ -7518,6 +7734,40 @@ export interface GisViewInstance {
 	 * （写法与 removePoints 一致：id / 下标 / { id } / { index }）；空数组无操作，返回实例本身。
 	 */
 	clearMovedPoints(refs?: GisViewFeatureRef | GisViewFeatureRef[]): GisViewInstance
+	/**
+	 * 相对上一次对账，成员 / 分组 / 拐点 / 端点 / 可见性或其余声明字段变过的通道。
+	 * 新加通道只补账不报变化，删掉的通道从账本清掉；整份换通道数据（updateData / updateOptions / applyChannels）
+	 * 之后以新数据为基准。返回项带 groups / 各 changed 标记 / fields / reasons。
+	 * options.reasons 只返回指定原因；options.ignoreGroups 忽略分组增删，只比较已有分组的拐点。
+	 */
+	getChangedChannels(options?: GisViewChangedChannelOptions): GisViewChangedChannel[]
+	/**
+	 * 通道变化对账：不传 / 传 null 全部对账，传一个或一批引用只对账这些（写法与 removePoints 一致）；
+	 * 返回实例本身，认不出来的引用跳过并报一句提醒。
+	 */
+	clearChangedChannels(refs?: GisViewFeatureRef | GisViewFeatureRef[]): GisViewInstance
+	/**
+	 * 相对上一次对账，path / start / end、from / to、可见性或其余声明字段变过的线路。
+	 * 新加线路只补账不报变化，删掉的线路从账本同步清掉；整份换线路后以新数据为基准。
+	 * 通道里的回线只比较自己的声明；通道骨架变化由 getChangedChannels 负责。
+	 * options.reasons 只返回指定原因。
+	 */
+	getChangedLines(options?: GisViewChangedLineOptions): GisViewChangedLine[]
+	/**
+	 * 线路变化对账：不传 / 传 null 全部对账，传一个或一批引用只对账这些（写法与 removePoints 一致）；
+	 * 返回实例本身，认不出来的引用跳过并报一句提醒。
+	 */
+	clearChangedLines(refs?: GisViewFeatureRef | GisViewFeatureRef[]): GisViewInstance
+	/**
+	 * 统一隐藏 / 显示节点、线路或通道：只改数据里的 visible，不删要素，分组 / 拐点 / 编辑状态都保留。
+	 * refs 收单个或一批（id / 下标 / { id } / { index }），也认 'selection'；整次调用一条历史、一条 batch 数据变更。
+	 * 返回 `{ ok, kind, visible, indexes, ids, items, skipped }`
+	 */
+	setFeatureVisible(kind: GisViewVisibilityKind, refs: GisViewVisibilityRefs, visible: boolean): GisViewSetVisibilityOutcome
+	/** `setFeatureVisible(kind, refs, false)` 的快捷写法 */
+	hideFeatures(kind: GisViewVisibilityKind, refs: GisViewVisibilityRefs): GisViewSetVisibilityOutcome
+	/** `setFeatureVisible(kind, refs, true)` 的快捷写法（隐藏后原样恢复） */
+	showFeatures(kind: GisViewVisibilityKind, refs: GisViewVisibilityRefs): GisViewSetVisibilityOutcome
 	/**
 	 * 某个下标的节点当前在不在图上：被筛选 / visible: false 隐藏掉的不算，
 	 * 初始化发散渲染还没排到的那一部分也不算。
@@ -7776,6 +8026,8 @@ export interface GisViewEngineOptions {
 	 * 切换走 setOptions / updateOptions 不用重排场景
 	 */
 	channelSelectMode?: GisViewChannelSelectMode
+	/** 分组拐点拖动模式：'parallel'（缺省）/ 'vertex'，见 GisViewOptions.channelWaypointDragMode */
+	channelWaypointDragMode?: GisViewChannelWaypointDragMode
 
 	/** 快捷键：动作 -> 写法（框选、多选、加点、复制、粘贴、取消、删除、适应视图），没写的沿用默认值 */
 	shortcuts?: GisViewShortcuts