# @alga-psa/ui-kit 中文文档

规范地址：https://npmcn.com/package/%40alga-psa/ui-kit/

版本：0\.2\.0
npm 元数据更新时间：2026-02-24T16:01:17.819Z
中文译文更新时间：2026-11-05T21:23:06.754Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40alga-psa/ui-kit
原文对照：https://npmcn.com/package/%40alga-psa/ui-kit/?lang=original

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

- 包体积（解压后）：148 kB，63 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：react ^18 \|\| ^19，react-dom ^18 \|\| ^19
- 首次发布：2025-09-02T02:16:45.613Z
- 最新版本发布：2026-02-24T16:01:17.642Z
- 近 30 天下载量：18673（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 1 个）

## 中文简介

用于 Alga 扩展的零依赖性 React 组件库 。 所有组件都使用CSS自定义属性用于主题,并在扩展iframes内部无缝工作.

## 安装

```sh
npm install @alga-psa/ui-kit
```

也可以使用：`pnpm add @alga-psa/ui-kit`、`yarn add @alga-psa/ui-kit`、`bun add @alga-psa/ui-kit`

## README

# @alga-psa/ ii- kit

用于 Alga 扩展的零依赖性 React 组件库 。 所有组件都使用CSS自定义属性用于主题,并在扩展iframes内部无缝工作.

> 见 **显示扩展名** (单位:千美元)`ee/extensions/showcase`用于每个组件的交互式演示.

## 安装

在您的应用程序根部导入主题样式表 :

```ts
import '@alga-psa/ui-kit/theme.css';
```

* * *

## 主题键

Tokens作为CSS变量被曝光. 在扩展框内运行时,主机将自动注入 `:root`。 。 。 .

| 变量 | 光线 | 阴暗 | 目的 |
| --- | --- | --- | --- |
| `--alga-bg` | `#ffffff` | `#0b0f14` | 背景情况 |
| `--alga-fg` | `#111111` | `#e5e7eb` | 前景/ 文本 |
| `--alga-muted` | `#f5f5f7` | `#0f1720` | 静音背景 |
| `--alga-muted-fg` | `#4b5563` | `#9ca3af` | 静音文本 |
| `--alga-primary` | `#9855ee` | `#8a4dea` | 小学(布尔) |
| `--alga-primary-foreground` | `#ffffff` | `#ffffff` | 关于小学的案文 |
| `--alga-secondary` | `#53d7fa` | `#40cff9` | 中学(蓝色) |
| `--alga-secondary-foreground` | `#111111` | `#0b0f14` | 关于中学的案文 |
| `--alga-border` | `#e5e7eb` | `#1f2937` | 边框 |
| `--alga-radius` | `8px` | `8px` | 边界半径 |
| `--alga-danger` | `#dc2626` | `#ef4444` | 危险/ 错误 |
| `--alga-warning` | `#d97706` | `#f59e0b` | 3⁄4 ̄ ̧漯B |
| `--alga-success` | `#16a34a` | `#22c55e` | 成绩 |

您也可以在程序上访问符号 :

```ts
import { tokens } from '@alga-psa/ui-kit';

tokens.primary   // 'var(--alga-primary)'
tokens.bg        // 'var(--alga-bg)'
```

* * *

## 构成部分

### 核心

#### `Button`

有多个变体和大小的Themed按钮.

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `variant` | `'primary' | 'secondary' | 'destructive' | 'outline' | 'ghost' | 'link' | 'soft' | 'dashed'` | `'primary'` | 视觉风格 |
| `size` | `'xs' | 'sm' | 'md' | 'lg' | 'icon'` | `'md'` | 控制粘贴和字体大小 |

```tsx
<Button variant="secondary" size="sm">Save</Button>
```

#### `Text`

有大小、音调和重量预置的打字组件.

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `as` | `'span' | 'p' | 'label' | 'strong'` | `'span'` | 要渲染的 HTML 元素 |
| `size` | `'xs' | 'sm' | 'md' | 'lg'` | `'md'` | 字体大小预设 |
| `tone` | `'default' | 'muted' | 'danger' | 'warning' | 'success'` | `'default'` | 文本颜色 |
| `weight` | `400 | 500 | 600 | 700` | `400` | 字体重量 |

```tsx
<Text as="p" size="lg" tone="muted" weight={600}>Hello</Text>
```

#### `Card`

相接的容器有背景,阴影和圆角. 扩展标准 `<div>` 属性.

```tsx
<Card style={{ padding: 24 }}>Content here</Card>
```

#### `Badge`

小丸形标签,用于状态指标.

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `tone` | `'default' | 'info' | 'success' | 'warning' | 'danger'` | `'default'` | 颜色方案 |

