尧图网页设计 
前端UI组件【免费下载链接】golden-layoutA multi window layout manager for webapps项目地址https://gitcode.com/gh_mirrors/go/golden-layout点击查看免费下载Golden Layout 是一个基于 JavaScript/TypeScript 的网页布局管理器让你可以在一个页面中摆放多个组件并通过拖拽自由重排、弹出独立窗口。本文以仓库 docs/index.md 为主体骨架结合 src/ts 源码与 package.json 中的真实脚本系统讲解它的功能特性、安装构建、核心数据结构、四种组件绑定方式、尺寸与自适应机制以及从 v1 迁移到 v2 的关键 API 变更。读完本文你将掌握 Golden Layout 的完整接入流程与底层实现原理能够在自己的 Web 应用中直接落地一套可拖拽、可持久化的多窗口布局方案。功能概览Golden Layout 的核心能力在 docs/index.md 中总结为以下特性原生弹窗Popouts组件可以被“弹出”到独立的浏览器窗口与主布局分开查看触摸支持支持触屏设备上的拖拽操作框架支持为 Angular、Vue 等应用框架提供集成能力虚拟组件Virtual ComponentsGolden Layout 不直接操作组件 DOM而是通过事件通知应用自行完成组件的定位全面的 API加载/保存布局、聚焦组件、编程式增删组件等均有公开接口布局持久化布局结构可保存为 JSON 配置并在之后重新加载组件焦点与 HTML 元素焦点机制类似同一时刻只有一个组件拥有焦点完全可主题化通过 CSS/Less/SCSS 定制全部外观现代浏览器支持面向 Firefox、Chrome 等现代浏览器响应式设计开箱即用。从 package.json 的browserslist字段可以看到项目明确支持的浏览器范围是最新版 Chrome、最新版 Firefox、近两个大版本的 Edge/Safari/iOS Safari 以及 Firefox ESR。这意味着 Golden Layout 不再支持 IE 等旧浏览器这一点在布局自适应章节还会再次强调。安装与使用通过 npm 安装Golden Layout 已发布到 NPM可以执行npm i golden-layout不过官方在 docs/index.md 中明确提示NPM 上的模块包已长时间未更新当前推荐的方式是从源码构建。如果只是想快速体验或用于旧项目npm 包仍然可用但建议优先走下面的源码路线。从源码构建推荐克隆当前仓库后在仓库根目录打开终端依次执行npm install或npm ci推荐后者保证依赖版本与 lock 文件一致安装所需依赖npm run build生成发行版输出到dist子目录。根据 package.json 中build脚本的定义npm run build会依次完成删除旧的lib与dist目录clean脚本编译 TypeScript 源码build:cjs与build:module:api通过api-extractor生成聚合的 TypeScript 类型声明文件index.d.ts与golden-layout-untrimmed.d.ts生成 source map将样式文件复制到dist目录build:styles。构建完成后将dist/css的内容递归复制到你的应用可读取的位置即可。需要注意lib子目录只存放编译器生成的 TypeScript 声明文件一般可以忽略它仅用于构建过程中生成聚合声明文件。构建并运行演示应用apitest仓库内置了一个apitest演示应用用于直观查看和调试库的功能。构建并启动开发服务器npm run apitest:build # 仅构建 npm run apitest:serve # 构建并启动开发服务器启动后在浏览器访问http://localhost:3000/即可查看。演示应用的源码位于 apitest 目录其中 predefined-layouts.ts、text-component.ts、event-component.ts 等文件覆盖了预定义布局、普通组件、事件广播等典型用法是学习 API 的最好范本。构建单文件 bundle如果不希望引入完整工具链可以直接使用单文件 bundle。执行npm run build:bundles构建产物位于dist/bundle/。注意 bundle 默认不构建也不包含在 NPM 包中。如果使用 ES Module推荐将dist/bundle/esm/golden-layout.min.js调试时用golden-layout.js复制到项目中并命名为golden-layout.js然后即可按需导入import { GoldenLayout, LayoutConfig, ResolvedLayoutConfig, ItemConfig, ComponentItemConfig, ResolvedItemConfig, RowOrColumn, Tab } from ./golden-layout.js;main、module、typings字段见 package.json分别指向dist/cjs/index.js、dist/esm/index.js与dist/types/index.d.ts说明包同时提供 CommonJS 与 ESM 两种模块格式。调试 Golden Layout 库apitest应用的 webpack 配置会引入 Golden Layout 库的 source map因此可以在调试器中直接对库源码下断点、单步跟踪见 apitest/webpack.config.js。若要在其他应用中调试库源码可使用npm link进行软链接在 golden-layout 仓库根目录执行npm link在目标应用的根目录执行npm link golden-layout。此后目标应用会直接使用仓库dist目录中的发行版。如果修改了库代码需要运行npm run build重新生成dist目录。要解除链接在目标应用执行npm install即可。布局结构LayoutManager 与 ContentItem 树布局结构是理解 Golden Layout 一切行为的基石。官方文档 docs/structure/index.md 给出了完整的关系图核心要点如下LayoutManager (GoldenLayout 或 VirtualLayout) └── GroundItem隐藏永久存在 └── 根 ContentItem ├── ComponentItem根为组件单一元素不可操作 ├── Stack根为标签栈 │ └── ComponentItem × N └── RowOrColumn根为行列 ├── RowOrColumn × N └── Stack × N └── ComponentItem × N一个GoldenLayout或VirtualLayout对象是LayoutManager的派生类继承链为LayoutManager→VirtualLayout→GoldenLayout见 src/ts/layout-manager.ts 与 docs/binding-components/index.md。创建任一实例时LayoutManager随之创建同时会创建一个GroundItem内容项它伴随LayoutManager的整个生命周期。其它对象ComponentItem、RowOrColumn、Stack、BrowserPopout构成布局本身在布局被加载或修改时创建在布局关闭或重新加载时销毁。一套布局由两部分组成① 组成主布局的ContentItem树不含弹窗② 打开的BrowserPopout列表。主布局树的根节点可以是ComponentItem、Stack或RowOrColumn若根是ComponentItem布局只有一个组件用户无法对它进行任何布局操作——对用户而言 Golden Layout 就像不存在一样若根是RowOrColumn它作为树的根每个RowOrColumn有一个或多个子内容项子项可以是RowOrColumn或Stack树的叶子一定是Stack。GroundItem的存在是为了让布局中每一个内容项都有父节点包括根内容项。它最多只能有一个子内容项即根内容项当没有加载布局时GroundItem有 0 个子节点根内容项为undefined。GroundItem不对外暴露其方法全部通过LayoutManager访问。从源码结构看GroundItem、RowOrColumn、Stack、ComponentItem分别对应 src/ts/items/ground-item.ts、src/ts/items/row-or-column.ts、src/ts/items/stack.ts、src/ts/items/component-item.ts统一继承自 src/ts/items/content-item.ts。绑定组件的四种方式Golden Layout 绑定到组件之后会控制其位置、尺寸与可见性。文档 docs/binding-components/index.md 明确了四种绑定方式按复杂度从低到高排列绑定方式组件来源定位方式适用场景注册式嵌入Embedding via Registration注册的构造函数/工厂函数Golden Layout 自带 DOM 层级内经典用法快速简单事件式嵌入Embedding via EventsbindComponentEvent事件处理器Golden Layout 自带 DOM 层级内应用需要更多分配控制权注册式虚拟Virtual via Registration注册的构造函数/工厂函数内部按虚拟组件处理以最小改动获得虚拟组件优势事件式虚拟Virtual via EventsbindComponentEvent事件处理器由应用自行定位最大设计灵活性框架集成推荐注册式嵌入经典方式这是最经典的绑定方式把组件类型注册给 Golden Layout指定一个构造函数或回调函数每当布局需要新实例时调用它。调用时传入一个容器对象ComponentContainer其中包含 HTML 元素构造函数会把组件的顶层元素挂到容器的 HTML 元素下使组件成为 Golden Layout DOM 层级的一部分。布局重排时Golden Layout 会调整 DOM 以匹配新的层级——实质上是重挂reparent组件根元素的祖先节点。可用于注册的函数包括GoldenLayout.registerComponent()已弃用GoldenLayout.registerComponentConstructor()GoldenLayout.registerComponentFactoryFunction()GoldenLayout.registerComponentFunction()已弃用GoldenLayout.registerGetComponentConstructorCallback()从源码 src/ts/golden-layout.ts 可以看到registerComponent()会根据传入函数是否带有prototype属性自动判断它是构造函数还是工厂函数然后分派给registerComponentConstructor()或registerComponentFactoryFunction()。两者都接受第三个参数virtual默认false并且都会在组件类型已注册时抛出绑定错误。事件式嵌入为了给应用更多控制权可以改用事件绑定为VirtualLayout.bindComponentEvent事件分配处理器后每当需要新组件时该事件被触发。处理器需要创建或获取组件确保组件顶层 HTML 元素成为container.element的子节点以virtual: false的BindableComponent接口返回组件。当组件从布局中移除时需要在VirtualLayout.unbindComponentEvent事件或容器container的beforeComponentRelease事件两者皆可中清理移除顶层元素、释放资源。只要分配了处理器这两个事件在组件不再被需要时都会触发。事件式虚拟组件Virtual Components虚拟组件模式下Golden Layout完全不知道组件的存在不会把组件 HTML 元素纳入自己的 DOM 层级。每当组件的位置、尺寸或可见性需要改变时Golden Layout 触发事件由应用来更新组件——这类似于虚拟网格virtual grid的思路网格不包含真实内容而是在需要显示内容时触发事件由应用返回内容。虚拟组件的主要优势文档原文要点布局变化时组件及其祖先不会被重挂避免破坏 iframe、socket 等无需从组件中提取顶层 HTML 元素Angular、Vue 等自带组件树的应用无需打破自己的组件层级不再需要 teleport 组件的 HTML 元素应用的 DOM 层级更浅调试更简单。需要处理的事件与典型处理器模式如下代码示例来自 docs/binding-components/index.mdVirtualLayout.bindComponentEvent: (container, itemConfig) ComponentContainer.BindableComponent新组件需要绑定时触发。典型做法是用itemConfig创建/获取组件 → 取组件的顶层 HTML 元素 → 确保其为absolute定位 → 挂到 Golden Layout 根元素下 → 以container为键存入映射 → 注册virtualRectingRequiredEvent与virtualVisibilityChangeRequiredEvent→ 以virtual: true返回。private handleBindComponentEvent(container: ComponentContainer, itemConfig: ResolvedComponentItemConfig) { const componentTypeName ResolvedComponentItemConfig.resolveComponentTypeName(itemConfig); if (componentTypeName undefined) { throw new Error(handleBindComponentEvent: Undefined componentTypeName); } const component this.createVirtualComponent(container, componentTypeName, itemConfig.componentState); const componentRootElement component.rootHtmlElement; this._layoutElement.appendChild(componentRootElement); this._boundComponentMap.set(container, component); container.virtualRectingRequiredEvent (container, width, height) this.handleContainerVirtualRectingRequiredEvent(container, width, height); container.virtualVisibilityChangeRequiredEvent (container, visible) this.handleContainerVisibilityChangeRequiredEvent(container, visible); return { component, virtual: true }; }VirtualLayout.unbindComponentEvent: (container) void组件被移除时触发。典型做法是按container从映射中取出组件从根元素上移除其顶层元素并删除映射项。LayoutManager.beforeVirtualRectingEvent: () void布局变更后可能一次需要重排多个组件该事件在重排前触发一次常用于缓存 Golden Layout 根元素的getBoundingClientRect()结果private handleBeforeVirtualRectingEvent(count: number) { this._goldenLayoutBoundingClientRect this._layoutElement.getBoundingClientRect(); }ComponentContainer.virtualRectingRequiredEvent: (container, width, height) void组件位置/尺寸需要变化时触发。典型做法是以container为键取组件 → 用getBoundingClientRect()计算容器相对 Golden Layout 根元素的位置 → 更新顶层元素的left、top、width、height。ComponentContainer.virtualVisibilityChangeRequiredEvent: (container, visible) void可见性变化时触发典型做法是修改顶层元素的display属性。ComponentContainer.virtualZIndexChangeRequiredEvent: (container, logicalZIndex, defaultZIndex) voidz-index 变化时触发典型做法是把顶层元素的zIndex设置为defaultZIndex。apitest应用完整演示了虚拟组件的实现方式见 apitest/app.ts。使用虚拟组件时可以把 Golden Layout 理解为一个只计算位置而非实际摆放组件的引擎。它的初始搭建工作量比其他方式更大但灵活性更高例如任何 HTML 元素都可以作为组件的父元素不限于 Golden Layout 容器不同组件甚至可以有不同父元素从而继承不同 CSS 或采用不同的事件传播策略。注册式虚拟组件如果既想保留注册的便利又想获得虚拟组件的好处可以走“注册式虚拟”组件照常注册但 Golden Layout 内部按虚拟组件处理并自行处理上述事件。迁移现有注册式应用只需四步注册函数新增参数virtual默认false设为true表示该类型的组件在内部按虚拟组件实现组件需要提供rootHtmlElementgetter 返回根元素TypeScript 组件应实现GoldenLayout.VirtuableComponent接口组件rootHtmlElement的overflowCSS 属性需设为hidden确保 Golden Layout 容器元素是定位过的position不为static。注意该方式有几个细微行为变化Golden Layout 会强制组件根元素为absolute定位会修改根元素的宽高嵌入式绑定修改的是容器元素以及 z-index。另外registerGetComponentConstructorCallback()不支持“注册式虚拟”绑定。多种绑定方式混用与绑定优先级同一应用可为不同组件类型使用不同绑定方式。每当需要绑定组件时Golden Layout 按以下顺序尝试见 docs/binding-components/index.md检查类型是否已注册——已注册则按注册方式绑定检查是否有bindComponentEvent处理器——有则按虚拟组件方式绑定检查是否有getComponentEvent处理器——有则静态嵌入绑定已弃用以上皆无抛出异常。如果同时使用“事件式虚拟”和“事件式嵌入”unbindComponentEvent处理器可以通过ComponentContainer.virtual字段判断某个组件使用的是哪种绑定方式。与前端框架集成Angular / Vue典型框架把 HTML 元素包装进自己的组件中应用不再是 HTML 元素的树而是框架组件的树每个组件包装一个 HTML 元素。文档 docs/frameworks/index.md 指出传统的事件式嵌入绑定会把 Golden Layout 注入 HTML 元素树从而干扰框架的组件树需要高级框架技巧才能绕开而事件式虚拟绑定Virtual via Events不会干扰组件树是框架应用中的推荐绑定方式。Angular官方提供了一个示例 Angular 应用演示如何分别用“事件式嵌入”与“事件式虚拟”两种方式集成 Golden Layout。Vue社区示例vue3-golden-layout-virtualcomponent展示了虚拟组件事件式虚拟的基本用法包括添加组件、保存布局配置、加载布局配置等该示例还把 Golden Layout 封装成了 Vue 3 组件以便复用。如果希望在 Vue 中使用“事件式嵌入”绑定可以参考 docs/frameworks/vue/embedding-via-events.md 中的代码片段。其他框架统一采用事件式虚拟绑定并按上述指南设置事件处理器之后即可正常使用LayoutManager.loadLayout()、LayoutManager.addComponent()等创建组件的函数。组件尺寸与最小尺寸在布局树中RowOrColumn沿主轴方向子项的尺寸由每个子项的size属性指定。文档 docs/sizing-components/index.md 说明size出现在RowOrColumn或Stack的 item config 中是一个字符串由两部分组成数量会被解析为数字只能包含合法的数字字符和单位单位取值%百分比或fr分数未定义时默认1fr。对应地src/ts/config/config.ts 中ItemConfig.size的注释确认对 row 而言指定高度、对 column 而言指定宽度格式为numberSizeUnit目前仅支持fr和%。minSize则用于指定最小尺寸格式为numberpx。RowOrColumn子项的像素分配算法文档原文流程取得RowOrColumn沿主轴方向的像素尺寸row 为宽度、column 为高度从像素尺寸中减去所有 splitter分隔条的尺寸对每个以百分比指定尺寸的子项按其百分比分配像素若还有分数尺寸的子项若像素未被分配完把剩余像素按分数比例分配若已分配完甚至超分配则额外拿出 50% 的像素按分数比例分配调整分配使总和回到 100%尽可能重新分配像素以尊重子项指定的最小尺寸。示例 1假设某个RowOrColumn减去分隔条后尺寸为 100 像素。子项尺寸像素110%10230%3031fr2042fr40示例 2所有子项尺寸都未定义时各自默认 1fr若全部未定义则RowOrColumn的尺寸尽量均分给所有子项。子项尺寸像素1undefined252undefined253undefined254undefined25布局自适应与手动调整尺寸布局通常会始终适配 Golden Layout 容器的尺寸。文档 docs/layout-resizing/index.md 列出三个控制属性均可从 src/ts/layout-manager.ts 源码中直接看到默认值属性作用默认值resizeWithContainerAutomatically是否随容器尺寸自动重排布局容器为body时true否则falseresizeDebounceInterval容器尺寸连续变化时的防抖间隔毫秒100resizeDebounceExtendedWhenPossible是否尽量延迟重排直到容器停止变化true要点resizeWithContainerAutomatically true时Golden Layout 会在容器尺寸变化时自动重排为false时应用需自行管理。建议开启自动重排时把容器的overflow设为clip。关闭自动重排后应用可用LayoutManager.setSize()手动设置尺寸。文档认为“管理容器尺寸”比“直接管理布局尺寸”是更好的设计因此很难想象需要关闭自动重排的场景。v2 中默认值true仅当容器为body是为了向后兼容v3 发布时默认值将统一改为始终true。Golden Layout 使用ResizeObserver监听容器尺寸变化见 src/ts/layout-manager.ts 中_resizeObserver字段。ResizeObserver在 IE 中不可用如需支持 IE 必须使用 polyfill但正如 browserslist 所示Golden Layout 只支持现代浏览器不支持 IE。组件焦点Component Focus组件可以拥有焦点这与 HTML 元素拥有焦点类似任意时刻只有一个组件拥有焦点或者没有任何组件拥有焦点。文档 docs/component-focus/index.md 说明点击组件的标签页tab会使组件获得焦点编程式聚焦调用容器的focus()方法取消焦点调用ComponentContainer.blur()点击组件内部的 HTML 不会自动让组件获得焦点但可以监听冒泡的click和/或focusin事件在处理器中调用ComponentContainer.focus()——apitest演示了该技巧获得焦点的组件的标签页与 header 元素会带有lm_focusedclass可用来高亮。仓库自带的 src/less/themes/goldenlayout-dark-theme.less 主题apitest使用会给聚焦标签页设置不同背景色若不希望高亮聚焦标签页请在所用 css/less/scss 中移除lm_focused选择器。在 v2 的 API 中焦点相关能力体现在ComponentItem.focus()/ComponentItem.blur()详见下一节并伴随冒泡的focus/blur事件。位置选择器Location SelectorsLocationSelector用“父节点 索引”的方式描述一个组件应放置的位置但它不直接指定父节点而是描述如何搜索父节点。文档 docs/location-selectors/index.md 给出的接口类型为export interface LocationSelector { typeId: LocationSelector.TypeId; index?: number; }typeId指定搜索父节点的算法index供算法计算在父节点下的首选子位置。从 src/ts/layout-manager.ts 中可以看到完整的TypeId枚举与对应语义TypeId含义是否保证命中FocusedItem聚焦项所在的 Stackindex表示相对聚焦项的偏移如 1 表示聚焦项之后的位置无聚焦项时失败FocusedStack聚焦项所在的 Stackindex表示子内容项索引无聚焦项时失败FirstStack布局中第一个 Stack空布局时失败FirstRowOrColumn布局中第一个 Row 或 Column优先搜 Row空布局时失败FirstRow布局中第一个 Row空布局时失败FirstColumn布局中第一个 Column空布局时失败Empty仅当布局为空时找到位置即根内容项位置布局非空时失败Root布局为空时命中根位置否则命中根下的子位置始终命中LayoutManager.addComponentAtLocation()与LayoutManager.newComponentAtLocation()接收一个LocationSelector数组从第一个元素开始依次尝试寻找有效位置找到即使用全部失败则不添加组件。而LayoutManager.addComponent()与LayoutManager.newComponent()使用默认数组——其最后一个元素是TypeId.Root因此必定能找到位置这两个函数总能成功添加组件。默认数组定义在LayoutManager.defaultLocationSelectors其源码内容为[ { typeId: LocationSelector.TypeId.FocusedStack, index: undefined }, { typeId: LocationSelector.TypeId.FirstStack, index: undefined }, { typeId: LocationSelector.TypeId.FirstRowOrColumn, index: undefined }, { typeId: LocationSelector.TypeId.Root, index: undefined }, ]另一个预定义数组LayoutManager.afterFocusedItemIfPossibleLocationSelectors会优先尝试把新组件放到聚焦项之后[ { typeId: LocationSelector.TypeId.FocusedItem, index: 1 }, { typeId: LocationSelector.TypeId.FirstStack, index: undefined }, { typeId: LocationSelector.TypeId.FirstRowOrColumn, index: undefined }, { typeId: LocationSelector.TypeId.Root, index: undefined }, ]findLocation()的具体实现src/ts/layout-manager.ts 第 1651 行起按switch (selector.typeId)逐个算法查找例如FocusedItem依赖_focusedComponentItemFirstStack调用findFirstContentItemType(ItemType.stack)Root则优先返回根内容项下的子位置。这正是“默认数组总能命中”的源码依据。Popouts 弹出窗口与跨窗口广播组件可以从布局中“弹出”到独立浏览器窗口文档 docs/popouts/index.mdPopouts 默认对所有内容项启用通过在header配置中设置{ popout: false }或使组件不可关闭isClosable: false来禁用。使用注册式绑定时务必在所有组件类型注册完成后再初始化子窗口中的 golden-layout 实例。Popouts 在页面卸载时不会自动销毁如应用希望在页面卸载时关闭全部弹窗应在页面 unload 处理中调用LayoutManager.closeAllOpenPopouts()。apitest中的standard与tabDropdown布局包含 Popout 示例。跨窗口通信通过EventHub完成LayoutManager.eventHub.emitUserBroadcast()广播消息监听userBroadcast事件接收layoutManager.eventHub.on(userBroadcast, (...ev: EventEmitter.UnknownParams) { // respond to user broadcast event });完整的用户消息广播示例见 apitest/event-component.ts。限制EventHub 仅支持userBroadcast事件类型其他事件类型不会在窗口间广播因此窗口间的状态同步需要应用自行处理。从 v1 迁移到 v2v2 是一次重大重构核心变化是代码移植到 TypeScript维护重点转向可靠性。迁移前务必阅读文档 docs/version-2/index.md 的完整清单以下为关键点。被移除的功能React 支持v2 不再支持 React官方推荐使用专为 React 设计的 FlexLayout 库嵌套 Stackv1 中不完整的嵌套 Stack 实现被彻底移除v2 明确不允许嵌套 Stack内部/公开 API 划分所有类、接口、函数、属性都被标记为internal或public应用只能使用publicAPI旧浏览器只支持现代浏览器见 browserslist去除 jQueryGolden Layout 不再依赖 jQuery。Config 与 Resolved Configv2 引入强类型配置并区分两类Config应用开发者主要使用。支持可选属性未指定时使用默认值并处理向后兼容把已弃用属性迁移到新值。Golden Layout API 方法的参数均为 Config 类型唯一例外是LayoutConfig.saveLayout()返回 Resolved Config。Resolved ConfigGolden Layout 内部使用。API 收到 Config 后会解析为 Resolved Config填充默认值、处理向后兼容从而始终以完全配置的状态工作。持久化建议始终保存LayoutManager.saveLayout()返回的 Resolved Config重新加载时先调用LayoutConfig.fromResolved()把 Resolved Config 转换回 Config。两种 Config 都有两套接口层级ItemConfig内容项配置与LayoutConfig布局配置即旧Config接口。其他配置变更要点ItemConfig.id类型改为string旧为string | string[]解析时仍接受字符串数组以兼容旧配置——先检查数组中的旧最大化指示符然后取第一个元素作为id其余丢弃ComponentItemConfig.componentName被componentType取代类型为JsonValue但若要与registerComponent()弃用、registerComponentConstructor()、registerComponentFactoryFunction()配合使用componentType必须是stringLayoutConfig.root属性指定根内容项的 ItemConfig非可选、必须指定LayoutConfig.selectionEnabled被移除Stack Header 点击改由新的stackHeaderClick事件处理始终启用ResolvedLayoutConfig新增minifyConfig()/unminifyConfig()取代LayoutManager.minifyConfig()/unminifyConfig()大量配置属性因重叠或迁移而被弃用详见 src/ts/config/config.ts。类层级与构造方式GoldenLayout现在是VirtualLayout的派生类VirtualLayout又是LayoutManager的派生类。应用应始终创建GoldenLayout或VirtualLayout的实例。构造函数接受 3 个可选参数承载 Golden Layout 实例的 HTML 元素不指定则置于body下bindComponentEvent事件处理器unbindComponentEvent事件处理器。注意初始布局不再由构造函数指定而是通过LayoutManager.loadLayout()加载。组件注册职责移到GoldenLayout类LayoutManager不再含任何注册函数registerComponentConstructor()新函数等价于旧registerComponent()但仅用于注册组件构造函数registerComponentFactoryFunction()新函数等价于旧registerComponent()但仅用于注册创建组件的回调闭包不要使用registerComponent()改用上述两个新函数。LayoutManager 主要变化不要直接构造LayoutManager应构造GoldenLayout不要调用init()改用LayoutManager.loadLayout()新函数可重复调用来替换布局saveLayout()新函数保存当前布局为LayoutConfig取代toConfig()setSize()新函数以像素设置实例尺寸取代updateSize()rootItem新属性指定布局根内容项非 Ground 项不要使用旧root它已被内部属性groundItem取代通常应使用rootItemfocusComponent()聚焦指定组件项同一时刻仅一个若此前有焦点组件则先失焦除非suppressEvent为 trueclearComponentFocus()移除现有组件焦点除非suppressEvent为 true否则发出blur事件。ContentItem、ComponentContainer、事件AbstractContentItem更名为ContentItemconfig属性移除改用toConfig()id类型改为stringItemContainer更名为ComponentContainerComponent内容项类更名为ComponentItem现在“Component”指 Golden Layout 内部托管的外部组件Root更名为GroundItem并标记为 internal应用不应访问布局根内容项可通过LayoutManager.rootItem获取Stack.getActiveContentItem()/setActiveContentItem()更名为getActiveComponentItem()/setActiveComponentItem()ContentItem.select()/deselect()移除改用ComponentItem.focus()/blur()ComponentContainer.element新属性取代getElement()initialStategetterstateRequestEvent保存布局时触发用于获取组件最新状态beforeComponentRelease组件释放前触发可用于释放资源setState()已弃用replaceComponent()可在不影响布局的前提下替换容器内组件事件机制所有 DOM 事件均可冒泡以便父级或全局处理监听器不再调用preventDefault()冒泡事件以EventEmitter.BubblingEvent或其子类为参数发出新增事件beforeComponentRelease、stackHeaderClick、stackHeaderTouchStart、focus、blur统一使用undefined而非null作为新属性/事件的空值。弃用与公开/内部 API大多数旧函数与属性保留但标记为deprecated。官方强烈建议应用改造与弃用 API 相关的 bug 将获得低优先级甚至不修复且弃用项可能在后续版本中移除。发行包包含两份 TypeScript 声明文件index.d.ts仅含 public API应用应使用它访问库golden-layout-untrimmed.d.ts包含全部public internalAPI仅在确实需要访问内部元素时使用需自行承担上述风险。API 的 public/internal 划分尚未最终确定但apitest应用与示例 Angular 应用中使用的任何元素都会被保留为 public。总结Golden Layout 是一个以“多窗口、可拖拽、可持久化”为核心的现代布局管理器。通过本文你可以看到完整脉络从 docs/index.md 的安装构建流程npm 安装、源码构建、apitest演示、单文件 bundle、npm link调试到 docs/structure/index.md 的LayoutManagerContentItem树结构再到 docs/binding-components/index.md 的四种组件绑定方式——其中“事件式虚拟绑定”是框架应用Angular、Vue的推荐方案尺寸计算%与fr单位、自适应重排三个resize*属性 ResizeObserver、组件焦点、LocationSelector位置寻址、Popout 跨窗口广播共同构成了它的完整能力面。v2 的 TypeScript 化与严格 public/internal API 划分则保证了长期维护的可靠性。若要在自己的项目中动手实践apitest 演示应用和 src/ts 源码是最直接的参考。赞分享前端UI组件【免费下载链接】golden-layoutA multi window layout manager for webapps项目地址https://gitcode.com/gh_mirrors/go/golden-layout点击查看免费下载相关推荐如何快速掌握Golden Layout开源Web应用多窗口布局管理器完整指南如何快速掌握Golden Layout开源Web应用多窗口布局管理器完整指南 Golden Layout 是一款功能强大的开源Web应用多窗口布局管理器它允前端UI组件Golden Layout弹出窗口完整指南原生多窗口布局的终极实现方案Golden Layout弹出窗口完整指南原生多窗口布局的终极实现方案 在现代Web应用开发中多窗口布局管理是提升用户体验的关键功能。Golden Layo前端UI组件TextureAsyncDisplayKitLayout 2.0 升级指南从 1.x 迁移到 Flexbox 化布局 API 的完整对照TextureAsyncDisplayKitLayout 2.0 升级指南从 1.x 迁移到 Flexbox 化布局 API 的完整对照 适用对象与场景移动开发UI组件上一篇Office Tool Plus零基础3分钟搞定Office部署的终极指南下一篇QuantConnect Lean 量化策略入门从零到实盘快速上手指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Golden Layout 2.x 完整实战指南：多窗口布局管理器从安装到迁移
前端UI组件【免费下载链接】golden-layoutA multi window layout manager for webapps项目地址https://gitcode.com/gh_mirrors/go/golden-layout点击查看免费下载Golden Layout 是一个基于 JavaScript/TypeScript 的网页布局管理器让你可以在一个页面中摆放多个组件并通过拖拽自由重排、弹出独立窗口。本文以仓库 docs/index.md 为主体骨架结合 src/ts 源码与 package.json 中的真实脚本系统讲解它的功能特性、安装构建、核心数据结构、四种组件绑定方式、尺寸与自适应机制以及从 v1 迁移到 v2 的关键 API 变更。读完本文你将掌握 Golden Layout 的完整接入流程与底层实现原理能够在自己的 Web 应用中直接落地一套可拖拽、可持久化的多窗口布局方案。功能概览Golden Layout 的核心能力在 docs/index.md 中总结为以下特性原生弹窗Popouts组件可以被“弹出”到独立的浏览器窗口与主布局分开查看触摸支持支持触屏设备上的拖拽操作框架支持为 Angular、Vue 等应用框架提供集成能力虚拟组件Virtual ComponentsGolden Layout 不直接操作组件 DOM而是通过事件通知应用自行完成组件的定位全面的 API加载/保存布局、聚焦组件、编程式增删组件等均有公开接口布局持久化布局结构可保存为 JSON 配置并在之后重新加载组件焦点与 HTML 元素焦点机制类似同一时刻只有一个组件拥有焦点完全可主题化通过 CSS/Less/SCSS 定制全部外观现代浏览器支持面向 Firefox、Chrome 等现代浏览器响应式设计开箱即用。从 package.json 的browserslist字段可以看到项目明确支持的浏览器范围是最新版 Chrome、最新版 Firefox、近两个大版本的 Edge/Safari/iOS Safari 以及 Firefox ESR。这意味着 Golden Layout 不再支持 IE 等旧浏览器这一点在布局自适应章节还会再次强调。安装与使用通过 npm 安装Golden Layout 已发布到 NPM可以执行npm i golden-layout不过官方在 docs/index.md 中明确提示NPM 上的模块包已长时间未更新当前推荐的方式是从源码构建。如果只是想快速体验或用于旧项目npm 包仍然可用但建议优先走下面的源码路线。从源码构建推荐克隆当前仓库后在仓库根目录打开终端依次执行npm install或npm ci推荐后者保证依赖版本与 lock 文件一致安装所需依赖npm run build生成发行版输出到dist子目录。根据 package.json 中build脚本的定义npm run build会依次完成删除旧的lib与dist目录clean脚本编译 TypeScript 源码build:cjs与build:module:api通过api-extractor生成聚合的 TypeScript 类型声明文件index.d.ts与golden-layout-untrimmed.d.ts生成 source map将样式文件复制到dist目录build:styles。构建完成后将dist/css的内容递归复制到你的应用可读取的位置即可。需要注意lib子目录只存放编译器生成的 TypeScript 声明文件一般可以忽略它仅用于构建过程中生成聚合声明文件。构建并运行演示应用apitest仓库内置了一个apitest演示应用用于直观查看和调试库的功能。构建并启动开发服务器npm run apitest:build # 仅构建 npm run apitest:serve # 构建并启动开发服务器启动后在浏览器访问http://localhost:3000/即可查看。演示应用的源码位于 apitest 目录其中 predefined-layouts.ts、text-component.ts、event-component.ts 等文件覆盖了预定义布局、普通组件、事件广播等典型用法是学习 API 的最好范本。构建单文件 bundle如果不希望引入完整工具链可以直接使用单文件 bundle。执行npm run build:bundles构建产物位于dist/bundle/。注意 bundle 默认不构建也不包含在 NPM 包中。如果使用 ES Module推荐将dist/bundle/esm/golden-layout.min.js调试时用golden-layout.js复制到项目中并命名为golden-layout.js然后即可按需导入import { GoldenLayout, LayoutConfig, ResolvedLayoutConfig, ItemConfig, ComponentItemConfig, ResolvedItemConfig, RowOrColumn, Tab } from ./golden-layout.js;main、module、typings字段见 package.json分别指向dist/cjs/index.js、dist/esm/index.js与dist/types/index.d.ts说明包同时提供 CommonJS 与 ESM 两种模块格式。调试 Golden Layout 库apitest应用的 webpack 配置会引入 Golden Layout 库的 source map因此可以在调试器中直接对库源码下断点、单步跟踪见 apitest/webpack.config.js。若要在其他应用中调试库源码可使用npm link进行软链接在 golden-layout 仓库根目录执行npm link在目标应用的根目录执行npm link golden-layout。此后目标应用会直接使用仓库dist目录中的发行版。如果修改了库代码需要运行npm run build重新生成dist目录。要解除链接在目标应用执行npm install即可。布局结构LayoutManager 与 ContentItem 树布局结构是理解 Golden Layout 一切行为的基石。官方文档 docs/structure/index.md 给出了完整的关系图核心要点如下LayoutManager (GoldenLayout 或 VirtualLayout) └── GroundItem隐藏永久存在 └── 根 ContentItem ├── ComponentItem根为组件单一元素不可操作 ├── Stack根为标签栈 │ └── ComponentItem × N └── RowOrColumn根为行列 ├── RowOrColumn × N └── Stack × N └── ComponentItem × N一个GoldenLayout或VirtualLayout对象是LayoutManager的派生类继承链为LayoutManager→VirtualLayout→GoldenLayout见 src/ts/layout-manager.ts 与 docs/binding-components/index.md。创建任一实例时LayoutManager随之创建同时会创建一个GroundItem内容项它伴随LayoutManager的整个生命周期。其它对象ComponentItem、RowOrColumn、Stack、BrowserPopout构成布局本身在布局被加载或修改时创建在布局关闭或重新加载时销毁。一套布局由两部分组成① 组成主布局的ContentItem树不含弹窗② 打开的BrowserPopout列表。主布局树的根节点可以是ComponentItem、Stack或RowOrColumn若根是ComponentItem布局只有一个组件用户无法对它进行任何布局操作——对用户而言 Golden Layout 就像不存在一样若根是RowOrColumn它作为树的根每个RowOrColumn有一个或多个子内容项子项可以是RowOrColumn或Stack树的叶子一定是Stack。GroundItem的存在是为了让布局中每一个内容项都有父节点包括根内容项。它最多只能有一个子内容项即根内容项当没有加载布局时GroundItem有 0 个子节点根内容项为undefined。GroundItem不对外暴露其方法全部通过LayoutManager访问。从源码结构看GroundItem、RowOrColumn、Stack、ComponentItem分别对应 src/ts/items/ground-item.ts、src/ts/items/row-or-column.ts、src/ts/items/stack.ts、src/ts/items/component-item.ts统一继承自 src/ts/items/content-item.ts。绑定组件的四种方式Golden Layout 绑定到组件之后会控制其位置、尺寸与可见性。文档 docs/binding-components/index.md 明确了四种绑定方式按复杂度从低到高排列绑定方式组件来源定位方式适用场景注册式嵌入Embedding via Registration注册的构造函数/工厂函数Golden Layout 自带 DOM 层级内经典用法快速简单事件式嵌入Embedding via EventsbindComponentEvent事件处理器Golden Layout 自带 DOM 层级内应用需要更多分配控制权注册式虚拟Virtual via Registration注册的构造函数/工厂函数内部按虚拟组件处理以最小改动获得虚拟组件优势事件式虚拟Virtual via EventsbindComponentEvent事件处理器由应用自行定位最大设计灵活性框架集成推荐注册式嵌入经典方式这是最经典的绑定方式把组件类型注册给 Golden Layout指定一个构造函数或回调函数每当布局需要新实例时调用它。调用时传入一个容器对象ComponentContainer其中包含 HTML 元素构造函数会把组件的顶层元素挂到容器的 HTML 元素下使组件成为 Golden Layout DOM 层级的一部分。布局重排时Golden Layout 会调整 DOM 以匹配新的层级——实质上是重挂reparent组件根元素的祖先节点。可用于注册的函数包括GoldenLayout.registerComponent()已弃用GoldenLayout.registerComponentConstructor()GoldenLayout.registerComponentFactoryFunction()GoldenLayout.registerComponentFunction()已弃用GoldenLayout.registerGetComponentConstructorCallback()从源码 src/ts/golden-layout.ts 可以看到registerComponent()会根据传入函数是否带有prototype属性自动判断它是构造函数还是工厂函数然后分派给registerComponentConstructor()或registerComponentFactoryFunction()。两者都接受第三个参数virtual默认false并且都会在组件类型已注册时抛出绑定错误。事件式嵌入为了给应用更多控制权可以改用事件绑定为VirtualLayout.bindComponentEvent事件分配处理器后每当需要新组件时该事件被触发。处理器需要创建或获取组件确保组件顶层 HTML 元素成为container.element的子节点以virtual: false的BindableComponent接口返回组件。当组件从布局中移除时需要在VirtualLayout.unbindComponentEvent事件或容器container的beforeComponentRelease事件两者皆可中清理移除顶层元素、释放资源。只要分配了处理器这两个事件在组件不再被需要时都会触发。事件式虚拟组件Virtual Components虚拟组件模式下Golden Layout完全不知道组件的存在不会把组件 HTML 元素纳入自己的 DOM 层级。每当组件的位置、尺寸或可见性需要改变时Golden Layout 触发事件由应用来更新组件——这类似于虚拟网格virtual grid的思路网格不包含真实内容而是在需要显示内容时触发事件由应用返回内容。虚拟组件的主要优势文档原文要点布局变化时组件及其祖先不会被重挂避免破坏 iframe、socket 等无需从组件中提取顶层 HTML 元素Angular、Vue 等自带组件树的应用无需打破自己的组件层级不再需要 teleport 组件的 HTML 元素应用的 DOM 层级更浅调试更简单。需要处理的事件与典型处理器模式如下代码示例来自 docs/binding-components/index.mdVirtualLayout.bindComponentEvent: (container, itemConfig) ComponentContainer.BindableComponent新组件需要绑定时触发。典型做法是用itemConfig创建/获取组件 → 取组件的顶层 HTML 元素 → 确保其为absolute定位 → 挂到 Golden Layout 根元素下 → 以container为键存入映射 → 注册virtualRectingRequiredEvent与virtualVisibilityChangeRequiredEvent→ 以virtual: true返回。private handleBindComponentEvent(container: ComponentContainer, itemConfig: ResolvedComponentItemConfig) { const componentTypeName ResolvedComponentItemConfig.resolveComponentTypeName(itemConfig); if (componentTypeName undefined) { throw new Error(handleBindComponentEvent: Undefined componentTypeName); } const component this.createVirtualComponent(container, componentTypeName, itemConfig.componentState); const componentRootElement component.rootHtmlElement; this._layoutElement.appendChild(componentRootElement); this._boundComponentMap.set(container, component); container.virtualRectingRequiredEvent (container, width, height) this.handleContainerVirtualRectingRequiredEvent(container, width, height); container.virtualVisibilityChangeRequiredEvent (container, visible) this.handleContainerVisibilityChangeRequiredEvent(container, visible); return { component, virtual: true }; }VirtualLayout.unbindComponentEvent: (container) void组件被移除时触发。典型做法是按container从映射中取出组件从根元素上移除其顶层元素并删除映射项。LayoutManager.beforeVirtualRectingEvent: () void布局变更后可能一次需要重排多个组件该事件在重排前触发一次常用于缓存 Golden Layout 根元素的getBoundingClientRect()结果private handleBeforeVirtualRectingEvent(count: number) { this._goldenLayoutBoundingClientRect this._layoutElement.getBoundingClientRect(); }ComponentContainer.virtualRectingRequiredEvent: (container, width, height) void组件位置/尺寸需要变化时触发。典型做法是以container为键取组件 → 用getBoundingClientRect()计算容器相对 Golden Layout 根元素的位置 → 更新顶层元素的left、top、width、height。ComponentContainer.virtualVisibilityChangeRequiredEvent: (container, visible) void可见性变化时触发典型做法是修改顶层元素的display属性。ComponentContainer.virtualZIndexChangeRequiredEvent: (container, logicalZIndex, defaultZIndex) voidz-index 变化时触发典型做法是把顶层元素的zIndex设置为defaultZIndex。apitest应用完整演示了虚拟组件的实现方式见 apitest/app.ts。使用虚拟组件时可以把 Golden Layout 理解为一个只计算位置而非实际摆放组件的引擎。它的初始搭建工作量比其他方式更大但灵活性更高例如任何 HTML 元素都可以作为组件的父元素不限于 Golden Layout 容器不同组件甚至可以有不同父元素从而继承不同 CSS 或采用不同的事件传播策略。注册式虚拟组件如果既想保留注册的便利又想获得虚拟组件的好处可以走“注册式虚拟”组件照常注册但 Golden Layout 内部按虚拟组件处理并自行处理上述事件。迁移现有注册式应用只需四步注册函数新增参数virtual默认false设为true表示该类型的组件在内部按虚拟组件实现组件需要提供rootHtmlElementgetter 返回根元素TypeScript 组件应实现GoldenLayout.VirtuableComponent接口组件rootHtmlElement的overflowCSS 属性需设为hidden确保 Golden Layout 容器元素是定位过的position不为static。注意该方式有几个细微行为变化Golden Layout 会强制组件根元素为absolute定位会修改根元素的宽高嵌入式绑定修改的是容器元素以及 z-index。另外registerGetComponentConstructorCallback()不支持“注册式虚拟”绑定。多种绑定方式混用与绑定优先级同一应用可为不同组件类型使用不同绑定方式。每当需要绑定组件时Golden Layout 按以下顺序尝试见 docs/binding-components/index.md检查类型是否已注册——已注册则按注册方式绑定检查是否有bindComponentEvent处理器——有则按虚拟组件方式绑定检查是否有getComponentEvent处理器——有则静态嵌入绑定已弃用以上皆无抛出异常。如果同时使用“事件式虚拟”和“事件式嵌入”unbindComponentEvent处理器可以通过ComponentContainer.virtual字段判断某个组件使用的是哪种绑定方式。与前端框架集成Angular / Vue典型框架把 HTML 元素包装进自己的组件中应用不再是 HTML 元素的树而是框架组件的树每个组件包装一个 HTML 元素。文档 docs/frameworks/index.md 指出传统的事件式嵌入绑定会把 Golden Layout 注入 HTML 元素树从而干扰框架的组件树需要高级框架技巧才能绕开而事件式虚拟绑定Virtual via Events不会干扰组件树是框架应用中的推荐绑定方式。Angular官方提供了一个示例 Angular 应用演示如何分别用“事件式嵌入”与“事件式虚拟”两种方式集成 Golden Layout。Vue社区示例vue3-golden-layout-virtualcomponent展示了虚拟组件事件式虚拟的基本用法包括添加组件、保存布局配置、加载布局配置等该示例还把 Golden Layout 封装成了 Vue 3 组件以便复用。如果希望在 Vue 中使用“事件式嵌入”绑定可以参考 docs/frameworks/vue/embedding-via-events.md 中的代码片段。其他框架统一采用事件式虚拟绑定并按上述指南设置事件处理器之后即可正常使用LayoutManager.loadLayout()、LayoutManager.addComponent()等创建组件的函数。组件尺寸与最小尺寸在布局树中RowOrColumn沿主轴方向子项的尺寸由每个子项的size属性指定。文档 docs/sizing-components/index.md 说明size出现在RowOrColumn或Stack的 item config 中是一个字符串由两部分组成数量会被解析为数字只能包含合法的数字字符和单位单位取值%百分比或fr分数未定义时默认1fr。对应地src/ts/config/config.ts 中ItemConfig.size的注释确认对 row 而言指定高度、对 column 而言指定宽度格式为numberSizeUnit目前仅支持fr和%。minSize则用于指定最小尺寸格式为numberpx。RowOrColumn子项的像素分配算法文档原文流程取得RowOrColumn沿主轴方向的像素尺寸row 为宽度、column 为高度从像素尺寸中减去所有 splitter分隔条的尺寸对每个以百分比指定尺寸的子项按其百分比分配像素若还有分数尺寸的子项若像素未被分配完把剩余像素按分数比例分配若已分配完甚至超分配则额外拿出 50% 的像素按分数比例分配调整分配使总和回到 100%尽可能重新分配像素以尊重子项指定的最小尺寸。示例 1假设某个RowOrColumn减去分隔条后尺寸为 100 像素。子项尺寸像素110%10230%3031fr2042fr40示例 2所有子项尺寸都未定义时各自默认 1fr若全部未定义则RowOrColumn的尺寸尽量均分给所有子项。子项尺寸像素1undefined252undefined253undefined254undefined25布局自适应与手动调整尺寸布局通常会始终适配 Golden Layout 容器的尺寸。文档 docs/layout-resizing/index.md 列出三个控制属性均可从 src/ts/layout-manager.ts 源码中直接看到默认值属性作用默认值resizeWithContainerAutomatically是否随容器尺寸自动重排布局容器为body时true否则falseresizeDebounceInterval容器尺寸连续变化时的防抖间隔毫秒100resizeDebounceExtendedWhenPossible是否尽量延迟重排直到容器停止变化true要点resizeWithContainerAutomatically true时Golden Layout 会在容器尺寸变化时自动重排为false时应用需自行管理。建议开启自动重排时把容器的overflow设为clip。关闭自动重排后应用可用LayoutManager.setSize()手动设置尺寸。文档认为“管理容器尺寸”比“直接管理布局尺寸”是更好的设计因此很难想象需要关闭自动重排的场景。v2 中默认值true仅当容器为body是为了向后兼容v3 发布时默认值将统一改为始终true。Golden Layout 使用ResizeObserver监听容器尺寸变化见 src/ts/layout-manager.ts 中_resizeObserver字段。ResizeObserver在 IE 中不可用如需支持 IE 必须使用 polyfill但正如 browserslist 所示Golden Layout 只支持现代浏览器不支持 IE。组件焦点Component Focus组件可以拥有焦点这与 HTML 元素拥有焦点类似任意时刻只有一个组件拥有焦点或者没有任何组件拥有焦点。文档 docs/component-focus/index.md 说明点击组件的标签页tab会使组件获得焦点编程式聚焦调用容器的focus()方法取消焦点调用ComponentContainer.blur()点击组件内部的 HTML 不会自动让组件获得焦点但可以监听冒泡的click和/或focusin事件在处理器中调用ComponentContainer.focus()——apitest演示了该技巧获得焦点的组件的标签页与 header 元素会带有lm_focusedclass可用来高亮。仓库自带的 src/less/themes/goldenlayout-dark-theme.less 主题apitest使用会给聚焦标签页设置不同背景色若不希望高亮聚焦标签页请在所用 css/less/scss 中移除lm_focused选择器。在 v2 的 API 中焦点相关能力体现在ComponentItem.focus()/ComponentItem.blur()详见下一节并伴随冒泡的focus/blur事件。位置选择器Location SelectorsLocationSelector用“父节点 索引”的方式描述一个组件应放置的位置但它不直接指定父节点而是描述如何搜索父节点。文档 docs/location-selectors/index.md 给出的接口类型为export interface LocationSelector { typeId: LocationSelector.TypeId; index?: number; }typeId指定搜索父节点的算法index供算法计算在父节点下的首选子位置。从 src/ts/layout-manager.ts 中可以看到完整的TypeId枚举与对应语义TypeId含义是否保证命中FocusedItem聚焦项所在的 Stackindex表示相对聚焦项的偏移如 1 表示聚焦项之后的位置无聚焦项时失败FocusedStack聚焦项所在的 Stackindex表示子内容项索引无聚焦项时失败FirstStack布局中第一个 Stack空布局时失败FirstRowOrColumn布局中第一个 Row 或 Column优先搜 Row空布局时失败FirstRow布局中第一个 Row空布局时失败FirstColumn布局中第一个 Column空布局时失败Empty仅当布局为空时找到位置即根内容项位置布局非空时失败Root布局为空时命中根位置否则命中根下的子位置始终命中LayoutManager.addComponentAtLocation()与LayoutManager.newComponentAtLocation()接收一个LocationSelector数组从第一个元素开始依次尝试寻找有效位置找到即使用全部失败则不添加组件。而LayoutManager.addComponent()与LayoutManager.newComponent()使用默认数组——其最后一个元素是TypeId.Root因此必定能找到位置这两个函数总能成功添加组件。默认数组定义在LayoutManager.defaultLocationSelectors其源码内容为[ { typeId: LocationSelector.TypeId.FocusedStack, index: undefined }, { typeId: LocationSelector.TypeId.FirstStack, index: undefined }, { typeId: LocationSelector.TypeId.FirstRowOrColumn, index: undefined }, { typeId: LocationSelector.TypeId.Root, index: undefined }, ]另一个预定义数组LayoutManager.afterFocusedItemIfPossibleLocationSelectors会优先尝试把新组件放到聚焦项之后[ { typeId: LocationSelector.TypeId.FocusedItem, index: 1 }, { typeId: LocationSelector.TypeId.FirstStack, index: undefined }, { typeId: LocationSelector.TypeId.FirstRowOrColumn, index: undefined }, { typeId: LocationSelector.TypeId.Root, index: undefined }, ]findLocation()的具体实现src/ts/layout-manager.ts 第 1651 行起按switch (selector.typeId)逐个算法查找例如FocusedItem依赖_focusedComponentItemFirstStack调用findFirstContentItemType(ItemType.stack)Root则优先返回根内容项下的子位置。这正是“默认数组总能命中”的源码依据。Popouts 弹出窗口与跨窗口广播组件可以从布局中“弹出”到独立浏览器窗口文档 docs/popouts/index.mdPopouts 默认对所有内容项启用通过在header配置中设置{ popout: false }或使组件不可关闭isClosable: false来禁用。使用注册式绑定时务必在所有组件类型注册完成后再初始化子窗口中的 golden-layout 实例。Popouts 在页面卸载时不会自动销毁如应用希望在页面卸载时关闭全部弹窗应在页面 unload 处理中调用LayoutManager.closeAllOpenPopouts()。apitest中的standard与tabDropdown布局包含 Popout 示例。跨窗口通信通过EventHub完成LayoutManager.eventHub.emitUserBroadcast()广播消息监听userBroadcast事件接收layoutManager.eventHub.on(userBroadcast, (...ev: EventEmitter.UnknownParams) { // respond to user broadcast event });完整的用户消息广播示例见 apitest/event-component.ts。限制EventHub 仅支持userBroadcast事件类型其他事件类型不会在窗口间广播因此窗口间的状态同步需要应用自行处理。从 v1 迁移到 v2v2 是一次重大重构核心变化是代码移植到 TypeScript维护重点转向可靠性。迁移前务必阅读文档 docs/version-2/index.md 的完整清单以下为关键点。被移除的功能React 支持v2 不再支持 React官方推荐使用专为 React 设计的 FlexLayout 库嵌套 Stackv1 中不完整的嵌套 Stack 实现被彻底移除v2 明确不允许嵌套 Stack内部/公开 API 划分所有类、接口、函数、属性都被标记为internal或public应用只能使用publicAPI旧浏览器只支持现代浏览器见 browserslist去除 jQueryGolden Layout 不再依赖 jQuery。Config 与 Resolved Configv2 引入强类型配置并区分两类Config应用开发者主要使用。支持可选属性未指定时使用默认值并处理向后兼容把已弃用属性迁移到新值。Golden Layout API 方法的参数均为 Config 类型唯一例外是LayoutConfig.saveLayout()返回 Resolved Config。Resolved ConfigGolden Layout 内部使用。API 收到 Config 后会解析为 Resolved Config填充默认值、处理向后兼容从而始终以完全配置的状态工作。持久化建议始终保存LayoutManager.saveLayout()返回的 Resolved Config重新加载时先调用LayoutConfig.fromResolved()把 Resolved Config 转换回 Config。两种 Config 都有两套接口层级ItemConfig内容项配置与LayoutConfig布局配置即旧Config接口。其他配置变更要点ItemConfig.id类型改为string旧为string | string[]解析时仍接受字符串数组以兼容旧配置——先检查数组中的旧最大化指示符然后取第一个元素作为id其余丢弃ComponentItemConfig.componentName被componentType取代类型为JsonValue但若要与registerComponent()弃用、registerComponentConstructor()、registerComponentFactoryFunction()配合使用componentType必须是stringLayoutConfig.root属性指定根内容项的 ItemConfig非可选、必须指定LayoutConfig.selectionEnabled被移除Stack Header 点击改由新的stackHeaderClick事件处理始终启用ResolvedLayoutConfig新增minifyConfig()/unminifyConfig()取代LayoutManager.minifyConfig()/unminifyConfig()大量配置属性因重叠或迁移而被弃用详见 src/ts/config/config.ts。类层级与构造方式GoldenLayout现在是VirtualLayout的派生类VirtualLayout又是LayoutManager的派生类。应用应始终创建GoldenLayout或VirtualLayout的实例。构造函数接受 3 个可选参数承载 Golden Layout 实例的 HTML 元素不指定则置于body下bindComponentEvent事件处理器unbindComponentEvent事件处理器。注意初始布局不再由构造函数指定而是通过LayoutManager.loadLayout()加载。组件注册职责移到GoldenLayout类LayoutManager不再含任何注册函数registerComponentConstructor()新函数等价于旧registerComponent()但仅用于注册组件构造函数registerComponentFactoryFunction()新函数等价于旧registerComponent()但仅用于注册创建组件的回调闭包不要使用registerComponent()改用上述两个新函数。LayoutManager 主要变化不要直接构造LayoutManager应构造GoldenLayout不要调用init()改用LayoutManager.loadLayout()新函数可重复调用来替换布局saveLayout()新函数保存当前布局为LayoutConfig取代toConfig()setSize()新函数以像素设置实例尺寸取代updateSize()rootItem新属性指定布局根内容项非 Ground 项不要使用旧root它已被内部属性groundItem取代通常应使用rootItemfocusComponent()聚焦指定组件项同一时刻仅一个若此前有焦点组件则先失焦除非suppressEvent为 trueclearComponentFocus()移除现有组件焦点除非suppressEvent为 true否则发出blur事件。ContentItem、ComponentContainer、事件AbstractContentItem更名为ContentItemconfig属性移除改用toConfig()id类型改为stringItemContainer更名为ComponentContainerComponent内容项类更名为ComponentItem现在“Component”指 Golden Layout 内部托管的外部组件Root更名为GroundItem并标记为 internal应用不应访问布局根内容项可通过LayoutManager.rootItem获取Stack.getActiveContentItem()/setActiveContentItem()更名为getActiveComponentItem()/setActiveComponentItem()ContentItem.select()/deselect()移除改用ComponentItem.focus()/blur()ComponentContainer.element新属性取代getElement()initialStategetterstateRequestEvent保存布局时触发用于获取组件最新状态beforeComponentRelease组件释放前触发可用于释放资源setState()已弃用replaceComponent()可在不影响布局的前提下替换容器内组件事件机制所有 DOM 事件均可冒泡以便父级或全局处理监听器不再调用preventDefault()冒泡事件以EventEmitter.BubblingEvent或其子类为参数发出新增事件beforeComponentRelease、stackHeaderClick、stackHeaderTouchStart、focus、blur统一使用undefined而非null作为新属性/事件的空值。弃用与公开/内部 API大多数旧函数与属性保留但标记为deprecated。官方强烈建议应用改造与弃用 API 相关的 bug 将获得低优先级甚至不修复且弃用项可能在后续版本中移除。发行包包含两份 TypeScript 声明文件index.d.ts仅含 public API应用应使用它访问库golden-layout-untrimmed.d.ts包含全部public internalAPI仅在确实需要访问内部元素时使用需自行承担上述风险。API 的 public/internal 划分尚未最终确定但apitest应用与示例 Angular 应用中使用的任何元素都会被保留为 public。总结Golden Layout 是一个以“多窗口、可拖拽、可持久化”为核心的现代布局管理器。通过本文你可以看到完整脉络从 docs/index.md 的安装构建流程npm 安装、源码构建、apitest演示、单文件 bundle、npm link调试到 docs/structure/index.md 的LayoutManagerContentItem树结构再到 docs/binding-components/index.md 的四种组件绑定方式——其中“事件式虚拟绑定”是框架应用Angular、Vue的推荐方案尺寸计算%与fr单位、自适应重排三个resize*属性 ResizeObserver、组件焦点、LocationSelector位置寻址、Popout 跨窗口广播共同构成了它的完整能力面。v2 的 TypeScript 化与严格 public/internal API 划分则保证了长期维护的可靠性。若要在自己的项目中动手实践apitest 演示应用和 src/ts 源码是最直接的参考。赞分享前端UI组件【免费下载链接】golden-layoutA multi window layout manager for webapps项目地址https://gitcode.com/gh_mirrors/go/golden-layout点击查看免费下载相关推荐如何快速掌握Golden Layout开源Web应用多窗口布局管理器完整指南如何快速掌握Golden Layout开源Web应用多窗口布局管理器完整指南 Golden Layout 是一款功能强大的开源Web应用多窗口布局管理器它允前端UI组件Golden Layout弹出窗口完整指南原生多窗口布局的终极实现方案Golden Layout弹出窗口完整指南原生多窗口布局的终极实现方案 在现代Web应用开发中多窗口布局管理是提升用户体验的关键功能。Golden Layo前端UI组件TextureAsyncDisplayKitLayout 2.0 升级指南从 1.x 迁移到 Flexbox 化布局 API 的完整对照TextureAsyncDisplayKitLayout 2.0 升级指南从 1.x 迁移到 Flexbox 化布局 API 的完整对照 适用对象与场景移动开发UI组件上一篇Office Tool Plus零基础3分钟搞定Office部署的终极指南下一篇QuantConnect Lean 量化策略入门从零到实盘快速上手指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考