# @cinesend/ui-kit 中文文档 规范地址：https://npmcn.com/package/%40cinesend/ui-kit/ 版本：0\.5\.5 npm 元数据更新时间：2026-11-02T22:17:09.825Z 中文译文更新时间：2026-11-09T16:22:17.880Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40cinesend/ui-kit 原文对照：https://npmcn.com/package/%40cinesend/ui-kit/?lang=original 项目主页：https://github.com/BitCine/cinesend-ui-kit#readme 源码仓库：https://github.com/BitCine/cinesend-ui-kit ## 关键信息（来自 npm 元数据） - 包体积（解压后）：1.3 MB，69 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - 运行依赖：1 个 - peer 依赖：react \>=18\.2 \<20，sonner ^2\.0\.7，react-dom \>=18\.2 \<20，@phosphor-icons/react ^2\.1\.10 - 首次发布：2026-09-25T19:46:04.459Z - 最新版本发布：2026-11-02T22:17:09.676Z - 近 30 天下载量：2260（2026-10-10 至 2026-11-08，npm 官方下载统计） - 已发布版本数：11（近 12 个月 11 个） ## 中文简介 共享反应组件,设计令牌,以及CineSendapps的CSS. ## 安装 ```sh npm install @cinesend/ui-kit ``` 也可以使用：`pnpm add @cinesend/ui-kit`、`yarn add @cinesend/ui-kit`、`bun add @cinesend/ui-kit` ## README # CineSend UI 工具包 为 CineSend apps 共享反应组件,令牌和 CSS. 这是 **没有** 一个应用:没有产品屏幕,没有API呼叫,没有应用逻辑. 发布到 npm 为 [`@cinesend/ui-kit`](https://www.npmjs.com/package/@cinesend/ui-kit)。 GitHub 重播为 `BitCine/cinesend-ui-kit`没有 `BitCine/ui-kit` 复发. ## 安装 ```bash npm install @cinesend/ui-kit ``` ```tsx import { Button, TextField } from "@cinesend/ui-kit"; import "@cinesend/ui-kit/styles.css"; ``` 样式表是一个单独的切入点, 必须导入一次, 靠近您的应用根 。 它没有被捆绑在联署材料中. 本地开发( 在应用程序旁边加上这个 repo ): ```json "@cinesend/ui-kit": "file:../cinesend-ui-kit" ``` 从 a 安装 `file:` 路径服务已建 `dist/`运行 `npm run build` 换了装备后再来. ### 从 git 安装 更古老的路径依然有效 ```json "@cinesend/ui-kit": "github:BitCine/cinesend-ui-kit#staging" ``` `dist/` 没有承诺,所以一个 git 安装通过 `prepare` 剧本. 这意味着消费者下载了这个包 依赖性,在每一个 `npm ci`. 预选 npm 释放; 此路径存在, 因此应用程序不会被迫在锁步中迁移 . ## 同伴依赖关系 应用程序必须提供: - `react` 财务报告和审定财务报表 `react-dom` (>=18.2 < 20) - `@phosphor-icons/react` ^2.1.10 (中文(简体) ) - `sonner` ^2.0.7 (中文(简体) ) 运行时间依赖 : `@base-ui/react`。 。 。 . ## 数据密集组件 这些工具箱大多是花砖和以文件为导向的,这就是文件与屏幕 需要帮助. `Table`, (中文(简体) ), `Pagination`, (中文(简体) ), `Badge` 页面状态用于数据密集度 内部工具,他们共享一条规则 值得说明一次: **他们描述 页面中包含服务器持有的数据,并永远不要重新解释.** ![The Table component](https://npmcn.com/package/%40cinesend/ui-kit/docs/screenshots/table-default.png) 排序, 包含行选择和每个单元格中的真实控制, 光和暗: ![Table with sorting and selection](https://npmcn.com/package/%40cinesend/ui-kit/docs/screenshots/table-interactive.png) ![The same table in dark mode](https://npmcn.com/package/%40cinesend/ui-kit/docs/screenshots/table-interactive-dark.png) - **`Table`** 没有什么 可排序标题报告它想要的种类 结束 `onSortChange`; 拥有查询答案的人。 交给的行 它是一个更大的一页集, 所以命令它们 在组件 排序页面而不是数据,并不同意两者的总数 下一页 选择被控制 出于同样的原因, 并只覆盖屏幕上的密钥. `caption` 需要: 它是表格的可访问名称,是视觉的 藏起来 没有它,屏幕阅读器宣布"表",没有别的. **`onRowClick` 是一个指针快捷键,不是行的唯一路线.** 保留行 他们的 `row` 角色,因此它们不能聚焦,没有被宣布为 控件 —— 在单元格中设置一个真实的链接或按钮并让行 点击复制。 单击从该控件开始的(或任何其他) 行中的交互式元素)不同时运行行快捷键,所以 动作起火一次而不是两次。 显而易见的另一种选择, `role="button"` 加号 `tabIndex` 编辑 ``,故意避免:它凌驾于 隐含行角色,让每个单元格没有有效的行所有者,断开 屏幕读取器的表格导航,并嵌入选择的复选框 在一个按钮内. **`stickyHeader` 需要将高度绑入表根本身**,哪个 这是什么 `className` 用于: ```tsx ``` 不是在包装上. `.cs-table` 携带 `overflow-x`,当一个 轴不是 `visible` 其他计算为 `auto` 这样啊 `.cs-table` 这是 最近的滚动容器 。 将包装包捆起来,然后将页头滚动 和桌子一起看的 看上去就像道克一样 工作时. **虚拟化是故意超出范围的.** 每行给定的是 已经完成。 进入高的百分百的空间很舒适, 覆盖一页 管理列表 。 屏幕需要数以万计的一行一行 不同组件, 而不是旗子在此. - **`Pagination`** 计数,而不是一个响应信封——每个后端 以不同方式拼写其页形, 以及理解一个的组件 框架 `meta` 是下一个应用在周围工作。 给我 `pageSize` 财务报告和审定财务报表 `onPageSizeChange` 用于逐行选择; 更改大小 哪一行在哪一页, 所以回到第一页. ![Pagination with a rows-per-page select](https://npmcn.com/package/%40cinesend/ui-kit/docs/screenshots/pagination-page-size.png) - **`TableToolbar`** 持有 `TableSearch`, (中文(简体) ), `TableSortMenu` 财务报告和审定财务报表 `TableFilters`。 。 。 . 喜欢 `Table`,它们报告用户要求的,并且不更改行:保留 它们的值位于构建查询的状态,然后在 他们改变. ![Table toolbar with the filters open](https://npmcn.com/package/%40cinesend/ui-kit/docs/screenshots/table-toolbar-filters.png) ![Table toolbar with the sort menu open](https://npmcn.com/package/%40cinesend/ui-kit/docs/screenshots/table-toolbar-sort.png) - **`Badge`** 使用语义语调,而不是状态. 绘制自己的词汇 进入呼叫站点的五吨位 然后返回 `neutral` 页:1 任何无法识别的东西, 所以一个不熟悉的状况 仍然显示在比较 而不是掉下来。 (`WorkspaceBadge` 是装饰性的起首部分,旁边是 工作空间名称; 是 `aria-hidden` 而不是这个。 ) - **`Alert`** 是一个属于旁边内容的讯息:失败 惟有在表单上方的警告。 这不是页面状态( 使用 `EmptyState` 或者说 `ErrorState` 而不是一个敬酒。 错误和警告是 立即宣布, 其余的礼貌. ![Alert tones in light mode](https://npmcn.com/package/%40cinesend/ui-kit/docs/screenshots/alert-tones.png) ![Alert tones in dark mode](https://npmcn.com/package/%40cinesend/ui-kit/docs/screenshots/alert-tones-dark.png) - **`ProgressBar`** 将其值夹到 0- 100 并读取 `NaN` 作为0,所以 将字节除以尚未到达的总数是安全的. **`Image`** 财务报告和审定财务报表 **`Poster`** 当图像是时, 以固定比例显示占位符 缺少或未加载, 因此布局不会跳出 . ![Progress bar and image states](https://npmcn.com/package/%40cinesend/ui-kit/docs/screenshots/progress-bar-and-image.png) - **`FileUpload`** 是一个跳伞区和一个按钮, 仅此而已:它给你 第一个文件被选中或删除,没有网络工作。 运行传输 你自己,然后喂回来 `uploading` 财务报告和审定财务报表 `error`。 。 。 . `accept` 使用输入 属性的语法, 在浏览器没有时也会在跳下时检查 执行它。 没有 `Chip`: 静态标签为中性 `Badge`。 。 。 . ![File upload drop zone](https://npmcn.com/package/%40cinesend/ui-kit/docs/screenshots/file-upload-idle.png) - **`DonutChart`** 是普通的SVG 从工具箱的符号中抽取,所以它添加了不 绘制依赖图。 给完成的部分 进展铃声和 剩余 `muted`,或者离开音符 以崩溃。 负数和 非数值计为零。 它没有徘徊或点击: `label` 已经告诉屏幕阅读器每个段的值, 以及可选的 因此,传说被隐藏在辅助技术中. ![Donut chart showing progress](https://npmcn.com/package/%40cinesend/ui-kit/docs/screenshots/demo-donut-progress.png) ![Donut chart breakdown with a legend](https://npmcn.com/package/%40cinesend/ui-kit/docs/screenshots/demo-donut-breakdown.png) - **`toUtcDateValue` 编号 : `fromUtcDateValue`** 在 UTC 时间戳之间转换 编辑 `YYYY-MM-DD` 价值 `DatePicker` 拿着 比较读取协调世界时的日期 而不是本地的 是停止存储的午夜UTC日期显示为 在协调世界时的前一天, 任何人的背后. - **`LoadingState` 编号 : `EmptyState` 编号 : `ErrorState`** 三个,永远不要 一个 "这里什么都没有" "我们找不到"导致相反 行动. `ErrorState` 使用信件串而不是错误对象 : 将失败变成句子需要知道您 API 的状态代码 用于"晚点再来"与"这个不见了",这是套件无法知道的. 选择 _哪个_ 要显示的状态是呼叫者的工作——这取决于数据 这个工具箱没有意见. ## 当地工具包工作 节点24(见 `.nvmrc`(b) —— `nvm use` 捡起. 构建工具链的需要 节点20.19+或22.12+;在任何更老的建筑物上,建筑物会因混乱而死 `node:util` 编号 : `styleText` 模块错误而不是版本投诉. ```bash nvm use npm install npm test npm run catalog:check npm run catalog ``` 目录 `catalog/` 文档此软件包。 这不是文件演示. ## 释放 出版者: `.github/workflows/release.yml` 使用 npm 数据 [受托出版](https://docs.npmjs.com/trusted-publishers) (OIDC) (英语). 没有 `NPM_TOKEN` 机密 — npmjs.com 配置以信任此 repo 的 `release.yml` 工作流程. 证出已绝( 二`publishConfig.provenance`) (中文(简体) ). 信任的出版 打开它 默认和 npm [不接受来自私人来源 仓库](https://github.blog/changelog/2023-07-25-publishing-with-npm-provenance-from-private-source-repositories-is-no-longer-supported), (中文(简体) ), 这部《古兰经》是真实的,所以它不能出版。 如果 重金永远公开. 要剪掉释放,碰上 `version` 内 `package.json` 作为公关的一部分。 合并为 `staging` 运行类型检查、测试和构建、发布和标记承诺 `v`。 。 。 . 一个未撞倒版本的合并不发布任何信息: 工作流程询问 npm 是否该版本存在,如果存在则停止,所以普通合并是 而不是失败的发布 。 推动 `v*` 手动标记仍然有效 对照 `package.json`。 。 。 . ## 用于消耗应用程序的堆栈 反应+Vite. TanStack 查询所有服务器数据 。 不添加原始内容 `fetch` 编号 : `useEffect` 数据装入应用程序. ## 常见问题 ### @cinesend/ui-kit 是什么？ 共享反应组件,设计令牌,以及CineSendapps的CSS\. ### 如何安装 @cinesend/ui-kit？ 在项目目录运行 npm install @cinesend/ui-kit，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18\.2 \<20）、sonner（^2\.0\.7）、react-dom（\>=18\.2 \<20）、@phosphor-icons/react（^2\.1\.10）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @cinesend/ui-kit 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @cinesend/ui-kit 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @cinesend/ui-kit 可以商用吗？ @cinesend/ui-kit 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @cinesend/ui-kit 的下载量有多少？ 根据 npm 官方下载统计，@cinesend/ui-kit 在 2026/10/10 – 2026/11/08 这 30 天内被下载 2,260 次，日均约 75 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @cinesend/ui-kit 还在维护吗？ 最新版本 0\.5\.5 发布于 2026/11/03（6 天前）；至今共发布 11 个版本，其中过去 12 个月发布了 11 个；首次发布于 2026/09/26。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。