```tsx
<Badge tone="success">Active</Badge>
```

#### `Alert`, (中文(简体) ), `AlertTitle`, (中文(简体) ), `AlertDescription`

带有可选图标的上下文提醒旗.

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `tone` | `'info' | 'success' | 'warning' | 'danger'` | `'info'` | 视觉音色 |
| `showIcon` | `boolean` | `true` | 显示特定音色图标 |

```tsx
<Alert tone="warning">
  <AlertTitle>Heads up</AlertTitle>
  <AlertDescription>This action cannot be undone.</AlertDescription>
</Alert>
```

#### `Separator`

区分内容的细分线 .

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `orientation` | `'horizontal' | 'vertical'` | `'horizontal'` | 线路方向 |
| `style` | `CSSProperties` | —— 说 | 其他内线样式 |

* * *

### 表单

#### `Input`

带有错误状态支持的文本输入 .

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `error` | `boolean` | —— 说 | 显示出错的样式 |
| `errorMessage` | `string` | —— 说 | 输入下显示出错消息 |

```tsx
<Input placeholder="Email" error={!!err} errorMessage={err} />
```

#### `TextArea`

多行文字输入. 扩展 `<textarea>` 属性.

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `error` | `boolean` | —— 说 | 显示出错边框 |
| `errorMessage` | `string` | —— 说 | 字段以下出错文本 |
| `resize` | `'none' | 'vertical' | 'horizontal' | 'both'` | `'vertical'` | 调整行为大小 |

#### `CustomSelect`

随搜索过滤而下降 .

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `options` | `SelectOption[]` | —— 说 | 可用选项 |
| `value` | `string` | —— 说 | 选中值 |
| `onChange` | `(value: string) => void` | —— 说 | 更改回调 |
| `placeholder` | `string` | —— 说 | 占位符文本 |
| `searchable` | `boolean` | `true` | 启用搜索过滤 |
| `disabled` | `boolean` | `false` | 禁用选中内容 |

#### `SearchInput`

输入内置搜索图标和可选调出.

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `onSearch` | `(value: string) => void` | —— 说 | 跳出搜索回调 |
| `debounceMs` | `number` | `300` | 省略延迟 ms |
| `size` | `'sm' | 'md'` | `'md'` | 输入大小 |

#### `Checkbox`

带有标签的Themed复选框.

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `label` | `string` | —— 说 | 标签文本 |
| `size` | `'sm' | 'md' | 'lg'` | `'md'` | 大小预设 |

#### `RadioGroup`

一组相互排斥的无线电按钮.

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `options` | `RadioOption[]` | —— 说 | 可用选项 |
| `value` | `string` | —— 说 | 选中值 |
| `onChange` | `(value: string) => void` | —— 说 | 更改回调 |
| `name` | `string` | 自动 | HTML 名称属性 |
| `disabled` | `boolean` | `false` | 禁用所有选项 |
| `orientation` | `'horizontal' | 'vertical'` | `'vertical'` | 布局方向 |
| `size` | `'sm' | 'md' | 'lg'` | `'md'` | 大小预设 |

`RadioOption`数字 : `{ value: string; label: string; disabled?: boolean }`

```tsx
<RadioGroup
  options={[{ value: 'a', label: 'Alpha' }, { value: 'b', label: 'Beta' }]}
  value={selected}
  onChange={setSelected}
/>
```

#### `Switch`

切换布尔值切换 .

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `checked` | `boolean` | —— 说 | 控制状态 |
| `onChange` | `(checked: boolean) => void` | —— 说 | 更改回调 |
| `size` | `'sm' | 'md' | 'lg'` | `'md'` | 大小预设 |
| `disabled` | `boolean` | `false` | 禁用开关 |
| `label` | `string` | —— 说 | 标签文本 |

#### `Label`

样式 `<label>` 键.

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `required` | `boolean` | —— 说 | 显示需要的指标 |
| `disabled` | `boolean` | —— 说 | 应用变形器 |

* * *

### 数据显示

#### `DataTable`

配有排序、搜索和自定义单元格渲染的平面表.

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `data` | `Row[]` | —— 说 | 行对象矩阵 |
| `columns` | `Column<Row>[]` | —— 说 | 栏定义 |
| `initialSortKey` | `string` | —— 说 | 初始排序栏 |
| `searchable` | `boolean` | `false` | 显示搜索输入 |
| `pageSize` | `number` | `10` | 每页行数 |

`Column<Row>`数字 : `{ key: string; header: string; width?: number; sortable?: boolean; render?: (row) => ReactNode }`

