# @columenlabs/lumen-ui 中文文档 规范地址：https://npmcn.com/package/%40columenlabs/lumen-ui/ 版本：0\.1\.219 npm 元数据更新时间：2026-11-09T05:44:26.854Z 中文译文更新时间：2026-11-10T11:32:21.065Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40columenlabs/lumen-ui 原文对照：https://npmcn.com/package/%40columenlabs/lumen-ui/?lang=original 项目主页：https://github.com/columenlabs/lumen 源码仓库：https://github.com/columenlabs/lumen ## 关键信息（来自 npm 元数据） - 包体积（解压后）：2.6 MB，463 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - 运行依赖：39 个 - peer 依赖：react ^19\.0\.0，react-dom ^19\.0\.0，@tanstack/react-query ^5\.103\.2，@tanstack/react-router ^1\.170\.39 - 首次发布：2026-10-22T18:30:31.551Z - 最新版本发布：2026-11-09T05:44:26.604Z - 近 30 天下载量：51271（2026-10-11 至 2026-11-09，npm 官方下载统计） - 已发布版本数：232（近 12 个月 232 个） ## 中文简介 路门:共享反应组件(框架,视图,部件,图表,抽屉). ## 安装 ```sh npm install @columenlabs/lumen-ui ``` 也可以使用：`pnpm add @columenlabs/lumen-ui`、`yarn add @columenlabs/lumen-ui`、`bun add @columenlabs/lumen-ui` ## README # 校对:soup Lumen's React 组件用于数据应用:应用程序框架,页面和视图在您行上,部件,图表,抽屉和拾取器上,都在一个主题上. 你给它数据和视图配置;它画出屏幕。 建造在 [阴影/ ui](https://ui.shadcn.com/) (Radix UI, Base UI, Tailwind CSS 4. ). 它的视野模式是 [`@columenlabs/lumen-ui-types`](https://www.npmjs.com/package/@columenlabs/lumen-ui-types)。 。 。 . - 文档和活例: [https://lumen.columenlabs.com/docs/ (中文(简体) )](https://lumen.columenlabs.com/docs/) - 对于代理人: [https://lumen.columenlabs.com/llms.txt (中文(简体) )](https://lumen.columenlabs.com/llms.txt) - 资料来源: [https://github.com/columenlabs/lumen (中文(简体) )](https://github.com/columenlabs/lumen) (单位:千美元)`packages/ui`麻省理工学院. ## 安装 将两个软件包钉入同一个准确版本. ```bash bun add @columenlabs/lumen-ui @columenlabs/lumen-ui-types bun add react react-dom @tanstack/react-query @tanstack/react-router # peers bun add -d tailwindcss @tailwindcss/vite tw-animate-css shadcn ``` ## 设置 `src/index.css`数字 : ```css @import "tailwindcss"; @import "tw-animate-css"; @import "shadcn/tailwind.css"; @import "@columenlabs/lumen-ui/theme.css"; @source "../node_modules/@columenlabs/lumen-ui/dist"; /* your accent, per app (LumenShell sets data-app on ) */ :root[data-app="myapp"] { --primary: oklch(0.55 0.15 160); } /* optional: numbers in the text font instead of mono (code stays mono via `font-code`) */ :root[data-app="myapp"] { --num-font: var(--app-font); } ``` 一开始,在事情发生之前, 告诉工具包你的应用程序。 工具箱没有产品名称: 你的名字和数据在这里. ```ts import { configureLumen } from '@columenlabs/lumen-ui'; import { registerDomains } from '@columenlabs/lumen-ui-types/registry'; configureLumen({ prefsCookie: 'myapp_prefs' }); // where display preferences live registerDomains({ /* your joins, sources and domain keys */ }); ``` 在外壳中环绕路线 : ```tsx import { LumenShell } from '@columenlabs/lumen-ui'; } nav={nav} user={{ email, name }}> ``` 你自己的零件进去了 `LumenShell`槽数 : `brand`, (中文(简体) ), `headerActions`, (中文(简体) ), `panel` (一个辅助小组,如助理), `wrap` (提供方围绕页面), `shared`, (中文(简体) ), `profile` (配置菜单)和 `statusEnd` (状态栏右端). 使用 `createDeskQueryClient()` 对于该应用的TanStack查询客户端:数据保持新鲜5分并缓存了30分. ## 里面的东西 **帧.** `LumenShell` (边栏只包含图标倒塌和一个抽屉在电话,头条,状态栏,设置,配置菜单,QQK Find), `LumenAppSwitcher` 财务报告和审定财务报表 `LumenSuiteSwitcher` (组,其他站点的应用程序,一个从地址读取的列表), `WhatsNew` (在抽屉里放纸条), `TasksButton` 财务报告和审定财务报表 `TasksProvider` (背景工作在标题中), `NotificationsSettings`, (中文(简体) ), `McpSettings`,登录屏幕(`LumenAuthStage`, (中文(简体) ), `LumenSecondStep`, (中文(简体) ), `LumenSignInMethods`, (中文(简体) ), `LumenBackupCodes`, (中文(简体) ), `LumenBotCheck` 为云雀花转弯, `authErrorText` 以白话盟誓, `StatusHealth`, (中文(简体) ), `LumenBoundary` (在卡片里留有坠机), `LumenPageState` (装入、空出和出错), `lumenToast`。 。 。 . **页面与视图.** `LumenLayout` (一个视图配置的一页牌:过滤器、瓷砖、部件; 通过时编辑布局并编辑部件 `onConfigChange`; 带有 `header: false` 是它唯一的躯体, `LumenGrid` (下面的六柱网格), `LumenView` 财务报告和审定财务报表 `LumenViewCard` (一个过滤您所装入的行、 组、 活字和总行的表格), `LumenTable`, (中文(简体) ), `LumenTokenizedFilter`, (中文(简体) ), `LumenWidget` 财务报告和审定财务报表 `LumenSavedWidget` (每张卡片都坐入框中,有其链接平方和控件), `LumenCard` (一个数字及其行), `LumenPager`, (中文(简体) ), `DetailsTable`, (中文(简体) ), `LumenTree`, (中文(简体) ), `LumenCalendar` (活动按月、周或议程,在一个时区), `LumenBoard` (按阶段分列的项目), `useAppView` (一页,每人可以更改并重置). **图.** `LumenChart` (一个或多个符号价格,附有指标), `LumenEChart`, (中文(简体) ), `LumenGeoMap`增长和价格图, `StackedBars`, (中文(简体) ), `StackedColumns`, (中文(简体) ), `TimeLines` (随时间而行,带有可选的右轴), `RankedBars` (以各栏占总分或一栏之分,并取一空相. **拾取器和相板.** `LumenSelector` (每个拾取者), `LumenDrawer` 与 `DrawerSection` (桌面上的一个侧面板,电话上的一个工作表), `LumenTabs`, (中文(简体) ), `LumenConfirm` (毁灭确认), `LumenForm`, (中文(简体) ), `LumenDateInput`, (中文(简体) ), `LumenChoice`, (中文(简体) ), `LumenSecret`, (中文(简体) ), `LumenFileField` (投放或选择文件), `RenameField`, (中文(简体) ), `ResetButton`, (中文(简体) ), `SaveButton` 与 `FormIssue` (但说它不能), `IconPicker`, (中文(简体) ), `LumenPlayer` (视频,音频,或翻过音频的幻灯片,有章节,后面的笔录和回放). **初发心相.** 阴影部分在下面 `@columenlabs/lumen-ui/ui/*` (单位:千美元)`ui/button`, (中文(简体) ), `ui/badge`, (中文(简体) ), `ui/input`,(......)和 `theme.css` (轻而暗之相. 每一个导出,它的道具和一个例子都在 [文档](https://lumen.columenlabs.com/docs/) 内 [`llms-full.txt`](https://lumen.columenlabs.com/llms-full.txt)。 。 。 . ## 套装要遵循规则 应用软件也要遵循 - 选手是 `LumenSelector`边板 `LumenDrawer`选项卡 `LumenTabs`,破坏性确认 `LumenConfirm`; 用于原始的 `ui/*` 只有在没有卢门部分合适时才进行. - 每张牌都坐着 `LumenBoundary`,所以一个坠机永远不会空出一页. - 数字使用表格数字并用正负 `−`; 损益总是显示一个标志或箭头. - 页面头号是度量牌: `TileRow` 联 合 国 `Tile` (或 `TileToggleGroup` 当他们选择页面显示的内容时 `fill` 所以他们共用一行,每一行 `spark` 进入了它的日常历史。 别为此自造出出相. - 列宽: 第一列( 一行名) 仅长到 `--lead-col-max` (18rem,主题.css;通过它,单元格在一行上截取并完整地显示在悬浮上(一个被制成的单元格会带出自己的悬浮卡). 将其它列与字段并列 `maxWidth` (单位:千美元)`'12rem'`),或用 `maxWidth: false`中,将名称放入 `truncate` 因此,椭圆落在它上, 而不是在它的芯片之后. - 行从来收. 每行(数据,组,子组,总数)以每行宽度读取一行. 在一通电话上,每行是一行一行卡:其名(椭圆形,盘旋上为全名)和右一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一 其他值在行的抽屉或面板上. 通过排序( 排序) 或标记其他显示来选择哪个值 `hideOnPhone`。 。 。 . - 列对齐是表格的,不是单元格的. 文本左, 数字右, 和数字列有一个右边缘, 用于标题、 值、 破折叠和 Total . `UnitValue` 在数字后将单位置于一个固定的槽中(`--unit-slot`2rem)及其状态点 刚刚留下的号码。 在卢门维尤的一桌 `UnitValue` 用一栏标记它(`data-units` ,通过 `UnitColumns` 上下文和单元格的 `data-col`;主题.css后将柱子右侧的沟槽从槽上拓宽并挂起其中的每个单元. 这么平平 `—`, (中文(简体) ), `Free` 或者说 `$0.21` 一个应用程序画在同一列 坐在数字的边缘, 标题坐过数字。 不要手动放置单位、点或贴花来排出一列;如果一列被关闭,请通过 `UnitValue`。在卢门维尤桌外(悬牌、平板) `UnitValue` 保持它的槽内线. - 计数列(使用量与备抵)显示每个单元格一个数字,其中 `UnitValue` (右对齐的编号,固定的哑声单位插槽,状态点),永不 `value [pct]`。通过实地提供两种读取 `showAs` (数额/ 津贴百分比,按编辑视图中每栏选取,作为 `shows`); 大小(存储)和上限计数的股份的默认金额. 将其他读数,津贴和费用公式放入悬浮卡. 使用总数 `rollRender`: 与其单位的总和; 份额是各行的总和, 而不是百分数的总和. - 一个浮起的块状活性条 在一个表格的选择上: 应用清除选择并去去行;土司的"Undo"恢复了修改,而不是选择. 取消保留选择 . - 列行中的栏:使用 `ShareMeter` (固定的音轨,固定的右对齐的编号),从不使用其标签大小的栏. - 共享的上限由谁使用(一个账户的贴有标签的贴有): `ShareMeter segments={[{ value, label }]}` 名称每个部分在栏杆盘旋中的分数;栏杆本身保留了一种颜色,其级别,所以颜色总是说它是多满的. 卷起这样的一行 `poolShare(rows, { pool, used, cap })` 在田间 `rollRender`: 游泳池的股份是其排行超过上限的用法(从未达到或最大超过其自己的百分比),一个跨多个游泳池的团体读取最完整的一个(a`top`) (中文(简体) ). - 仪表级是工具箱的 而不是应用程序的 用法共享读取 `ok` 75%以下, `watch` (琥珀)从75%, `alert` (橙色)从90%, `over` (红色)从100%;超过100% `ShareMeter` 一直放满,孵出的一个树茎会从顶部的一滴滴滴上溢出,最高可达+50%. 保健份额`kind="health"`:上行时间,成功率)读取绿色为99%及以上,琥珀从95%取出,红色低于95%. `ShareMeter` 从股份取出颜色, 除非你通过 `color`· ; `UnitValue share={0.8}` 从琥珀上标出它的编号和点( 绿色数字保持不变); 进度卡跟随相同的关卡 。 对于任何其他标记(一个点,一个芯片,一个"最相近的盖"的单元格) `meterLevel(share, levels, kind)` 颜色与 `METER_LEVEL_COLOR` 或者说 `meterValueTone(share)`。每个应用程序覆盖 `configureLumen({ meterLevels: { watch: 0.8 }, healthLevels: { watch: 0.995 } })` (每个关卡都可以单独移动)或每公尺 `levels`不要手动滚动 `share >= 0.75` 检查. - Pace(时间到一个上限,按最近的速度)是工具包的: `burnRate(samples, { per, gauge })` 超过窗口的完整样本(小时或每日) `7d`,则 `timeToCap(rate, used, cap, resetInHours)`窗口的中位数等于中位数(`spikes` 说出多少;一连串热样品都算数。 带它 `TimeToCap` (单位:千美元)`in 2h 05m`, (中文(简体) ), `At cap`, (中文(简体) ), `Resets first`· ; `short` 在电话上),被测量仪重置位置的高度所显示,并用 `PaceWindowPicker` (6h、12h、24h、7d)页头; `usePaceWindow()` 在所有地方读取相同的选择, 保存在浏览器的浏览器中( name`setDefaultPaceWindow` 设置应用程序的默认值). 在大多数时数为空(中位数为0)的情况下,单个非零小时计为0,而窗口的使用量太少(`timeToCap(..., { minTotal })`,默认上限的0.1%)是 `thin`:没有时间去盖. 不要手卷ETA或窗口切换. - 期间(本周与上一周)的变动是: `trendChange(now, prev, { minBase })` 由 `TrendValue`数字 : `▲ 12%` 在足够早的时期, 明显的差异 `▲ +3` 当它处于或低于 `minBase`, (中文(简体) ), `▲ >10×` 过去十次。 超过近空基线的%会误导;永远不会显示. - 表行为一行. 单元格显示一个值(最多有一个小条或标记);其他任何值(其他的度量,备抵,分解)都用悬浮工具提示,从不用堆叠的文字或子行. - 图表颜色是主题符号(`var(--chart-1)`, (中文(简体) ), `useChartTokens()`),从未选择一个主题; `LumenEChart` 决定 `var(--…)` 在它的选项中,如此闪烁的光和暗读. - "无标签"过滤器来自: `LumenTokenizedFilter` 在所有文本字段中标出“无”行,有些行没有值(一个) `empty` 符号);不要为它添加自己的切换. - 比较少的分页行:最多每张卡一行分页;更窄的剪接(一种产品,一种类型)是行 `LumenTokenizedFilter`,然后与一个链接打开带有过滤芯片的标签. - 一个被选中的侧边栏:给每个导航项目自己的路由,让打开的父目录看起来中立. - 每一个应用程序都有新内容:通过 `releases="/api/releases"` 改为 `LumenShell`由lumen -ship's服务 `listReleases`。 。 。 . - 被窗体检查所屏蔽的保存是 `SaveButton` 列出每个问题,从不赤裸 `disabled`。 。 。 . ## 通知 Charts使用TradingView轻量级 ChartsTM并关闭其标志. 请与 [https://www.tradingview.com/ (中文(简体) )](https://www.tradingview.com/) 在你的应用程序(见通知)的某个地方. ## 版本数 0.x:任何未成年人可以断裂到1.0. 每次和鲁门合并 `main` 发布每个 Lumen 软件包的下一个补丁;参见 [释放](https://github.com/columenlabs/lumen/releases)。 。 。 . ## 常见问题 ### @columenlabs/lumen-ui 是什么？ 路门:共享反应组件\(框架,视图,部件,图表,抽屉\)\. ### 如何安装 @columenlabs/lumen-ui？ 在项目目录运行 npm install @columenlabs/lumen-ui，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^19\.0\.0）、react-dom（^19\.0\.0）、@tanstack/react-query（^5\.103\.2）、@tanstack/react-router（^1\.170\.39）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @columenlabs/lumen-ui 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @columenlabs/lumen-ui 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @columenlabs/lumen-ui 可以商用吗？ @columenlabs/lumen-ui 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @columenlabs/lumen-ui 的下载量有多少？ 根据 npm 官方下载统计，@columenlabs/lumen-ui 在 2026/10/11 – 2026/11/09 这 30 天内被下载 51,271 次，日均约 1,709 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @columenlabs/lumen-ui 还在维护吗？ 最新版本 0\.1\.219 发布于 2026/11/09（1 天前）；至今共发布 232 个版本，其中过去 12 个月发布了 232 个；首次发布于 2026/10/23。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。