查看器

<xh-flow-viewer> 在业务页面里显示流程与运行状态，类在 @xihan-flow/runtime 里导出为 XhFlowViewer，调用 defineFlowViewer() 注册。用法见查看器。

元素 xh-flow-viewer

属性

属性	attribute	类型	说明
schema	—	FlowDocument | undefined	要显示的流程定义；从无到有时重新自动适配。
extensions	—	readonly FlowRuntimeExtension[] | undefined	扩展：节点类型、节点渲染等都从这里来，内置扩展自动排在最前。赋值时当场合并查重，冲突抛 DesignerExtensionError、属性保持原值；同一个扩展对象换了引用当作卸下再装上，宿主要保持引用稳定。
statuses	—	Readonly<Record<string, FlowNodeStatus | null>> | undefined	节点 id → 运行状态；null 表示没有状态。
highlighted	—	readonly string[] | undefined	高亮的节点 id。
router	—	FlowEdgeRouter | undefined	连线路由器，缺省为直角路由。
translations	—	Partial<FlowViewerTranslations> | undefined	元素自己的文案，压在全局配置之上。

方法

方法	说明
export(format: FlowImageFormat, options?: FlowImageExportOptions): Promise<Blob>	把画面上的流程图导出成图片：svg 是能单独打开的 SVG 文件，png 按倍率栅格化；颜色与字体取画面此刻的样式，节点、图标、连线与标签都画进去。选项见 FlowImageExportOptions。流程图是空的、format 不是这两种时以 RangeError 拒绝。
getViewport(): Viewport	当前视口。
setViewport(viewport: Viewport): void	设置视口；此后尺寸变化不再自动适配。
zoomToFit(): void	缩放并平移到让整张图落在视口中央，小图不放大到 100% 以上；此后尺寸变化时重新适配，直到设置视口或在画布上按下指针。
zoomIn(): void	以视口中心放大一档。
zoomOut(): void	以视口中心缩小一档。
zoomToActual(): void	缩放到 100% 并把整张图居中。
scrollToNode(id: string): void	把节点居中显示。
revealNode(id: string): void	节点没整个落在视口内时把它居中，已在视口内则不动。
setNodeStatus(id: string, status: FlowNodeStatus | null): void	设置单个节点的运行状态，传 null 清除。
setNodeStatuses(statuses: Readonly<Record<string, FlowNodeStatus | null>>): void	批量设置节点运行状态，未列出的节点保持不变。
highlightNodes(ids: readonly string[]): void	高亮一组节点，其余节点取消高亮。
clearHighlights(): void	清除全部高亮。

事件

事件都是冒泡的 CustomEvent。

事件	detail	说明
node-click	{ id: string }	点了节点；拖动平移之后松手不算点击。
edge-click	{ id: string }	点了连线或连线标签。
blank-click	Record<string, never>	点了画布空白处。
node-contextmenu	{ id: string, x: number, y: number }	在节点上打开右键菜单；可以取消，取消后浏览器的右键菜单也不出现。
edge-contextmenu	{ id: string, x: number, y: number }	在连线上打开右键菜单；可以取消。
blank-contextmenu	{ x: number, y: number }	在画布空白处打开右键菜单；可以取消。
viewport-change	{ viewport: Viewport }	视口变了：缩放、平移、适配与 setViewport 都会派发。

注册

defineFlowViewer()

declare function defineFlowViewer(): void

注册 <xh-flow-viewer> 与内置节点渲染用到的 <xh-icon>；重复调用不报错。

节点渲染

FlowNodeRenderer

type FlowNodeRenderer = (container: HTMLElement, context: FlowNodeRenderContext) => void

自定义节点内容：每次绘制都会调用，把内容写进 container；不给时用 defaultNodeRenderer。

FlowNodeRenderContext

自定义节点内容时拿到的上下文。

属性	类型	说明
node	FlowNode	要画的节点。
nodeType	FlowNodeType | undefined	节点类型；类型没有登记时为 undefined。
label	string	要显示的文字：节点的 label，没有时取节点类型的名称，再没有取节点 id。
status	FlowNodeStatus | undefined	节点此刻的运行状态；没有状态时为 undefined。
highlighted	boolean	节点是否高亮。

defaultNodeRenderer()

declare function defaultNodeRenderer(container: HTMLElement, { nodeType, label }: FlowNodeRenderContext): void

内置的节点内容：节点类型给了 icon 时图标（data-part="node-icon"）在前、文字（data-part="node-label"）在后，没给时节点里只有文字。没有登记渲染的节点类型用它，自定义的渲染也可以调它画出同样的内容。重画时复用已有的图标与文字节点。图标是 <xh-icon>，defineFlowViewer() 与 defineFlowDesigner() 会注册它。