```tsx
<DataTable
  data={items}
  columns={[
    { key: 'name', header: 'Name', sortable: true },
    { key: 'status', header: 'Status', render: (row) => <Badge>{row.status}</Badge> },
  ]}
/>
```

* * *

### 导航

#### `Tabs`

水平标签栏 .

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `tabs` | `TabItem[]` | —— 说 | 标签定义 |
| `activeTab` | `string` | —— 说 | 当前活动的标签 ID |
| `onChange` | `(id: string) => void` | —— 说 | 标签更改回调 |

`TabItem`数字 : `{ id: string; label: string; icon?: ComponentType; disabled?: boolean }`

```tsx
<Tabs
  tabs={[{ id: 'one', label: 'Tab 1' }, { id: 'two', label: 'Tab 2' }]}
  activeTab={tab}
  onChange={setTab}
/>
```

#### `ViewSwitcher`

在视图间切换的分块按钮组 .

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `currentView` | `T` | —— 说 | 活动视图值 |
| `onChange` | `(view: T) => void` | —— 说 | 查看更改回调 |
| `options` | `ViewSwitcherOption<T>[]` | —— 说 | 现有意见 |

`ViewSwitcherOption<T>`数字 : `{ value: T; label: string; icon?: ComponentType }`

```tsx
<ViewSwitcher
  currentView={view}
  onChange={setView}
  options={[{ value: 'list', label: 'List' }, { value: 'grid', label: 'Grid' }]}
/>
```

#### `Breadcrumbs`

水平面包屑导航道.

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `items` | `BreadcrumbItem[]` | —— 说 | 面包屑片段 |
| `separator` | `ReactNode` | `'/'` | 自定义分隔符 |

`BreadcrumbItem`数字 : `{ label: ReactNode; href?: string; onClick?: () => void }`

```tsx
<Breadcrumbs items={[
  { label: 'Home', href: '/' },
  { label: 'Settings', onClick: goSettings },
  { label: 'Profile' },
]} />
```

#### `DropdownMenu`

由按钮触发的弹出式菜单 .

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `trigger` | `ReactNode` | —— 说 | 触发元素 |
| `items` | `DropdownMenuItem[]` | —— 说 | 菜单项目 |

`DropdownMenuItem`数字 : `{ label: string; onClick?: () => void; icon?: ComponentType; danger?: boolean; disabled?: boolean; separator?: boolean }`

* * *

### 版式

#### `Stack`

Flexbox 排版帮助器,用于堆放具有一致间隔的孩子.

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `direction` | `'row' | 'column'` | `'column'` | 弹性方向 |
| `gap` | `number | string` | `8` | 儿童之间的差距(数目=px) |
| `align` | `'stretch' | 'flex-start' | 'center' | 'flex-end' | 'baseline'` | —— 说 | 横轴对齐 |
| `justify` | `'flex-start' | 'center' | 'flex-end' | 'space-between' | 'space-around' | 'space-evenly'` | —— 说 | 主轴对齐 |

```tsx
<Stack direction="row" gap={12} align="center">
  <Text>Left</Text>
  <Button>Right</Button>
</Stack>
```

#### `Drawer`

滑入面板从右边缘取出,并带有焦点陷阱和覆盖.

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `open` | `boolean` | —— 说 | 抽屉是否打开 |
| `onClose` | `() => void` | —— 说 | 关闭回调 |
| `width` | `string` | `'fit-content'` | CSS 宽度 |
| `maxWidth` | `string` | `'60vw'` | 最大宽度 |
| `title` | `ReactNode` | —— 说 | 绘图标题 |
| `overlay` | `boolean` | `true` | 显示背景覆盖 |
| `closeOnOverlayClick` | `boolean` | `true` | 关闭覆盖点击 |
| `closeOnEscape` | `boolean` | `true` | 关闭退出密钥 |

#### `Dialog` 编号 : `ConfirmDialog`

模块对话框 .

**对话框** 所有权和儿童的基本模式.

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `isOpen` | `boolean` | —— 说 | 打开状态 |
| `onClose` | `() => void` | —— 说 | 关闭回调 |
| `title` | `string` | —— 说 | 对话框标题 |

**确认拨号** - 确认/取消模式.

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `isOpen` | `boolean` | —— 说 | 打开状态 |
| `title` | `string` | —— 说 | 标题 |
| `message` | `string` | —— 说 | 文本正文 |
| `variant` | `'default' | 'danger'` | `'default'` | 视觉音色 |
| `onConfirm` | `() => void` | —— 说 | 确认回调 |
| `onCancel` | `() => void` | —— 说 | 取消回调 |

```tsx
<ConfirmDialog
  isOpen={open}
  title="Delete Item"
  message="Are you sure?"
  variant="danger"
  onConfirm={handleDelete}
  onCancel={() => setOpen(false)}
/>
```

