在 React Vite 项目中快速接入 beekeeperstudio/ui-kitBeekeeper Studio UI 组件库实战指南【免费下载链接】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导读apps/ui-kit/examples/react是 Beekeeper Studio 官方提供的 React 示例模板演示如何在 Vite React 环境中使用beekeeperstudio/ui-kit组件库。读完本文你将掌握从零初始化项目、引入组件库、封装自定义元素Custom Element、处理组件事件与生命周期以及通过 CSS 变量深度定制表格、SQL 编辑器等组件样式的完整实战方案可直接复制到自己的 React 应用中。快速开始两条命令跑通示例原文档给出的 Quickstart 极其精简核心只有两条命令。在仓库根目录下进入示例目录执行即可cd apps/ui-kit/examples/react yarn install yarn devyarn install安装依赖。示例项目通过package.json中的beekeeperstudio/ui-kit: link:../..以yarn link 方式直接引用仓库内的 UI Kit 源码见 apps/ui-kit/examples/react/package.json因此不需要发布到 npm 即可本地调试改动 UI Kit 源码后刷新页面即可看到效果。yarn dev启动 Vite 开发服务器默认启用 HMR模块热更新。启动后浏览器中会看到一个同时渲染 Vite、React、Beekeeper Studio 三个 Logo 的演示页下方依次展示 Text Editor、SQL Text Editor、Table、Entity List、Data Editor 五组组件实例。该模板的作用正如原文档所述提供了一套开箱即用的最小化配置让 React 与 Vite 的 HMR、ESLint 规则以及 Beekeeper Studio UI Kit 同时工作起来是后续将 UI Kit 集成进自身项目的最佳起点。示例项目结构一页看懂工程骨架apps/ui-kit/examples/react是一个标准的 Vite React TypeScript 工程结构如下examples/react/ ├── index.html # 应用入口 HTML ├── main.tsx # 根目录的入口与 src/main.tsx 配套 ├── package.json # 依赖与脚本 ├── tsconfig.json # TS 配置 ├── tsconfig.app.json # 应用侧 TS 配置 ├── tsconfig.node.json # Node 侧vite.configTS 配置 ├── vite.config.js / vite.config.ts ├── eslint.config.js # ESLint 规则 ├── yarn.lock ├── public/vite.svg └── src/ ├── main.tsx # 实际运行入口挂载 UI Kit 与全局样式 ├── App.tsx # 页面骨架 ├── App.css / index.css # 全局样式 ├── custom-theme.css # 组件主题定制示例 ├── Components.tsx # 组件演示总编排 ├── data.ts # 演示数据entities/tables └── Bks*.tsx # 各组件在 React 中的封装示例开发脚本定义在 package.json命令作用yarn dev启动 Vite 开发服务器含 HMRyarn build使用 Vite 构建生产产物yarn lint运行 ESLint 检查yarn preview本地预览构建产物依赖方面运行时仅需beekeeperstudio/ui-kit、react、react-domReact 18.3.x开发期使用vitejs/plugin-react、TypeScript 5.4、ESLint 9 与 react-hooks / react-refresh 插件是一套非常克制的最小配置。接入核心main.tsx 中如何激活 UI KitUI Kit 的接入方式与普通 npm 组件库完全不同——它不导出 React 组件而是导出一系列Web Components自定义元素。因此入口文件的引入顺序至关重要见 src/main.tsximport { StrictMode } from react import { createRoot } from react-dom/client import beekeeperstudio/ui-kit; // 1. 注册所有自定义元素副作用导入 import beekeeperstudio/ui-kit/style.css; // 2. 引入组件库基础样式 import ./index.css import ./custom-theme.css // 3. 引入自定义主题覆盖 import App from ./App.jsx createRoot(document.getElementById(root)!).render( StrictMode App / /StrictMode, )这里有两个关键点必须执行副作用导入import beekeeperstudio/ui-kit负责在浏览器中注册bks-table、bks-text-editor、bks-sql-text-editor、bks-entity-list、bks-data-editor等自定义元素。若遗漏该行后续 JSX 中使用bks-table /将不被浏览器识别。样式文件顺序敏感先引入style.css提供组件的默认主题再引入custom-theme.css做覆盖保证自定义变量能按 CSS 层叠规则生效详见主题定制一节。五类核心组件在 React 中的封装模式由于 UI Kit 是自定义元素而非 React 组件示例项目总结了一套通用封装范式用ref拿到 DOM 元素通过属性property传数据、通过事件event收回调并在卸载时销毁内部 Vue 实例。下面逐一解读示例中的五个封装。1. 表格组件 BksTablebks-table见 src/BksTable.tsx。其要点是等待组件内部初始化完成后再写入数据const tableRef useRefTableElement(null as unknown as TableElement); useEffect(() { tableRef.current document.createElement(bks-table) as TableElement; const handleInitialized () setInitialized(true); tableRef.current.addEventListener(bks-initialized, handleInitialized); containerRef.current?.appendChild(tableRef.current); return () { tableRef.current.removeEventListener(bks-initialized, handleInitialized); tableRef.current.vueComponent.$destroy(); // 手动销毁内部 Vue 实例 containerRef.current?.removeChild(tableRef.current); }; }, []); useEffect(() { if (!initialized) return; tableRef.current.columns columns; // 传入列定义Column[] tableRef.current.data data; // 传入行数据BaseData }, [initialized, columns, data]);关键点组件通过document.createElement动态创建并挂载到容器 div而不是直接在 JSX 中书写标签数据通过columns/data两个属性注入列定义和行数据来自演示数据集data.ts由getEntities()提供组件内部由 Vue 实现这也是销毁时需要调用vueComponent.$destroy()的原因对外暴露bks-initialized事件表示就绪因为 UI Kit 的 Vue 生命周期不感知 React 渲染React 严格模式StrictMode下卸载时若不手动$destroy()会出现重复挂载或内存泄漏。2. SQL 文本编辑器 BksSqlTextEditorbks-sql-text-editor见 src/BksSqlTextEditor.tsx。它演示了编辑器与外部状态的双向同步const [text, setText] useState(select * from users u\nwhere u.id 1;); useEffect(() { sqlTextEditorRef.current document.createElement(bks-sql-text-editor) as SqlTextEditorElement; sqlTextEditorRef.current.value text; // 初始值 sqlTextEditorRef.current.addEventListener(bks-initialized, handleInitialized); sqlTextEditorRef.current.addEventListener(bks-value-change, handleUpdateValue); ... }, []); function handleUpdateValue(event) { if (text event.detail.value) return; // 事件载荷在 detail.value setText(event.detail.value); }写入方向通过value属性注入初始 SQL 文本读取方向监听bks-value-change自定义事件event.detail.value携带最新编辑内容回写到 React state还支持传入entities属性表结构元数据供编辑器做表名/字段的自动补全——这正是 Beekeeper Studio 主应用 SQL 编辑器能力的组件化呈现。3. 实体列表 BksEntityListbks-entity-list见 src/BksEntityList.tsx。它演示了事件驱动的组件间联动双击左侧实体列表项右侧表格切换显示对应表的数据。function handleItemDblClick(event) { const idx ref.current.entities.findIndex( (entity) entity event.detail.entity // 通过对象引用比对定位 ); if (idx -1) onSelectEntity(idx); // 回调父组件切换选中表 }数据注入entities属性接收Entity[]事件接收监听bks-entity-dblclickevent.detail.entity即被双击的实体对象事件载荷携带的是对象引用因此可通过findIndex直接定位下标再通过onSelectEntity回调把选中状态提升到Components.tsx的useState中驱动 BksTable 重新渲染——这是数据向上、事件向上的典型 React 数据流。4. 数据编辑器 BksDataEditorbks-data-editor见 src/BksDataEditor.tsx。它演示了查询提交事件的响应式处理模拟了输入 SQL → 执行 → 渲染结果集的完整链路function handleQuerySubmit(event) { ref.current!.setTable({ name: result, entityType: table, columns: [ { field: id, dataType: integer }, { field: name, dataType: string }, ], data: [{ id: 1, name: Alice }, { id: 2, name: Bob }], }); } useEffect(() { ref.current?.addEventListener(bks-query-submit, handleQuerySubmit); ... ref.current.entities tables; // 传入表结构供编辑器感知 schema }, [tables]);监听bks-query-submit事件模拟执行查询通过ref.current.setTable(...)把模拟结果集写回组件驱动结果表格渲染该模式可直接替换为真实场景在回调中执行 SQL、拿到行数据后调用setTable展示结果即构成了一个最简SQL 查询台。5. 纯文本编辑器 BksTextEditorbks-text-editor见 src/BksTextEditor.tsx。其用法与 SQL 编辑器一致value属性 bks-value-change事件另外代码中保留了一段被注释的Language Server ProtocolLSP客户端配置示例可用于接入语言服务器实现类型提示、诊断等能力// textEditorRef.current.lsConfig { // languageId: typescript, // transport: { wsUri: ws://localhost:3000/server }, // rootUri: /home/user/dev/.../fixtures/, // documentUri: /home/user/dev/.../fixtures/index.ts, // }当需要语法分析、自动补全等高级能力时取消注释并配置wsUri指向你的 LSP 服务器即可。事件与生命周期速查表综合以上五个封装可以整理出通用集成规则组件自定义元素数据属性关键事件表格bks-tablecolumns/databks-initializedSQL 编辑器bks-sql-text-editorvalue/entitiesbks-initialized/bks-value-change实体列表bks-entity-listentitiesbks-entity-dblclick数据编辑器bks-data-editorentitiesbks-query-submit配合setTable()文本编辑器bks-text-editorvalue/lsConfigbks-initialized/bks-value-change所有组件都暴露bks-initialized初始化完成、vueComponent内部 Vue 实例两个约定前者用于等就绪再传数据后者用于卸载时手动销毁。这是 UI Kit 面向 React 等框架设计的统一契约。主题定制用 CSS 变量重绘组件外观示例的 src/custom-theme.css 是一份完整的主题覆盖示范。它不修改组件源码而是利用组件的 CSS 变量接口重定义配色例如 SQL 编辑器的语法高亮.custom-theme .BksSqlTextEditor { --bks-text-editor-bg-color: #00ff00; --bks-text-editor-fg-color: #ff0000; --bks-text-editor-keyword-fg-color: #ff00ff; --bks-text-editor-string-fg-color: #00ffff; --bks-text-editor-number-fg-color: #ffff00; --bks-text-editor-comment-fg-color: #ff8800; --bks-text-editor-variable-fg-color: #8800ff; --bks-text-editor-property-fg-color: #ff0088; --bks-text-editor-bracket-fg-color: #88ff00; --bks-text-editor-selected-bg-color: rgba(255, 0, 0, 0.5); }表格组件的变量覆盖了表头、行、单元格、排序器、范围选择等十余个维度.custom-theme .BksTable { --bks-table-bg-color: #ffff00; --bks-table-header-bg-color: #ff8800; --bks-table-row-odd-bg-color: #ff88ff; --bks-table-cell-bg-color-hover: #00ff00; --bks-table-cell-bg-color-selected: #ff00ff; --bks-table-sorter-fg-color-active: #00ffff; --bks-table-range-border-color: #ff0088; }同时也可直接覆盖组件内部的样式类如tabulator-header、.primary-key:before以及实体列表、数据编辑器按钮等结构样式。这套机制意味着无需 fork UI Kit 源码即可让组件外观与宿主应用的品牌色、暗色主题完全一致。在Components.tsx中默认主题与自定义主题的两个BksDataEditor被分别渲染在.card与.card.custom-theme容器中方便对比效果。从示例走向生产接入流程总结将上述经验迁移到自己的 React 工程完整流程是安装在任意 React 项目中执行npm install beekeeperstudio/ui-kit组件库安装方式见 apps/ui-kit/README.md或像示例一样通过link:引用本地源码进行开发调试引入在入口文件按顺序导入beekeeperstudio/ui-kit与beekeeperstudio/ui-kit/style.css再导入自己的主题覆盖样式封装按上文五类组件的模式用useRefuseEffect封装为 React 组件创建元素 → 监听bks-initialized→ 注入属性 → 监听业务事件 → 卸载时vueComponent.$destroy()联调数据编辑器可接入真实查询逻辑SQL 编辑器可通过entities注入表结构开启补全文本编辑器可通过lsConfig连接 LSP 服务器构建与检查使用yarn build产出生产包yarn lint借助 ESLint 9 与 react-hooks / react-refresh 插件维持代码质量。组件库源码位于 apps/ui-kit/lib其官方文档目录 apps/ui-kit/docs 提供了各组件 API、自定义属性与事件约定的完整参考如 getting-started.md需要更细粒度能力时可对照查阅。示例中还包含一份 Vite 环境可直接使用的开发配置vite.config.ts 与 vite.config.js以及完整的 TypeScript 工程配置tsconfig.json可作为真实项目脚手架的直接参考。【免费下载链接】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），仅供参考