FlowRuntimeExtension

流程运行时层的扩展：在 core 层之上加节点内容的渲染，查看器与设计器都读它。

继承 FlowCoreExtension。

属性	类型	说明
nodeRenderers?	Readonly<Record<string, FlowNodeRenderer>>	节点内容的渲染，键是节点类型；没给渲染的类型用 defaultNodeRenderer 画图标与文字。

createFlowRuntimeModel()

declare function createFlowRuntimeModel(extensions?: readonly FlowRuntimeExtension[]): FlowRuntimeModel

合出运行时用的流程模型；同一节点类型在两个扩展里都给了渲染时抛 DesignerExtensionError。同一个数组只合一次。

导出图片

FlowImageFormat

type FlowImageFormat = 'svg' | 'png'

导出图片的格式。

FlowImageExportOptions

导出图片的选项。

属性	类型	说明
scale?	number	倍率，只对 PNG 有效：PNG 的像素宽高是图的宽高乘它，缺省 1；超过浏览器画布的上限时自动降倍率，图按比例缩小。
background?	string	底色，任何 CSS 颜色；缺省取画布此刻的底色（画布透明时往外找到第一层不透明的），写 'transparent' 不铺。
padding?	number	流程图四周的留白，缺省 24。

exportFlowImage()

declare function exportFlowImage(source: FlowImageSource, format: FlowImageFormat, options?: FlowImageExportOptions): Promise<Blob>

导出成图片：SVG 是 flowImageSvg 的文本，PNG 在它上面按倍率栅格化（底色已画进 SVG），超过画布上限时按比例缩小。PNG 里的文字用本机的系统字体画，不加载网页字体。

flowImageSvg()

declare function flowImageSvg(source: FlowImageSource, options?: FlowImageExportOptions): SVGSVGElement

把画面上的流程图画成一份能单独打开的 SVG：连线层经 standaloneSvg 克隆（只供命中的透明粗线不要，克隆根上的表现属性挪到放连线的组上），节点按计算样式画成框、图标与文字，连线标签画成底框与文字；四周留白，按选项铺底色。颜色写成 sRGB 的 #rrggbb，透明度写进 fill-opacity / stroke-opacity；画布的字体写在根上，文字只写与它不同的那几项。坐标是世界坐标，1 个单位即 1 像素。流程图是空的时抛 RangeError。

FlowImageSource

画出图片要读的活元素：场景、画布上的连线层、节点与连线标签的元素，以及视口的缩放。

属性	类型	说明
scene	FlowScene
canvas	Element	画布元素：缺省底色从它开始找。
edges	SVGSVGElement	连线所在的 SVG 层，里面的坐标是世界坐标。
zoom	number	视口的缩放：元素在屏幕上的尺寸除以它即世界尺寸。

方法	说明
node(id: string): HTMLElement | null	节点 id → 画面上的节点元素。
label(id: string): HTMLElement | null	连线 id → 画面上的连线标签元素。

连线路由

createOrthogonalRouter()

declare function createOrthogonalRouter(options?: OrthogonalRouterOptions): FlowEdgeRouter

创建直角路由器；找不到绕开全部节点的通路时，返回不看障碍物的直角折线。

OrthogonalRouterOptions

属性	类型	说明
margin?	number	与节点保持的距离，也是从端口引出的长度，缺省 16。
bendCost?	number	每个拐弯折合的长度，缺省 margin 的两倍。

文案

FlowViewerTranslations

查看器的文案。

属性	类型	说明
label	string	视口区域的可访问名。

语言包

locale/de-DE

名称	种类	说明
flowDeDE	常量	流程的德语文案：查看器、设计器与 designer-shell 零件。

locale/en-US

名称	种类	说明
flowEnUS	常量	流程的英文文案：查看器、设计器与 designer-shell 零件。

locale/es-ES

名称	种类	说明
flowEsES	常量	流程的西班牙语文案：查看器、设计器与 designer-shell 零件。

locale/fr-FR

名称	种类	说明
flowFrFR	常量	流程的法语文案：查看器、设计器与 designer-shell 零件。

locale/ja-JP

名称	种类	说明
flowJaJP	常量	流程的日语文案：查看器、设计器与 designer-shell 零件。

locale/ko-KR

名称	种类	说明
flowKoKR	常量	流程的韩语文案：查看器、设计器与 designer-shell 零件。

locale/pt-BR

名称	种类	说明
flowPtBR	常量	流程的巴西葡萄牙语文案：查看器、设计器与 designer-shell 零件。

locale/ru-RU

名称	种类	说明
flowRuRU	常量	流程的俄语文案：查看器、设计器与 designer-shell 零件。

locale/types

