Beekeeper Studio UI Kit 实体列表Entity List组件完全指南属性、事件与实战用法【免费下载链接】beekeeper-studioModern and easy to use SQL client for MySQL, Postgres, SQLite, SQL Server, and more. Linux, MacOS, and Windows.项目地址: https://gitcode.com/GitHub_Trending/be/beekeeper-studio实体列表Entity List是 Beekeeper Studio UI Kit 提供的 Web Component用于以可展开/折叠的树形结构展示数据库对象表、视图、物化视图、例程与模式是数据库客户端侧边栏的核心交互组件。本文以 Entity List API 为骨架结合 Entity List 使用指南 与仓库源码完整讲解其全部属性Properties、事件Events以及 Schema 分组、隐藏、置顶、懒加载列、虚拟渲染等实战能力帮助你在自己的数据库工具或管理界面中直接复用该组件。组件概览如何引入 bks-entity-listbks-entity-list是一个通过 define.ts 注册到window.customElements的自定义元素底层由 EntityList.vue 经vue/web-component-wrapper包装而成见 index.ts。也就是说你可以像使用原生 HTML 标签一样在任意页面中使用它并通过属性property赋值和事件监听addEventListener来驱动它bks-entity-list/bks-entity-list script const entityList document.querySelector(bks-entity-list); entityList.entities [{ name: users }]; /script其数据来源是entities属性——一个由 Entity 对象组成的数组。Entity 类型在源码中定义为TableEntity | RoutineEntity | SchemaEntity三种联合类型见 types.ts。Properties组件全部可配置属性以下是 Entity List API 中声明的全部属性名称类型说明默认值entitiesobject[]实体数组详见 Entity API[]hiddenEntitiesobject[]被隐藏的实体数组详见 Entity API[]contextMenuItemsobject[]|function扩展默认右键菜单详见 Context Menuundefined除了 API 文档声明的三个核心属性组件的实际 props 定义entity-list.ts还暴露了以下常用配置项源码中有明确注释说明其用途属性类型说明默认值pinnedEntitiesEntity[]显示在主列表上方的置顶实体数组[]enablePinningboolean是否启用实体置顶功能falsepinnedSortByposition|name置顶实体的排序字段positionpinnedSortOrderstring置顶实体的排序方向ascshowCreateEntityBtnboolean是否显示新建实体按钮true其中pinnedSortBy的可选值在源码中通过SortByValues [position, name]常量约束contextMenuItems同时接受数组或函数两种形态CustomMenuItems类型用于静态或动态生成菜单项。Events组件对外广播的全部事件Entity List API 声明了以下 9 个事件完整列表如下事件名触发时机Event Detailbks-entity-expand实体被展开时{ entity: Entity }bks-entity-collapse实体被折叠时{ entity: Entity }bks-entity-dblclick实体被双击时{ event: MouseEvent, entity: Entity }bks-entity-contextmenu实体被右键点击时{ event: MouseEvent, entity: Entity }bks-entities-request-columns展开实体但其columns为undefined时{ entity: Entity }bks-expand-all点击全部展开按钮且所有实体均已展开时-bks-collapse-all点击全部折叠按钮且所有实体均已折叠时-bks-add-entity-click点击新建实体按钮时{ event: MouseEvent }bks-refresh-click点击刷新按钮时{ event: MouseEvent }这些事件在源码中有类型化定义EntityListEventMaptypes.ts将事件名与CustomEvent的 payload 类型一一绑定例如bks-entity-dblclick: CustomEvent{ entity: Entity }。同时组件还额外派发了bks-entity-pin、bks-entity-unpin、bks-entity-unhide、bks-refresh-btn-click、bks-pinned-entities-sort-by等事件见 EntityList.vue 与事件映射表分别对应置顶、取消置顶、取消隐藏与刷新按钮等交互。典型的事件监听方式entityList.addEventListener(bks-entity-dblclick, (event) { console.log(双击了实体, event.detail.entity); });基本用法从最小实体到带列结构只提供名称的实体最简单的实体只需一个name字段此时默认按table类型渲染const entities [{ name: users }, { name: orders }];携带列信息的实体提供columns后展开实体即可看到列清单每个列由field列名必填和dataType数据类型可选构成对应TableColumn接口Entity APIbks-entity-list/bks-entity-list script const entities [ { name: users, columns: [ { field: id, dataType: integer }, { field: name, dataType: string }, ], }, ]; const entityList document.querySelector(bks-entity-list); entityList.entities entities; /scriptSchemas按模式自动分组给实体对象提供一个schema字符串属性实体就会自动归入对应的模式schema文件夹内同一模式的多个实体共享一个文件夹const entities [ { name: users, schema: public }, { name: orders, schema: public }, ];该行为在 treeItems.ts 的树构建逻辑与 entity-list.spec.ts 中有明确的测试印证当实体携带schema时树中会先插入一个type: schema、entity: { entityType: schema, name: public }的文件夹节点实体节点则以level: 1挂在其下测试还验证了无 schema、单 schema、多 schema 三种场景下树的生成结构。Entity types四种实体类型组件识别table、view、materialized-view、routine四种类型schema类型则由组件在按模式分组时自动生成。示例如下const entities [ { name: users }, // 缺省类型默认按 table 处理 { name: users, entityType: table }, { name: order_summary, entityType: view }, { name: order_summary_2, entityType: materialized-view }, { name: get_order, entityType: routine, returnType: integer, type: function, // function / window / aggregate / procedure }, ];在 models.ts 中例程类型RoutineTypeNames被映射为四种展示名称functionFunction、windowWindow Function、aggregateAggregate Function、procedureStored Procedure。例程实体的完整结构见 Entity APIentityType必须为routinereturnType必填还可选提供returnTypeLength与routineParams每个参数包含必填的name、type与可选的length。Identifier实体标识符的确定规则实体列表默认使用name、schema、entityType三者的组合作为实体的唯一标识符key。如果需要使用自定义标识可在实体对象上添加id属性const users { id: abc123, name: users };从测试用例entity-list.spec.ts可以看到实际 key 的生成形态无 schema 时形如table..users、routine..get_users带 schema 时形如table.public.usersschema 文件夹节点形如schema.public。也就是说标识符按{entityType}.{schema}.{name}的模式拼接提供id后即可绕过这一默认规则。Hiding隐藏实体与 UI 辅助从逻辑上讲只要不把某个实体放进entities数组它就不会显示。但组件还提供了 UI 提示与一个隐藏实体弹窗HiddenEntitiesModal帮助用户统一管理被隐藏的实体列表。启用方式是把要隐藏的实体放进hiddenEntities属性const entities [users, orders]; const hiddenEntities [orders]; entityList.entities entities; entityList.hiddenEntities hiddenEntities; // 监听取消隐藏事件从 hiddenEntities 中移除目标实体 entityList.addEventListener(bks-entity-unhide, (event) { const entity event.detail.entity; const entities hiddenEntities.filter( (hiddenEntity) hiddenEntity ! entity ); entityList.hiddenEntities entities; });在组件模板EntityList.vue中当hiddenEntities非空且没有激活过滤时标题区会显示一个visibility_off徽标与隐藏数量超过 99 显示为99并提供Right click an entity to hide it的悬浮提示与View hidden入口点击后打开HiddenEntitiesModal弹窗弹窗内的取消隐藏通过bks-entity-unhide事件回传给宿主应用。Pinning置顶实体置顶功能可以把常用实体固定显示在主列表上方。启用方式为将enablePinning设为true并把需要置顶的实体放入pinnedEntitiesconst entities [users, orders]; const pinnedEntities [orders]; entityList.enablePinning true; entityList.entities entities; entityList.pinnedEntities pinnedEntities; // 处理置顶追加实体到 pinnedEntities entityList.addEventListener(bks-entity-pin, (event) { const entity event.detail.entity; const entities pinnedEntities.concat(entity); entityList.pinnedEntities entities; }); // 处理取消置顶从 pinnedEntities 中移除实体 entityList.addEventListener(bks-entity-unpin, (event) { const entity event.detail.entity; const entities pinnedEntities.filter( (pinnedEntity) pinnedEntity ! entity ); entityList.pinnedEntities entities; });置顶区域由独立的 PinnedTableList.vue 渲染主列表与置顶列表之间通过split.js提供了可拖拽的分隔条见 EntityList.vue。置顶实体还支持排序bks-pinned-entities-sort-by、bks-pinned-entities-sort-order、bks-pinned-entities-sort-position事件默认按position升序排列可切换为按name排序。Lazy Loading Columns列信息的懒加载开启列懒加载非常简单不设置实体的columns属性或显式将其设为undefined组件就会在需要时主动请求列信息。当实体被展开点击实体图标旁的展开箭头或点击右上角的全部展开按钮时组件会派发bks-entities-request-columns事件宿主应用在此事件中异步获取列并写回实体对象entityList.addEventListener(bks-entities-request-columns, (event) { const entities event.detail.entities; for (const entity of entities) { const columns await fetchColumns(entity); entity.columns columns; } });该机制同样适用于其他表类实体view与materialized-view。借助虚拟渲染组件只会为进入视口的实体发起请求避免一次加载海量列定义。如果想彻底关闭懒加载、阻止事件派发只需把实体的columns设为[]空数组。事件的派发链路在 EntityList.vue 中可以看到handleRequestItemsColumns/handleRequestEntitiesColumns将Item[]或Entity[]映射为{ entities: [...] }后统一 emit。Virtual Rendering虚拟渲染与内置过滤实体列表采用虚拟渲染策略只渲染视口内的实体并在用户滚动时增量更新从而支撑包含大量表/视图/例程的大型数据库侧边栏。组件内部还内置了实体过滤能力sql_tools.ts顶部的过滤输入框按名称做前缀优先、包含次之的两级匹配先收集以查询词开头的实体再收集包含查询词的实体并拼接右上角的过滤菜单则支持按 Tables / Views / Routines 分类开关showPartitions用于控制分区实体parenttype p的显示。过滤激活时标题区会显示shownEntities / totalEntities的计数徽标EntityList.vue。Context Menu扩展右键菜单contextMenuItems属性用于在默认右键菜单基础上追加自定义项它可以是一个菜单项数组也可以是一个函数动态生成菜单项。组件默认内置了Copy Name菜单项将实体名写入剪贴板见 EntityList.vue。右键实体的处理流程在 EntityList.vue 中先派发bks-entity-contextmenu事件再通过useCustomMenuItems合并默认菜单与自定义菜单最后调用openMenu打开菜单。关于自定义菜单项的完整配置方式数组/函数两种形态、菜单项字段结构等请参考 Context Menu 文档。API 速查相关文档与源码索引Entity List API组件属性与事件的官方 API 参考Entity List 使用指南完整的使用示例Entity APIEntity类型定义表/视图/物化视图/例程/模式Context Menu右键菜单扩展指南组件实现EntityList.vue、entity-list.ts、types.ts、treeItems.ts类型定义types.ts、models.ts单元测试entity-list.spec.ts覆盖无 schema / 单 schema / 多 schema 三种树的构建场景小结bks-entity-list是一个开箱即用的数据库实体树组件通过entities、hiddenEntities、contextMenuItems三个核心属性完成数据与交互注入通过bks-entity-expand、bks-entities-request-columns、bks-entity-pin等事件与宿主应用双向协作配合 Schema 自动分组、四种实体类型、置顶、懒加载列与虚拟渲染足以支撑从个人工具到生产级数据库客户端侧边栏的完整需求。需要获取列信息、持久化隐藏/置顶状态或注入自定义菜单时记得在对应事件中更新属性让组件始终保持单一数据源驱动。【免费下载链接】beekeeper-studioModern and easy to use SQL client for MySQL, Postgres, SQLite, SQL Server, and more. Linux, MacOS, and Windows.项目地址: https://gitcode.com/GitHub_Trending/be/beekeeper-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/12 21:12:03 · 阅读 1.2k Beekeeper Studio UI Kit 实体列表（Entity List）组件完全指南：属性、事件与实战用法
Beekeeper Studio UI Kit 实体列表Entity List组件完全指南属性、事件与实战用法【免费下载链接】beekeeper-studioModern and easy to use SQL client for MySQL, Postgres, SQLite, SQL Server, and more. Linux, MacOS, and Windows.项目地址: https://gitcode.com/GitHub_Trending/be/beekeeper-studio实体列表Entity List是 Beekeeper Studio UI Kit 提供的 Web Component用于以可展开/折叠的树形结构展示数据库对象表、视图、物化视图、例程与模式是数据库客户端侧边栏的核心交互组件。本文以 Entity List API 为骨架结合 Entity List 使用指南 与仓库源码完整讲解其全部属性Properties、事件Events以及 Schema 分组、隐藏、置顶、懒加载列、虚拟渲染等实战能力帮助你在自己的数据库工具或管理界面中直接复用该组件。组件概览如何引入 bks-entity-listbks-entity-list是一个通过 define.ts 注册到window.customElements的自定义元素底层由 EntityList.vue 经vue/web-component-wrapper包装而成见 index.ts。也就是说你可以像使用原生 HTML 标签一样在任意页面中使用它并通过属性property赋值和事件监听addEventListener来驱动它bks-entity-list/bks-entity-list script const entityList document.querySelector(bks-entity-list); entityList.entities [{ name: users }]; /script其数据来源是entities属性——一个由 Entity 对象组成的数组。Entity 类型在源码中定义为TableEntity | RoutineEntity | SchemaEntity三种联合类型见 types.ts。Properties组件全部可配置属性以下是 Entity List API 中声明的全部属性名称类型说明默认值entitiesobject[]实体数组详见 Entity API[]hiddenEntitiesobject[]被隐藏的实体数组详见 Entity API[]contextMenuItemsobject[]|function扩展默认右键菜单详见 Context Menuundefined除了 API 文档声明的三个核心属性组件的实际 props 定义entity-list.ts还暴露了以下常用配置项源码中有明确注释说明其用途属性类型说明默认值pinnedEntitiesEntity[]显示在主列表上方的置顶实体数组[]enablePinningboolean是否启用实体置顶功能falsepinnedSortByposition|name置顶实体的排序字段positionpinnedSortOrderstring置顶实体的排序方向ascshowCreateEntityBtnboolean是否显示新建实体按钮true其中pinnedSortBy的可选值在源码中通过SortByValues [position, name]常量约束contextMenuItems同时接受数组或函数两种形态CustomMenuItems类型用于静态或动态生成菜单项。Events组件对外广播的全部事件Entity List API 声明了以下 9 个事件完整列表如下事件名触发时机Event Detailbks-entity-expand实体被展开时{ entity: Entity }bks-entity-collapse实体被折叠时{ entity: Entity }bks-entity-dblclick实体被双击时{ event: MouseEvent, entity: Entity }bks-entity-contextmenu实体被右键点击时{ event: MouseEvent, entity: Entity }bks-entities-request-columns展开实体但其columns为undefined时{ entity: Entity }bks-expand-all点击全部展开按钮且所有实体均已展开时-bks-collapse-all点击全部折叠按钮且所有实体均已折叠时-bks-add-entity-click点击新建实体按钮时{ event: MouseEvent }bks-refresh-click点击刷新按钮时{ event: MouseEvent }这些事件在源码中有类型化定义EntityListEventMaptypes.ts将事件名与CustomEvent的 payload 类型一一绑定例如bks-entity-dblclick: CustomEvent{ entity: Entity }。同时组件还额外派发了bks-entity-pin、bks-entity-unpin、bks-entity-unhide、bks-refresh-btn-click、bks-pinned-entities-sort-by等事件见 EntityList.vue 与事件映射表分别对应置顶、取消置顶、取消隐藏与刷新按钮等交互。典型的事件监听方式entityList.addEventListener(bks-entity-dblclick, (event) { console.log(双击了实体, event.detail.entity); });基本用法从最小实体到带列结构只提供名称的实体最简单的实体只需一个name字段此时默认按table类型渲染const entities [{ name: users }, { name: orders }];携带列信息的实体提供columns后展开实体即可看到列清单每个列由field列名必填和dataType数据类型可选构成对应TableColumn接口Entity APIbks-entity-list/bks-entity-list script const entities [ { name: users, columns: [ { field: id, dataType: integer }, { field: name, dataType: string }, ], }, ]; const entityList document.querySelector(bks-entity-list); entityList.entities entities; /scriptSchemas按模式自动分组给实体对象提供一个schema字符串属性实体就会自动归入对应的模式schema文件夹内同一模式的多个实体共享一个文件夹const entities [ { name: users, schema: public }, { name: orders, schema: public }, ];该行为在 treeItems.ts 的树构建逻辑与 entity-list.spec.ts 中有明确的测试印证当实体携带schema时树中会先插入一个type: schema、entity: { entityType: schema, name: public }的文件夹节点实体节点则以level: 1挂在其下测试还验证了无 schema、单 schema、多 schema 三种场景下树的生成结构。Entity types四种实体类型组件识别table、view、materialized-view、routine四种类型schema类型则由组件在按模式分组时自动生成。示例如下const entities [ { name: users }, // 缺省类型默认按 table 处理 { name: users, entityType: table }, { name: order_summary, entityType: view }, { name: order_summary_2, entityType: materialized-view }, { name: get_order, entityType: routine, returnType: integer, type: function, // function / window / aggregate / procedure }, ];在 models.ts 中例程类型RoutineTypeNames被映射为四种展示名称functionFunction、windowWindow Function、aggregateAggregate Function、procedureStored Procedure。例程实体的完整结构见 Entity APIentityType必须为routinereturnType必填还可选提供returnTypeLength与routineParams每个参数包含必填的name、type与可选的length。Identifier实体标识符的确定规则实体列表默认使用name、schema、entityType三者的组合作为实体的唯一标识符key。如果需要使用自定义标识可在实体对象上添加id属性const users { id: abc123, name: users };从测试用例entity-list.spec.ts可以看到实际 key 的生成形态无 schema 时形如table..users、routine..get_users带 schema 时形如table.public.usersschema 文件夹节点形如schema.public。也就是说标识符按{entityType}.{schema}.{name}的模式拼接提供id后即可绕过这一默认规则。Hiding隐藏实体与 UI 辅助从逻辑上讲只要不把某个实体放进entities数组它就不会显示。但组件还提供了 UI 提示与一个隐藏实体弹窗HiddenEntitiesModal帮助用户统一管理被隐藏的实体列表。启用方式是把要隐藏的实体放进hiddenEntities属性const entities [users, orders]; const hiddenEntities [orders]; entityList.entities entities; entityList.hiddenEntities hiddenEntities; // 监听取消隐藏事件从 hiddenEntities 中移除目标实体 entityList.addEventListener(bks-entity-unhide, (event) { const entity event.detail.entity; const entities hiddenEntities.filter( (hiddenEntity) hiddenEntity ! entity ); entityList.hiddenEntities entities; });在组件模板EntityList.vue中当hiddenEntities非空且没有激活过滤时标题区会显示一个visibility_off徽标与隐藏数量超过 99 显示为99并提供Right click an entity to hide it的悬浮提示与View hidden入口点击后打开HiddenEntitiesModal弹窗弹窗内的取消隐藏通过bks-entity-unhide事件回传给宿主应用。Pinning置顶实体置顶功能可以把常用实体固定显示在主列表上方。启用方式为将enablePinning设为true并把需要置顶的实体放入pinnedEntitiesconst entities [users, orders]; const pinnedEntities [orders]; entityList.enablePinning true; entityList.entities entities; entityList.pinnedEntities pinnedEntities; // 处理置顶追加实体到 pinnedEntities entityList.addEventListener(bks-entity-pin, (event) { const entity event.detail.entity; const entities pinnedEntities.concat(entity); entityList.pinnedEntities entities; }); // 处理取消置顶从 pinnedEntities 中移除实体 entityList.addEventListener(bks-entity-unpin, (event) { const entity event.detail.entity; const entities pinnedEntities.filter( (pinnedEntity) pinnedEntity ! entity ); entityList.pinnedEntities entities; });置顶区域由独立的 PinnedTableList.vue 渲染主列表与置顶列表之间通过split.js提供了可拖拽的分隔条见 EntityList.vue。置顶实体还支持排序bks-pinned-entities-sort-by、bks-pinned-entities-sort-order、bks-pinned-entities-sort-position事件默认按position升序排列可切换为按name排序。Lazy Loading Columns列信息的懒加载开启列懒加载非常简单不设置实体的columns属性或显式将其设为undefined组件就会在需要时主动请求列信息。当实体被展开点击实体图标旁的展开箭头或点击右上角的全部展开按钮时组件会派发bks-entities-request-columns事件宿主应用在此事件中异步获取列并写回实体对象entityList.addEventListener(bks-entities-request-columns, (event) { const entities event.detail.entities; for (const entity of entities) { const columns await fetchColumns(entity); entity.columns columns; } });该机制同样适用于其他表类实体view与materialized-view。借助虚拟渲染组件只会为进入视口的实体发起请求避免一次加载海量列定义。如果想彻底关闭懒加载、阻止事件派发只需把实体的columns设为[]空数组。事件的派发链路在 EntityList.vue 中可以看到handleRequestItemsColumns/handleRequestEntitiesColumns将Item[]或Entity[]映射为{ entities: [...] }后统一 emit。Virtual Rendering虚拟渲染与内置过滤实体列表采用虚拟渲染策略只渲染视口内的实体并在用户滚动时增量更新从而支撑包含大量表/视图/例程的大型数据库侧边栏。组件内部还内置了实体过滤能力sql_tools.ts顶部的过滤输入框按名称做前缀优先、包含次之的两级匹配先收集以查询词开头的实体再收集包含查询词的实体并拼接右上角的过滤菜单则支持按 Tables / Views / Routines 分类开关showPartitions用于控制分区实体parenttype p的显示。过滤激活时标题区会显示shownEntities / totalEntities的计数徽标EntityList.vue。Context Menu扩展右键菜单contextMenuItems属性用于在默认右键菜单基础上追加自定义项它可以是一个菜单项数组也可以是一个函数动态生成菜单项。组件默认内置了Copy Name菜单项将实体名写入剪贴板见 EntityList.vue。右键实体的处理流程在 EntityList.vue 中先派发bks-entity-contextmenu事件再通过useCustomMenuItems合并默认菜单与自定义菜单最后调用openMenu打开菜单。关于自定义菜单项的完整配置方式数组/函数两种形态、菜单项字段结构等请参考 Context Menu 文档。API 速查相关文档与源码索引Entity List API组件属性与事件的官方 API 参考Entity List 使用指南完整的使用示例Entity APIEntity类型定义表/视图/物化视图/例程/模式Context Menu右键菜单扩展指南组件实现EntityList.vue、entity-list.ts、types.ts、treeItems.ts类型定义types.ts、models.ts单元测试entity-list.spec.ts覆盖无 schema / 单 schema / 多 schema 三种树的构建场景小结bks-entity-list是一个开箱即用的数据库实体树组件通过entities、hiddenEntities、contextMenuItems三个核心属性完成数据与交互注入通过bks-entity-expand、bks-entities-request-columns、bks-entity-pin等事件与宿主应用双向协作配合 Schema 自动分组、四种实体类型、置顶、懒加载列与虚拟渲染足以支撑从个人工具到生产级数据库客户端侧边栏的完整需求。需要获取列信息、持久化隐藏/置顶状态或注入自定义菜单时记得在对应事件中更新属性让组件始终保持单一数据源驱动。【免费下载链接】beekeeper-studioModern and easy to use SQL client for MySQL, Postgres, SQLite, SQL Server, and more. Linux, MacOS, and Windows.项目地址: https://gitcode.com/GitHub_Trending/be/beekeeper-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考