#### `Popover`

定位内容弹出到触发元素中 .

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `trigger` | `ReactNode` | —— 说 | 触发元素 |
| `open` | `boolean` | —— 说 | 控制开放状态 |
| `onOpenChange` | `(open: boolean) => void` | —— 说 | 打开状态回调 |
| `placement` | `'top' | 'bottom' | 'left' | 'right'` | `'bottom'` | 弹出后安置 |

* * *

### 反馈

#### `Spinner` 编号 : `LoadingIndicator`

**旋转器** ——动画循环装入指标.

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `size` | `'button' | 'xs' | 'sm' | 'md' | 'lg'` | `'md'` | 数字预设 |
| `variant` | `'default' | 'inverted'` | `'default'` | 使用 `'inverted'` 颜色背景 |

**装入指标** 带有任择文本的旋转器.

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `size` | 与斯宾纳相同 | `'md'` | 旋转器大小 |
| `text` | `string` | —— 说 | 旋转器旁边的标签 |
| `layout` | `'inline' | 'stacked'` | `'inline'` | 文本位置 |

```tsx
<Spinner size="sm" />
<LoadingIndicator text="Loading..." layout="stacked" />
```

#### `Tooltip`

寄托在孩子们身上.

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `content` | `ReactNode` | —— 说 | 工具提示内容 |
| `placement` | `'top' | 'bottom' | 'left' | 'right'` | `'top'` | 职位 |
| `delay` | `number` | `200` | 显示延迟 MS |

```tsx
<Tooltip content="More info">
  <Button variant="ghost">?</Button>
</Tooltip>
```

#### `Progress`

水平进度栏 .

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `value` | `number` | —— 说 | 现值( 0- 100) |
| `max` | `number` | `100` | 最大值 |
| `size` | `'sm' | 'md' | 'lg'` | `'md'` | 栏高 |
| `tone` | `'primary' | 'success' | 'warning' | 'danger'` | `'primary'` | 边框颜色 |

```tsx
<Progress value={75} tone="success" />
```

#### `Skeleton` 编号 : `SkeletonText` 编号 : `SkeletonCircle` 编号 : `SkeletonRectangle`

占位符加载形状 .

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `width` | `string | number` | `'100%'` | 宽度 |
| `height` | `string | number` | `'1em'` | 高度 |
| `variant` | `'text' | 'circular' | 'rectangular'` | `'text'` | 形状 |
| `animation` | `'pulse' | 'wave' | 'none'` | `'pulse'` | 动画类型 |
| `lines` | `number` | `3` | 行数( 文本变体) |

```tsx
<SkeletonText lines={3} />
<SkeletonCircle width={40} height={40} />
```

* * *

## 钩子

### `useTheme()`

回返 `{ setMode, getMode }` 用于读取和设置当前主题模式( e)`'light' | 'dark'`) (中文(简体) ).

```tsx
import { useTheme } from '@alga-psa/ui-kit';

const { setMode, getMode } = useTheme();
setMode('dark');
```

### `applyThemeVars(vars)`

应用 a `Record<string, string>` cSS 自定义属性值到文档根.

```tsx
import { applyThemeVars } from '@alga-psa/ui-kit';

applyThemeVars({ 'alga-primary': '#ff6600' });
```

* * *

## 扩展主题桥

对于在 iframes 中运行的扩展,请使用内置主题桥接收主机主题变量 :

```tsx
import { applyThemeVars } from '@alga-psa/ui-kit';

window.addEventListener('message', (ev) => {
  const data = ev.data;
  if (data?.alga === true && data?.version === '1' && data?.type === 'theme') {
    applyThemeVars(data.payload || {});
  }
});

// Signal readiness to the host
window.parent.postMessage({ alga: true, version: '1', type: 'ready' }, '*');
```

## 常见问题

### @alga-psa/ui-kit 是什么？

用于 Alga 扩展的零依赖性 React 组件库 。 所有组件都使用CSS自定义属性用于主题,并在扩展iframes内部无缝工作\.

### 如何安装 @alga-psa/ui-kit？

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

### @alga-psa/ui-kit 支持 TypeScript 吗？

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

### @alga-psa/ui-kit 支持 ESM 还是 CommonJS？

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

### @alga-psa/ui-kit 可以商用吗？

@alga-psa/ui-kit 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @alga-psa/ui-kit 的下载量有多少？

根据 npm 官方下载统计，@alga-psa/ui-kit 在 2026/10/06 – 2026/11/04 这 30 天内被下载 18,673 次，日均约 622 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @alga-psa/ui-kit 还在维护吗？

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