# @lailai0916/ui 中文文档

规范地址：https://npmcn.com/package/%40lailai0916/ui/

版本：0\.3\.19
npm 元数据更新时间：2026-11-01T14:42:48.166Z
中文译文更新时间：2026-11-01T17:29:28.993Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40lailai0916/ui
原文对照：https://npmcn.com/package/%40lailai0916/ui/?lang=original
项目主页：https://github.com/lailai0916/ui#readme
源码仓库：https://github.com/lailai0916/ui

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：523 kB，277 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.19
- 运行依赖：3 个
- peer 依赖：react ^18\.3\.1 \|\| ^19\.0\.0，react-dom ^18\.3\.1 \|\| ^19\.0\.0
- 首次发布：2026-09-15T14:49:25.874Z
- 最新版本发布：2026-11-01T14:42:47.835Z
- 已发布版本数：24（近 12 个月 24 个）

## 中文简介

为来来网站共享React组件和设计令牌。

## 安装

```sh
npm install @lailai0916/ui
```

也可以使用：`pnpm add @lailai0916/ui`、`yarn add @lailai0916/ui`、`bun add @lailai0916/ui`

## README

# laikit UI

[English](https://npmcn.com/package/%40lailai0916/ui/README.md) · **简体中文**

![](https://img.shields.io/github/actions/workflow/status/lailai0916/ui/ci.yml?branch=main&style=flat-square) ![](https://img.shields.io/npm/v/@lailai0916/ui?style=flat-square) ![](https://img.shields.io/github/last-commit/lailai0916/ui?style=flat-square) ![](https://img.shields.io/github/languages/top/lailai0916/ui?style=flat-square) ![](https://img.shields.io/github/repo-size/lailai0916/ui?style=flat-square) ![](https://img.shields.io/badge/code_style-prettier-ff69b4?style=flat-square) ![](https://img.shields.io/github/license/lailai0916/ui?style=flat-square)

## 项目简介

laikit UI 是从 [lailai's Home](https://lailai.one/) 抽出的共享 React 组件库，以 `@lailai0916/ui` 发布。

原 GitHub 包 `@lailai/ui` 的组件已合并到此库，仓库由 `laikit-ui` 重命名为 `ui`。Home、Tools 和 Academy 共用这一 npm 包；旧项目请参考[迁移指南](https://npmcn.com/package/%40lailai0916/ui/docs/migrating-from-ui.md)。

## 项目特性

🧩 **共享组件** — 64 个组件覆盖卡片、表单、控件、图表、导航和窗口面板，提供 TypeScript 类型声明与按组件导入入口。

🎨 **统一主题** — 共用 CSS 变量、深浅配色及减少动画支持，让多个网站保持一致。

🔌 **框架适配** — 原生链接和标题无需 Docusaurus 即可使用；需要时可通过 `LaikitProvider` 接入宿主路由、标题渲染和翻译。

🌐 **中英双语** — 内置英文和简体中文，覆盖组件库自身的标签；应用内容由调用方传入。

## 快速开始

支持 React 18.3.1 和 React 19。开发需要 Node.js 20.19+；CI 使用 Node.js 24。

```bash
npm install @lailai0916/ui react react-dom
```

```tsx
import { Button, LaikitProvider, TitleCard } from '@lailai0916/ui';
import '@lailai0916/ui/theme.css';
import '@lailai0916/ui/styles.css';

export function App() {
  return (
    <LaikitProvider locale="zh-Hans">
      <TitleCard title="欢迎">
        <Button onClick={() => alert('你好！')}>打个招呼</Button>
      </TitleCard>
    </LaikitProvider>
  );
}
```

在应用入口按上述顺序各导入一次 CSS。组件库不安装全局 CSS reset，也不覆盖宿主的正文字体。请在应用中设置基础排版和 `box-sizing`；主题提供 `--lk-font-family`、`--lk-font-size` 和 `--lk-line-height` 默认值。

在 `<html>` 上设置 `data-theme="light"` 或 `data-theme="dark"` 选择主题；未指定时，配色跟随系统。导入组件库后覆盖 `--lk-*` 变量即可定制颜色。独立 React 应用可使用 `ThemeProvider` 和 `ThemeControl` 保存主题偏好；Docusaurus 等已有主题管理的宿主继续使用自身的管理方式。 顶部栏可使用受控的 `LanguageButton` 与 `ThemeButton`；`ThemeProvider mode="system"` 在系统变化和重新加载时跟随系统，并允许当前页临时切换。

按组件导入可写为 `import Button from '@lailai0916/ui/Button'`。`Page`、`Markdown`、`Field`、`Layout` 和 `Panel` 子路径使用具名导出；所有组件也都支持从包根入口具名导入。

## 项目结构

```bash
ui/
├── demo/                           # 独立 React 示例
├── docs/                           # 接入和发布指南
├── scripts/                        # 构建和发布辅助脚本
├── src/                            # 组件、主题与适配层
├── tests/                          # 包入口与 SSR 测试
├── package.json                    # 依赖、入口和命令
└── vite.config.ts                  # ESM 与 CSS 构建
```

## 组件清单

| 分类 | 导出 |
| --- | --- |
| 布局 | `Card`, `TitleCard`, `LinkCard`, `DataCard`, `ShareCard`, `PageHeader`, `PageTitle`, `PageContent`, `PageContainer`, `SiteHeader`, `Stack`, `Cluster`, `Panel`, `PanelHeader`, `PanelBody`, `PanelFooter`, `Divider` |
| 控件 | `Button`, `ButtonLink`, `CopyButton`, `IconButton`, `LanguageButton`, `ThemeButton`, `Segmented`, `Tabs`, `Slider`, `Switch`, `ThemeControl` |
| 图表 | `Chart`, `Donut`, `Progress`, `Table` |
| 展示 | `Alert`, `Dialog`, `Badge`, `Icon`, `IconBlock`, `Hint`, `Tooltip`, `Skeleton`, `DataState`, `TrafficLights`, `WindowBar`, `WindowPanel`, `MDTitle`, `Quote`, `GitHub`, `Avatar`, `Brand`, `EmptyState` |
| 表单 | `Input`, `TextArea`, `Select`, `DropdownSelect`, `TextField`, `TextAreaField`, `SelectField`, `DropdownSelectField`, `PasswordInput`, `PasswordField`, `Checkbox`, `Radio` |
| 导航 | `Paginator`, `SkipLink` |

数量不含 `LaikitProvider`、`ThemeProvider`、路由辅助组件、hooks 及 `Tooltip.Label` / `Tooltip.Value`。共享工具包括 `useImageStatus`、`useMeasuredHeight`、`formatCompact` 和 `formatBytes`。

`Divider` 提供不附带间距的横向或纵向分割线；列表和容器边框共用其 `--lk-divider-color` 与 `--lk-divider-width` 变量。具体约定见[分割线说明](https://npmcn.com/package/%40lailai0916/ui/docs/integration.md#dividers--%E5%88%86%E5%89%B2%E7%BA%BF)。

`Select` 和 `SelectField` 保留原生 `<select>` 属性与选项子节点。`DropdownSelect` 和 `DropdownSelectField` 根据字符串值的 `options` 提供主题化弹层，支持键盘操作、表单提交和对话框。 具体行为见[下拉选择契约](https://npmcn.com/package/%40lailai0916/ui/docs/integration.md#dropdown-selection--%E4%B8%8B%E6%8B%89%E9%80%89%E6%8B%A9)和[双语示例](https://npmcn.com/package/%40lailai0916/ui/demo/DropdownSelectDemo.tsx)。

[接入指南](https://npmcn.com/package/%40lailai0916/ui/docs/integration.md) 说明路由适配、服务端渲染、主题定制和组件约定。[交互示例](https://npmcn.com/package/%40lailai0916/ui/demo/main.tsx) 在不依赖 Docusaurus 的环境中展示全部组件。

完整的[使用文档](https://lailai.one/docs/project/ui)包含组件预览、API、主题定制和维护发布流程。

## 开发

```bash
git clone https://github.com/lailai0916/ui.git
cd ui
npm ci
npm run dev
npm run check
```

`npm run check` 验证格式、lint、类型、发布产物、服务端渲染测试和示例构建。`npm run build` 将包输出到 `dist/`；`npm run build:demo` 将示例输出到 `demo-dist/`。另见[发布说明](https://npmcn.com/package/%40lailai0916/ui/docs/releasing.md)和[贡献指南](https://npmcn.com/package/%40lailai0916/ui/.github/CONTRIBUTING.md)。

推送到 `main` 后，通过验证的新稳定版本会经 npm Trusted Publishing 自动发布。推送前同步更新 `package.json` 和 `package-lock.json` 的版本号，并补充更新日志。已经发布的版本会跳过；各网站仍需更新依赖并重新部署。

## 许可协议

本项目代码采用 [MIT 许可协议](https://github.com/lailai0916/tools/blob/main/LICENSE)。

## 常见问题

### @lailai0916/ui 是什么？

为来来网站共享React组件和设计令牌。

### 如何安装 @lailai0916/ui？

在项目目录运行 npm install @lailai0916/ui，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18\.3\.1 \|\| ^19\.0\.0）、react-dom（^18\.3\.1 \|\| ^19\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @lailai0916/ui 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @lailai0916/ui 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @lailai0916/ui 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.19。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @lailai0916/ui 可以商用吗？

@lailai0916/ui 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @lailai0916/ui 还在维护吗？

最新版本 0\.3\.19 发布于 2026/11/01（1 天前）；至今共发布 24 个版本，其中过去 12 个月发布了 24 个；首次发布于 2026/09/15。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。