名称	种类	说明
FlowLocale	接口	流程一种语言的全部文案。

locale/zh-CN

名称	种类	说明
flowZhCN	常量	流程的简体中文文案：查看器、设计器与 designer-shell 零件。

locale/zh-TW

名称	种类	说明
flowZhTW	常量	流程的繁体中文文案：查看器、设计器与 designer-shell 零件。

全部导出

designer-locale

名称	种类	说明
DEFAULT_FLOW_DESIGNER_TRANSLATIONS	常量	设计器不配语言包时的缺省文案。
FLOW_DESIGNER_EN_US	常量	设计器的英文文案，也是不配语言包时的缺省。
FlowBuiltinPropertyKey	类型	设计器内建的属性路径，formatJsonPath 的写法。
FlowDesignerLocale	接口	一种语言的设计器文案：问题说明与内建属性名写成表，其余与 FlowDesignerTranslations 相同。
flowDesignerTranslations	函数	把一种语言的设计器文案换成设计器读的形状：问题按码查表，表里没有的（扩展的问题码）显示问题码。
FlowIssueMessage	类型	一条问题说明：text 取参数的文字，type 取参数里那个节点类型的显示名。

extensions

名称	种类	说明
createFlowRuntimeModel	函数	合出运行时用的流程模型；同一节点类型在两个扩展里都给了渲染时抛 DesignerExtensionError。
FlowRuntimeExtension	接口	流程运行时层的扩展：在 core 层之上加节点内容的渲染，查看器与设计器都读它。
FlowRuntimeModel	接口	运行时用的流程模型：core 的模型加上各节点类型的渲染。

flow-viewer

名称	种类	说明
defineFlowViewer	函数	注册 <xh-flow-viewer> 与内置节点渲染用到的 <xh-icon>；重复调用不报错。
FLOW_VIEWER_TAG	常量	查看器的标签名。
FlowNodeRenderContext	接口	自定义节点内容时拿到的上下文。
FlowNodeRenderer	类型	自定义节点内容：每次绘制都会调用，把内容写进 container；不给时用 defaultNodeRenderer。
FlowViewerEventMap	接口	查看器派发的事件；x / y 为浏览器视口坐标。
XhFlowViewer	类	流程查看器 <xh-flow-viewer>：只读显示流程、运行状态与高亮。

image-export

名称	种类	说明
exportFlowImage	函数	导出成图片：SVG 是 flowImageSvg 的文本，PNG 在它上面按倍率栅格化（底色已画进 SVG），超过画布上限时按比例缩小。
FlowImageExportOptions	接口	导出图片的选项。
FlowImageFormat	类型	导出图片的格式。
FlowImageSource	接口	画出图片要读的活元素：场景、画布上的连线层、节点与连线标签的元素，以及视口的缩放。
flowImageSvg	函数	把画面上的流程图画成一份能单独打开的 SVG：连线层经 standaloneSvg 克隆（只供命中的透明粗线不要，克隆根上的表现属性挪到放连线的组上），节点按计算样式画成框、图标与文字，连线标签画成底框与文字；四周留白，按选项铺底色。

node-renderer

名称	种类	说明
defaultNodeRenderer	函数	内置的节点内容：节点类型给了 icon 时图标（data-part="node-icon"）在前、文字（data-part="node-label"）在后，没给时节点里只有文字。

router

名称	种类	说明
createOrthogonalRouter	函数	创建直角路由器；找不到绕开全部节点的通路时，返回不看障碍物的直角折线。
OrthogonalRouterOptions	接口

scene

名称	种类	说明
buildScene	函数	算出整张图的场景。
FlowNodeStatus	类型	节点运行状态；内置样式覆盖 running / completed / faulted / waiting / canceled / compensated，其余取值由使用方自行着色。
FlowScene	接口
FlowSceneEdge	接口
FlowSceneNode	接口
FlowSceneOptions	接口

translations

名称	种类	说明
DEFAULT_FLOW_VIEWER_TRANSLATIONS	常量	查看器的英文文案，也是不配语言包时的缺省。
FlowDesignerTranslations	接口	设计器的文案。
FlowHistoryTranslations	接口	撤销历史里一步的说明：单个节点写「种类 名称」（见 node，没有名称时名称是 id），几个节点写个数。
FlowIssueNames	接口	拼问题说明时用到的名称。
FlowOutlineTranslations	接口	流程结构面板的几处文案。
FlowStartVariableColumn	类型	启动变量表的列：变量名、必填、缺省值、说明。
FlowTourStepKey	类型	新手引导里流程自己的几步：连线、自动布局与导出图片。
FlowTourStepTranslations	接口	新手引导一步的文案。
FlowViewerTranslations	接口	查看器的文案。