npm package: @lvetechs/ui-lib
Description: 🎨 @lvetechs/ui-lib - 现代化 React UI 组件库，支持可视化设计器
Author: lindadayo
Latest version: 1.2.5

# 🎨 @lvetechs/ui-lib 组件库

一个现代化的 React/Vue UI 组件库，基于 Tailwind CSS，支持可视化设计编辑器。

## 安装与引入

```bash
pnpm add @lvetechs/ui-lib
```

```tsx
// 引入样式（在应用入口文件中引入一次即可）
import '@lvetechs/ui-lib/style.css'

// 按需导入组件
import { Button, Input, Card } from '@lvetechs/ui-lib'

// 导入类型（TypeScript）
import type { ButtonProps, InputProps } from '@lvetechs/ui-lib'

在本地项目开发时，修改package.json
"dependencies": {
  "@lvetechs/ui-lib": "workspace:*" 
}
```

---

## 目录

- [基础组件](#基础组件)
  - [Button 按钮](#button-按钮)
  - [Input 输入框](#input-输入框)
  - [Card 卡片](#card-卡片)
- [表单组件](#表单组件)
  - [Select 选择器](#select-选择器)
  - [Checkbox 复选框](#checkbox-复选框)
  - [Switch 开关](#switch-开关)
  - [Radio 单选框](#radio-单选框)
  - [Textarea 文本域](#textarea-文本域)
- [反馈组件](#反馈组件)
  - [Dialog 弹框](#dialog-弹框)
  - [Toast 轻提示](#toast-轻提示)
  - [Alert 警告提示](#alert-警告提示)
  - [Progress 进度条](#progress-进度条)
  - [Skeleton 骨架屏](#skeleton-骨架屏)
  - [Spinner 加载指示器](#spinner-加载指示器)
- [布局组件](#布局组件)
  - [Container 容器](#container-容器)
  - [Flex 弹性布局](#flex-弹性布局)
  - [Grid 网格布局](#grid-网格布局)
  - [Divider 分割线](#divider-分割线)
- [数据展示组件](#数据展示组件)
  - [Avatar 头像](#avatar-头像)
  - [Tag 标签](#tag-标签)
  - [Tabs 标签页](#tabs-标签页)
  - [Popover 气泡卡片](#popover-气泡卡片)
- [媒体组件](#媒体组件)
  - [Image 图片](#image-图片)
  - [VideoPreview 视频播放器](#videopreview-视频播放器)

---

## 基础组件

### Button 按钮

用户交互的主要入口，支持多种变体、尺寸、加载状态和图标。

```tsx
import { Button } from '@lvetechs/ui-lib'
```

#### 基础用法

```tsx
<Button>默认按钮</Button>
<Button variant="primary">主要按钮</Button>
<Button variant="secondary">次要按钮</Button>
<Button variant="outline">轮廓按钮</Button>
<Button variant="ghost">幽灵按钮</Button>
<Button variant="danger">危险按钮</Button>
<Button variant="success">成功按钮</Button>
```

#### 不同尺寸

```tsx
<Button size="xs">超小</Button>
<Button size="sm">小</Button>
<Button size="md">中等</Button>
<Button size="lg">大</Button>
<Button size="xl">超大</Button>
```

#### 加载状态

```tsx
<Button loading>提交中...</Button>
```

#### 带图标

```tsx
<Button leftIcon={<PlusIcon />}>新增</Button>
<Button rightIcon={<ArrowIcon />}>下一步</Button>
<Button iconOnly rounded><SearchIcon /></Button>
```

#### 全宽按钮

```tsx
<Button fullWidth>占满宽度</Button>
```

#### Props

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `variant` | `'primary' \| 'secondary' \| 'outline' \| 'ghost' \| 'danger' \| 'success'` | `'primary'` | 按钮样式变体 |
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | 按钮尺寸 |
| `fullWidth` | `boolean` | `false` | 是否占满父容器宽度 |
| `loading` | `boolean` | `false` | 是否显示加载状态 |
| `leftIcon` | `ReactNode` | - | 左侧图标 |
| `rightIcon` | `ReactNode` | - | 右侧图标 |
| `rounded` | `boolean` | `false` | 是否为圆形按钮 |
| `iconOnly` | `boolean` | `false` | 是否只显示图标 |
| `disabled` | `boolean` | `false` | 是否禁用 |

---

### Input 输入框

文本输入控件，支持标签、错误提示、图标、前后缀、清除功能。

```tsx
import { Input } from '@lvetechs/ui-lib'
```

#### 基础用法

```tsx
<Input placeholder="请输入" />
<Input label="用户名" required />
<Input label="邮箱" error="邮箱格式不正确" />
<Input label="备注" helper="选填，最多 200 字" />
```

#### 样式变体

```tsx
<Input variant="default" placeholder="默认边框" />
<Input variant="filled" placeholder="填充背景" />
<Input variant="flushed" placeholder="底部边框" />
```

#### 带图标

```tsx
<Input leftIcon={<SearchIcon />} placeholder="搜索..." />
<Input rightIcon={<EyeIcon />} type="password" />
```

#### 前后缀

```tsx
<Input prefix="$" placeholder="金额" />
<Input suffix="kg" placeholder="重量" />
```

#### 可清除

```tsx
const [value, setValue] = useState('')
<Input value={value} clearable onClear={() => setValue('')} />
```

#### Props

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `label` | `string` | - | 输入框标签 |
| `error` | `string` | - | 错误信息 |
| `helper` | `string` | - | 帮助文本 |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 尺寸 |
| `variant` | `'default' \| 'filled' \| 'flushed'` | `'default'` | 样式变体 |
| `leftIcon` | `ReactNode` | - | 左侧图标 |
| `rightIcon` | `ReactNode` | - | 右侧图标 |
| `prefix` | `string` | - | 前缀文本 |
| `suffix` | `string` | - | 后缀文本 |
| `required` | `boolean` | `false` | 是否必填 |
| `clearable` | `boolean` | `false` | 是否可清除 |
| `onClear` | `() => void` | - | 清除回调 |

---

### Card 卡片

内容容器，支持标题、封面、底部操作等。

```tsx
import { Card } from '@lvetechs/ui-lib'
```

#### 基础用法

```tsx
<Card title="卡片标题">
  这是卡片内容
</Card>
```

#### 变体样式

```tsx
<Card variant="elevated">阴影卡片</Card>
<Card variant="outlined">描边卡片</Card>
<Card variant="filled">填充卡片</Card>
<Card variant="glass">毛玻璃卡片</Card>
```

#### 可交互卡片

```tsx
<Card hoverable clickable onClick={() => console.log('clicked')}>
  可悬浮可点击的卡片
</Card>
```

#### 带封面和底部

```tsx
<Card
  cover="https://example.com/image.jpg"
  title="文章标题"
  extra={<Button size="sm">详情</Button>}
  footer={<span>2024-01-01</span>}
>
  文章摘要内容...
</Card>
```

#### Props

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `title` | `ReactNode` | - | 卡片标题 |
| `extra` | `ReactNode` | - | 头部额外内容 |
| `footer` | `ReactNode` | - | 底部内容 |
| `cover` | `string` | - | 封面图片 URL |
| `variant` | `'elevated' \| 'outlined' \| 'filled' \| 'glass'` | `'elevated'` | 变体样式 |
| `hoverable` | `boolean` | `false` | 是否可悬浮 |
| `clickable` | `boolean` | `false` | 是否可点击 |
| `bordered` | `boolean` | `false` | 是否有边框 |
| `padding` | `'none' \| 'sm' \| 'md' \| 'lg'` | `'md'` | 内边距大小 |

---

## 表单组件

### Select 选择器

下拉选择框，支持搜索、清除、键盘导航。

```tsx
import { Select } from '@lvetechs/ui-lib'
```

#### 基础用法

```tsx
const options = [
  { value: 'apple', label: '苹果' },
  { value: 'banana', label: '香蕉' },
  { value: 'orange', label: '橙子' },
]

<Select options={options} placeholder="请选择水果" />
```

#### 带标签和搜索

```tsx
<Select
  label="城市"
  options={cityOptions}
  searchable
  clearable
  required
  onChange={(value) => console.log(value)}
/>
```

#### 受控模式

```tsx
const [value, setValue] = useState<string | number>('')

<Select
  value={value}
  options={options}
  onChange={setValue}
/>
```

#### Props

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `options` | `SelectOption[]` | `[]` | 选项列表 |
| `value` | `string \| number` | - | 当前值（受控） |
| `defaultValue` | `string \| number` | - | 默认值（非受控） |
| `placeholder` | `string` | - | 占位文本 |
| `label` | `string` | - | 标签文本 |
| `error` | `string` | - | 错误信息 |
| `helper` | `string` | - | 帮助文本 |
| `disabled` | `boolean` | `false` | 是否禁用 |
| `required` | `boolean` | `false` | 是否必填 |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 尺寸 |
| `searchable` | `boolean` | `false` | 是否可搜索 |
| `clearable` | `boolean` | `false` | 是否可清除 |
| `onChange` | `(value: string \| number) => void` | - | 值变化回调 |

**SelectOption 类型：**

```ts
interface SelectOption {
  value: string | number
  label: string
  disabled?: boolean
  icon?: ReactNode
}
```

---

### Checkbox 复选框

多选控件，支持三种状态（选中、未选中、不确定）。

```tsx
import { Checkbox } from '@lvetechs/ui-lib'
```

#### 基础用法

```tsx
<Checkbox label="同意用户协议" />
<Checkbox label="记住我" defaultChecked />
<Checkbox label="订阅通知" description="每周接收产品更新邮件" />
```

#### 受控模式

```tsx
const [checked, setChecked] = useState(false)
<Checkbox checked={checked} onChange={setChecked} label="选中我" />
```

#### 不确定状态（全选场景）

```tsx
<Checkbox indeterminate label="全选" />
```

#### 不同颜色和尺寸

```tsx
<Checkbox color="violet" label="紫色" />
<Checkbox color="emerald" label="绿色" />
<Checkbox size="sm" label="小" />
<Checkbox size="lg" label="大" />
```

#### Props

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `label` | `ReactNode` | - | 标签文本 |
| `description` | `string` | - | 描述文本 |
| `checked` | `boolean` | - | 是否选中（受控） |
| `defaultChecked` | `boolean` | `false` | 默认是否选中 |
| `indeterminate` | `boolean` | `false` | 不确定状态 |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 尺寸 |
| `color` | `'violet' \| 'cyan' \| 'emerald' \| 'rose' \| 'amber'` | `'violet'` | 颜色 |
| `disabled` | `boolean` | `false` | 是否禁用 |
| `error` | `boolean` | `false` | 是否有错误 |
| `onChange` | `(checked: boolean) => void` | - | 选中变化回调 |

---

### Switch 开关

布尔值切换组件，适合即时生效的设置场景。

```tsx
import { Switch } from '@lvetechs/ui-lib'
```

#### 基础用法

```tsx
<Switch label="开启通知" />
<Switch label="深色模式" defaultChecked />
<Switch label="飞行模式" description="关闭所有网络连接" />
```

#### 受控模式

```tsx
const [enabled, setEnabled] = useState(false)
<Switch checked={enabled} onChange={setEnabled} label="启用功能" />
```

#### 状态图标和内嵌标签

```tsx
<Switch showIcons label="带图标" />
<Switch size="lg" onLabel="ON" offLabel="OFF" label="大号带文字" />
```

#### Props

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `checked` | `boolean` | - | 是否开启（受控） |
| `defaultChecked` | `boolean` | `false` | 默认是否开启 |
| `label` | `ReactNode` | - | 标签文本 |
| `description` | `string` | - | 描述文本 |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 尺寸 |
| `color` | `'violet' \| 'cyan' \| 'emerald' \| 'rose' \| 'amber'` | `'violet'` | 颜色 |
| `disabled` | `boolean` | `false` | 是否禁用 |
| `showIcons` | `boolean` | `false` | 是否显示状态图标 |
| `onLabel` | `string` | - | 开启时的文本（仅 `lg` 尺寸） |
| `offLabel` | `string` | - | 关闭时的文本（仅 `lg` 尺寸） |
| `onChange` | `(checked: boolean) => void` | - | 状态变化回调 |

---

### Radio 单选框

单选控件，需配合 `RadioGroup` 使用。

```tsx
import { Radio, RadioGroup } from '@lvetechs/ui-lib'
```

#### 基础用法

```tsx
<RadioGroup value={selected} onChange={setSelected}>
  <Radio value="a" label="选项 A" />
  <Radio value="b" label="选项 B" />
  <Radio value="c" label="选项 C" />
</RadioGroup>
```

#### 水平排列

```tsx
<RadioGroup direction="horizontal" defaultValue="a">
  <Radio value="a" label="选项 A" />
  <Radio value="b" label="选项 B" />
  <Radio value="c" label="选项 C" />
</RadioGroup>
```

#### 带描述

```tsx
<RadioGroup label="配送方式" defaultValue="standard">
  <Radio value="standard" label="标准配送" description="3-5 个工作日" />
  <Radio value="express" label="快速配送" description="1-2 个工作日" />
</RadioGroup>
```

#### RadioGroup Props

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `name` | `string` | - | 表单 name 属性 |
| `value` | `string \| number` | - | 当前值（受控） |
| `defaultValue` | `string \| number` | - | 默认值 |
| `label` | `string` | - | 组标签文本 |
| `children` | `ReactNode` | - | Radio 子组件 |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 尺寸 |
| `color` | `'violet' \| 'cyan' \| 'emerald' \| 'rose' \| 'amber'` | `'violet'` | 颜色 |
| `disabled` | `boolean` | `false` | 是否禁用整个组 |
| `direction` | `'horizontal' \| 'vertical'` | `'vertical'` | 排列方向 |
| `onChange` | `(value: string \| number) => void` | - | 值变化回调 |

#### Radio Props

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `value` | `string \| number` | **必填** | 单选框的值 |
| `label` | `ReactNode` | - | 标签文本 |
| `description` | `string` | - | 描述文本 |
| `disabled` | `boolean` | `false` | 是否禁用此选项 |

---

### Textarea 文本域

多行文本输入组件，支持自动调整高度和字数统计。

```tsx
import { Textarea } from '@lvetechs/ui-lib'
```

#### 基础用法

```tsx
<Textarea label="描述" placeholder="请输入描述..." />
<Textarea label="备注" rows={6} resize="vertical" />
```

#### 字数统计

```tsx
<Textarea
  label="评论"
  showCount
  maxLength={200}
  placeholder="请输入评论，最多 200 字"
/>
```

#### 自动调整高度

```tsx
<Textarea autoSize label="自适应高度" />
<Textarea autoSize={{ minRows: 3, maxRows: 8 }} label="限制行数" />
```

#### Props

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `label` | `string` | - | 标签文本 |
| `error` | `string` | - | 错误信息 |
| `helper` | `string` | - | 帮助文本 |
| `variant` | `'default' \| 'filled' \| 'flushed'` | `'default'` | 样式变体 |
| `required` | `boolean` | `false` | 是否必填 |
| `showCount` | `boolean` | `false` | 是否显示字数统计 |
| `maxLength` | `number` | - | 最大字符数 |
| `autoSize` | `boolean \| { minRows?: number; maxRows?: number }` | `false` | 是否自动调整高度 |
| `resize` | `'none' \| 'vertical' \| 'horizontal' \| 'both'` | `'vertical'` | 调整大小方式 |
| `rows` | `number` | `4` | 默认行数 |

---

## 反馈组件

### Dialog 弹框

模态对话框，用于确认操作、显示表单等需要用户关注的场景。

```tsx
import { Dialog } from '@lvetechs/ui-lib'
```

#### 基础用法

```tsx
const [visible, setVisible] = useState(false)

<Button onClick={() => setVisible(true)}>打开弹框</Button>

<Dialog
  visible={visible}
  title="确认删除"
  onClose={() => setVisible(false)}
  onOk={() => handleDelete()}
  onCancel={() => setVisible(false)}
>
  确定要删除这条记录吗？此操作不可撤销。
</Dialog>
```

#### 不同尺寸

```tsx
<Dialog size="sm" title="小弹框">内容</Dialog>
<Dialog size="md" title="中弹框">内容</Dialog>
<Dialog size="lg" title="大弹框">内容</Dialog>
<Dialog size="xl" title="超大弹框">内容</Dialog>
```

#### 自定义底部

```tsx
<Dialog
  visible={visible}
  title="自定义操作"
  footer={
    <>
      <Button variant="ghost" onClick={onClose}>稍后再说</Button>
      <Button variant="primary" onClick={onConfirm}>立即升级</Button>
    </>
  }
>
  发现新版本，是否升级？
</Dialog>
```

#### 异步确认

```tsx
<Dialog
  visible={visible}
  onOk={async () => {
    await api.submit(data)
    // 成功后自动关闭，失败时不关闭
  }}
  loading={submitting}
>
  提交表单？
</Dialog>
```

#### Props

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `title` | `ReactNode` | `'提示'` | 标题 |
| `children` | `ReactNode` | - | 内容 |
| `footer` | `ReactNode` | - | 自定义底部 |
| `visible` | `boolean` | `false` | 是否可见 |
| `onVisibleChange` | `(visible: boolean) => void` | - | 可见性变化回调 |
| `onClose` | `() => void` | - | 关闭回调 |
| `size` | `'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | 尺寸 |
| `closable` | `boolean` | `true` | 是否显示关闭按钮 |
| `maskClosable` | `boolean` | `true` | 点击遮罩是否关闭 |
| `centered` | `boolean` | `true` | 是否垂直居中 |
| `onOk` | `() => void \| Promise<void>` | - | 确认回调（支持异步） |
| `onCancel` | `() => void` | - | 取消回调 |
| `okText` | `string` | `'确认'` | 确认按钮文本 |
| `cancelText` | `string` | `'取消'` | 取消按钮文本 |
| `showFooter` | `boolean` | `true` | 是否显示底部 |
| `loading` | `boolean` | `false` | 确认按钮加载状态 |
| `zIndex` | `number` | `99` | 层叠顺序 |

---

### Toast 轻提示

轻量级消息提示，不打断用户操作，自动消失。

```tsx
import { ToastProvider, useToast } from '@lvetechs/ui-lib'
```

#### 配置 Provider

在应用根组件中包裹 `ToastProvider`：

```tsx
function App() {
  return (
    <ToastProvider position="top-right" maxToasts={5}>
      <YourApp />
    </ToastProvider>
  )
}
```

#### 使用 Toast

```tsx
function MyComponent() {
  const toast = useToast()

  return (
    <>
      <Button onClick={() => toast.success('保存成功！')}>成功</Button>
      <Button onClick={() => toast.error('操作失败')}>错误</Button>
      <Button onClick={() => toast.warning('请注意')}>警告</Button>
      <Button onClick={() => toast.info('新消息')}>信息</Button>
    </>
  )
}
```

#### 自定义持续时间

```tsx
toast.success('3秒后消失', 3000)
toast.info('不会自动消失', 0) // 传 0 表示不自动关闭
```

#### ToastProvider Props

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `position` | `'top' \| 'top-left' \| 'top-right' \| 'bottom' \| 'bottom-left' \| 'bottom-right'` | `'top-right'` | 显示位置 |
| `maxToasts` | `number` | `5` | 同时显示的最大数量 |

#### useToast 返回方法

| 方法 | 签名 | 说明 |
|------|------|------|
| `info` | `(message: string, duration?: number) => void` | 信息提示 |
| `success` | `(message: string, duration?: number) => void` | 成功提示 |
| `warning` | `(message: string, duration?: number) => void` | 警告提示 |
| `error` | `(message: string, duration?: number) => void` | 错误提示 |
| `toast` | `(options: Omit<ToastItem, 'id'>) => void` | 通用方法 |

---

### Alert 警告提示

重要信息提示，常驻页面中直到用户关闭。

```tsx
import { Alert } from '@lvetechs/ui-lib'
```

#### 基础用法

```tsx
<Alert type="info">这是一条信息提示。</Alert>
<Alert type="success">操作成功完成！</Alert>
<Alert type="warning">请注意操作风险。</Alert>
<Alert type="error">发生了一个错误。</Alert>
```

#### 带标题

```tsx
<Alert type="warning" title="注意">
  您的账户即将到期，请及时续费。
</Alert>
```

#### 变体样式

```tsx
<Alert variant="soft" type="info">柔和样式（默认）</Alert>
<Alert variant="solid" type="info">实心样式</Alert>
<Alert variant="outline" type="info">描边样式</Alert>
```

#### 可关闭

```tsx
<Alert type="info" closable onClose={() => console.log('关闭了')}>
  这条提示可以关闭。
</Alert>
```

#### 带操作按钮

```tsx
<Alert
  type="warning"
  title="存储空间不足"
  action={<Button size="sm" variant="outline">升级方案</Button>}
>
  您的存储空间已使用 90%，建议升级。
</Alert>
```

#### Props

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `type` | `'info' \| 'success' \| 'warning' \| 'error'` | `'info'` | 类型 |
| `title` | `string` | - | 标题 |
| `children` | `ReactNode` | **必填** | 内容 |
| `showIcon` | `boolean` | `true` | 是否显示图标 |
| `closable` | `boolean` | `false` | 是否可关闭 |
| `onClose` | `() => void` | - | 关闭回调 |
| `action` | `ReactNode` | - | 操作区域 |
| `variant` | `'soft' \| 'solid' \| 'outline'` | `'soft'` | 变体样式 |

---

### Progress 进度条

进度指示器，支持线性和圆形两种形式。

```tsx
import { Progress } from '@lvetechs/ui-lib'
```

#### 基础用法

```tsx
<Progress value={50} />
<Progress value={75} color="emerald" />
<Progress value={30} color="rose" />
```

#### 显示标签

```tsx
<Progress value={60} showLabel />
<Progress value={80} showLabel labelPosition="top" />
<Progress value={45} showLabel labelPosition="inside" size="lg" />
```

#### 圆形进度

```tsx
<Progress value={75} circular showLabel />
<Progress value={60} circular circleSize={80} color="cyan" showLabel />
```

#### 条纹和动画

```tsx
<Progress value={50} variant="striped" />
<Progress value={30} variant="animated" />
```

#### 自定义标签

```tsx
<Progress
  value={3}
  max={10}
  showLabel
  label={(value, max) => `${value}/${max} 步`}
/>
```

#### Props

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `value` | `number` | **必填** | 当前进度值 |
| `max` | `number` | `100` | 最大值 |
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | `'md'` | 尺寸 |
| `color` | `'violet' \| 'cyan' \| 'emerald' \| 'rose' \| 'amber' \| 'gradient'` | `'violet'` | 颜色 |
| `variant` | `'default' \| 'striped' \| 'animated'` | `'default'` | 变体 |
| `showLabel` | `boolean` | `false` | 是否显示标签 |
| `label` | `string \| ((value, max) => string)` | - | 自定义标签 |
| `labelPosition` | `'inside' \| 'outside' \| 'top'` | `'outside'` | 标签位置 |
| `circular` | `boolean` | `false` | 是否为圆形进度 |
| `circleSize` | `number` | `120` | 圆形进度尺寸（px） |

---

### Skeleton 骨架屏

内容加载占位符，提升加载体验。

```tsx
import { Skeleton, SkeletonCard, SkeletonAvatar, SkeletonButton, SkeletonTable } from '@lvetechs/ui-lib'
```

#### 基础用法

```tsx
{/* 单行文本 */}
<Skeleton variant="text" width="60%" />

{/* 多行文本 */}
<Skeleton variant="text" lines={3} />

{/* 圆形（头像占位） */}
<Skeleton variant="circular" width={40} height={40} />

{/* 矩形（图片占位） */}
<Skeleton variant="rectangular" height={200} />

{/* 圆角矩形 */}
<Skeleton variant="rounded" width={100} height={40} />
```

#### 动画效果

```tsx
<Skeleton animation="pulse" variant="text" />  {/* 脉冲（默认） */}
<Skeleton animation="wave" variant="text" />   {/* 波浪 */}
<Skeleton animation="none" variant="text" />   {/* 无动画 */}
```

#### 预设组合

```tsx
<SkeletonCard />                    {/* 卡片骨架 */}
<SkeletonAvatar size={48} />        {/* 头像骨架 */}
<SkeletonButton width={100} />      {/* 按钮骨架 */}
<SkeletonTable rows={5} cols={4} /> {/* 表格骨架 */}
```

#### Props

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `variant` | `'text' \| 'circular' \| 'rectangular' \| 'rounded'` | `'text'` | 形状变体 |
| `width` | `string \| number` | - | 宽度 |
| `height` | `string \| number` | - | 高度 |
| `animation` | `'pulse' \| 'wave' \| 'none'` | `'pulse'` | 动画效果 |
| `lines` | `number` | `1` | 行数（仅 text 变体） |

---

### Spinner 加载指示器

加载状态指示器，多种动画变体。

```tsx
import { Spinner } from '@lvetechs/ui-lib'
```

#### 基础用法

```tsx
<Spinner />
<Spinner size="lg" label="加载中..." />
```

#### 变体

```tsx
<Spinner variant="spinner" /> {/* 经典旋转 */}
<Spinner variant="dots" />    {/* 跳动圆点 */}
<Spinner variant="bars" />    {/* 跳动条 */}
<Spinner variant="ring" />    {/* 圆环 */}
```

#### 颜色和速度

```tsx
<Spinner color="cyan" speed="fast" />
<Spinner color="emerald" speed="slow" />
<Spinner color="white" /> {/* 适用于深色背景 */}
```

#### Props

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | 尺寸 |
| `color` | `'violet' \| 'cyan' \| 'emerald' \| 'rose' \| 'white' \| 'gray'` | `'violet'` | 颜色 |
| `thickness` | `number` | `3` | 线条粗细（spinner/ring 变体） |
| `speed` | `'slow' \| 'normal' \| 'fast'` | `'normal'` | 速度 |
| `variant` | `'spinner' \| 'dots' \| 'bars' \| 'ring'` | `'spinner'` | 变体 |
| `label` | `string` | - | 标签文本 |

---

## 布局组件

### Container 容器

基于 Flexbox 的布局容器，提供快捷的布局配置。

```tsx
import { Container } from '@lvetechs/ui-lib'
```

#### 基础用法

```tsx
{/* 水平排列 */}
<Container direction="row" gap="md">
  <div>Item 1</div>
  <div>Item 2</div>
</Container>

{/* 垂直排列 */}
<Container direction="column" gap="lg">
  <div>Top</div>
  <div>Bottom</div>
</Container>

{/* 居中内容 */}
<Container center minHeight={200}>
  <div>居中内容</div>
</Container>

{/* 两端对齐 */}
<Container justify="between" align="center">
  <span>Logo</span>
  <nav>导航</nav>
</Container>
```

#### Props

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `direction` | `'row' \| 'column'` | `'row'` | Flex 方向 |
| `justify` | `'start' \| 'end' \| 'center' \| 'between' \| 'around' \| 'evenly'` | `'start'` | 主轴对齐 |
| `align` | `'start' \| 'end' \| 'center' \| 'stretch'` | `'start'` | 交叉轴对齐 |
| `gap` | `number \| 'none' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | 间距 |
| `wrap` | `boolean` | `false` | 是否换行 |
| `padding` | `'none' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | 内边距 |
| `bg` | `string` | - | 背景色 |
| `center` | `boolean` | `false` | 是否居中 |
| `minHeight` | `string \| number` | - | 最小高度 |

---

### Flex 弹性布局

更纯粹的 Flexbox 封装，适合精细控制。

```tsx
import Flex from '@lvetechs/ui-lib' // 需要单独导入
```

#### 基础用法

```tsx
<Flex gap={4}>
  <div>Item 1</div>
  <div>Item 2</div>
</Flex>

{/* 导航栏布局 */}
<Flex justify="between" align="center">
  <Logo />
  <Nav />
</Flex>

{/* 垂直居中 */}
<Flex direction="column" align="center" gap={2}>
  <h1>标题</h1>
  <p>内容</p>
</Flex>
```

#### Props

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `direction` | `'row' \| 'row-reverse' \| 'column' \| 'column-reverse'` | `'row'` | 方向 |
| `justify` | `'start' \| 'end' \| 'center' \| 'between' \| 'around' \| 'evenly'` | `'start'` | 主轴对齐 |
| `align` | `'start' \| 'end' \| 'center' \| 'baseline' \| 'stretch'` | `'stretch'` | 交叉轴对齐 |
| `wrap` | `boolean \| 'reverse'` | `false` | 是否换行 |
| `gap` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 8 \| 10 \| 12` | `0` | 间距 |
| `inline` | `boolean` | `false` | 是否为内联元素 |

---

### Grid 网格布局

基于 CSS Grid 的二维网格布局。

```tsx
import Grid, { GridItem } from '@lvetechs/ui-lib' // 需要单独导入
```

#### 基础用法

```tsx
<Grid cols={3} gap={4}>
  <div>1</div>
  <div>2</div>
  <div>3</div>
  <div>4</div>
  <div>5</div>
  <div>6</div>
</Grid>
```

#### 使用 GridItem 控制跨度

```tsx
<Grid cols={4} gap={4}>
  <GridItem colSpan={2}>跨 2 列</GridItem>
  <GridItem>普通</GridItem>
  <GridItem>普通</GridItem>
  <GridItem colSpan="full">跨满行</GridItem>
</Grid>
```

#### Grid Props

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `cols` | `1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 12 \| 'none'` | `'none'` | 列数 |
| `rows` | `1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 'none'` | `'none'` | 行数 |
| `gap` | `0-12` | `4` | 间距 |
| `gapX` | `0-12` | - | 列间距 |
| `gapY` | `0-12` | - | 行间距 |
| `align` | `'start' \| 'end' \| 'center' \| 'stretch'` | `'stretch'` | 交叉轴对齐 |
| `justify` | `'start' \| 'end' \| 'center' \| 'stretch'` | `'stretch'` | 主轴对齐 |
| `flow` | `'row' \| 'col' \| 'dense' \| 'row-dense' \| 'col-dense'` | - | 自动流动方向 |

#### GridItem Props

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `colSpan` | `1-6 \| 12 \| 'full'` | - | 列跨度 |
| `rowSpan` | `1-6` | - | 行跨度 |
| `colStart` | `1-13 \| 'auto'` | - | 列起始位置 |
| `rowStart` | `1-7 \| 'auto'` | - | 行起始位置 |

---

### Divider 分割线

内容分隔线，支持水平/垂直方向和文字标签。

```tsx
import { Divider } from '@lvetechs/ui-lib'
```

#### 基础用法

```tsx
<Divider />
<Divider variant="dashed" />
<Divider variant="dotted" />
```

#### 带文字

```tsx
<Divider>或者</Divider>
<Divider textPosition="left">标题</Divider>
<Divider textPosition="right">更多</Divider>
```

#### 垂直分割线

```tsx
<div style={{ display: 'flex', height: 40, alignItems: 'center', gap: 16 }}>
  <span>选项A</span>
  <Divider direction="vertical" />
  <span>选项B</span>
</div>
```

#### Props

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `direction` | `'horizontal' \| 'vertical'` | `'horizontal'` | 方向 |
| `variant` | `'solid' \| 'dashed' \| 'dotted'` | `'solid'` | 线条样式 |
| `color` | `'default' \| 'light' \| 'dark' \| 'violet'` | `'default'` | 颜色 |
| `textPosition` | `'left' \| 'center' \| 'right'` | `'center'` | 文本位置 |
| `thickness` | `'thin' \| 'medium' \| 'thick'` | `'thin'` | 粗细 |
| `children` | `ReactNode` | - | 文字标签 |

---

## 数据展示组件

### Avatar 头像

用户头像展示，支持图片、首字母、状态指示。

```tsx
import { Avatar, AvatarGroup } from '@lvetechs/ui-lib'
```

#### 基础用法

```tsx
{/* 图片头像 */}
<Avatar src="https://example.com/avatar.jpg" alt="用户" />

{/* 首字母头像 */}
<Avatar name="张三" />
<Avatar name="John Doe" />

{/* 默认图标 */}
<Avatar />
```

#### 不同尺寸和形状

```tsx
<Avatar name="A" size="xs" />
<Avatar name="B" size="sm" />
<Avatar name="C" size="md" />
<Avatar name="D" size="lg" />
<Avatar name="E" size="xl" />
<Avatar name="F" size="2xl" />
<Avatar name="G" size={100} />  {/* 自定义尺寸 */}

<Avatar name="A" shape="circle" />   {/* 圆形（默认） */}
<Avatar name="B" shape="rounded" />  {/* 圆角方形 */}
<Avatar name="C" shape="square" />   {/* 正方形 */}
```

#### 状态指示

```tsx
<Avatar name="张三" status="online" />   {/* 在线 - 绿色 */}
<Avatar name="李四" status="offline" />  {/* 离线 - 灰色 */}
<Avatar name="王五" status="busy" />     {/* 忙碌 - 红色 */}
<Avatar name="赵六" status="away" />     {/* 离开 - 黄色 */}
```

#### 头像组

```tsx
<AvatarGroup max={3} size="md">
  <Avatar name="Alice" />
  <Avatar name="Bob" />
  <Avatar name="Charlie" />
  <Avatar name="David" />
  <Avatar name="Eve" />
</AvatarGroup>
{/* 显示 Alice, Bob, Charlie, +2 */}
```

#### Avatar Props

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `src` | `string` | - | 图片地址 |
| `alt` | `string` | - | 图片替代文本 |
| `name` | `string` | - | 用户名（生成首字母和自动颜色） |
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| number` | `'md'` | 尺寸 |
| `shape` | `'circle' \| 'square' \| 'rounded'` | `'circle'` | 形状 |
| `color` | `'violet' \| 'cyan' \| 'emerald' \| 'rose' \| 'amber' \| 'gray' \| 'auto'` | `'auto'` | 背景颜色 |
| `bordered` | `boolean` | `false` | 是否显示边框 |
| `status` | `'online' \| 'offline' \| 'busy' \| 'away'` | - | 状态指示 |
| `badge` | `ReactNode` | - | 右上角徽标 |
| `icon` | `ReactNode` | - | 自定义图标 |

#### AvatarGroup Props

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `max` | `number` | - | 最大显示数量 |
| `size` | 同 Avatar | `'md'` | 统一尺寸 |
| `spacing` | `number` | `-8` | 头像间距（负数为重叠） |

---

### Tag 标签

小型标签组件，用于标记、分类或展示状态。

```tsx
import { Tag } from '@lvetechs/ui-lib'
```

#### 基础用法

```tsx
<Tag>默认标签</Tag>
<Tag color="violet">紫色</Tag>
<Tag color="emerald">绿色</Tag>
<Tag color="rose">红色</Tag>
<Tag color="cyan">青色</Tag>
<Tag color="amber">黄色</Tag>
```

#### 变体样式

```tsx
<Tag variant="soft" color="emerald">已完成</Tag>   {/* 柔和（默认） */}
<Tag variant="solid" color="rose">紧急</Tag>        {/* 实心 */}
<Tag variant="outline" color="blue">进行中</Tag>    {/* 描边 */}
```

#### 可关闭

```tsx
<Tag closable onClose={() => console.log('关闭')}>
  React
</Tag>
```

#### 药丸形状和图标

```tsx
<Tag rounded color="violet">药丸标签</Tag>
<Tag icon={<StarIcon />} color="amber">收藏</Tag>
```

#### Props

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `children` | `ReactNode` | **必填** | 内容 |
| `color` | `'violet' \| 'cyan' \| 'emerald' \| 'rose' \| 'amber' \| 'gray' \| 'blue' \| 'pink'` | `'gray'` | 颜色 |
| `variant` | `'solid' \| 'soft' \| 'outline'` | `'soft'` | 变体 |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 尺寸 |
| `closable` | `boolean` | `false` | 是否可关闭 |
| `onClose` | `() => void` | - | 关闭回调 |
| `icon` | `ReactNode` | - | 左侧图标 |
| `rounded` | `boolean` | `false` | 是否药丸形状 |

---

### Tabs 标签页

选项卡式导航，在多个面板之间切换。

```tsx
import { Tabs } from '@lvetechs/ui-lib'
```

#### 基础用法（items 模式）

```tsx
<Tabs
  items={[
    { key: 'tab1', label: '标签一', children: <div>内容一</div> },
    { key: 'tab2', label: '标签二', children: <div>内容二</div> },
    { key: 'tab3', label: '标签三', children: <div>内容三</div> },
  ]}
/>
```

#### 变体样式

```tsx
<Tabs variant="line" items={items} />      {/* 下划线（默认） */}
<Tabs variant="enclosed" items={items} />  {/* 包围式 */}
<Tabs variant="pills" items={items} />     {/* 药丸 */}
<Tabs variant="soft" items={items} />      {/* 柔和 */}
```

#### 受控模式

```tsx
const [activeTab, setActiveTab] = useState('tab1')

<Tabs
  value={activeTab}
  onChange={setActiveTab}
  items={items}
/>
```

#### 禁用某些标签

```tsx
<Tabs
  items={[
    { key: 'tab1', label: '可用' },
    { key: 'tab2', label: '禁用', disabled: true },
    { key: 'tab3', label: '可用' },
  ]}
/>
```

#### Props

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `items` | `{ key: string; label: string; children?: ReactNode; disabled?: boolean }[]` | - | 标签项列表 |
| `value` | `string` | - | 当前标签（受控） |
| `defaultValue` | `string` | - | 默认标签 |
| `variant` | `'line' \| 'enclosed' \| 'pills' \| 'soft'` | `'line'` | 变体样式 |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 尺寸 |
| `onChange` | `(value: string) => void` | - | 值变化回调 |

---

### Popover 气泡卡片

弹出式气泡卡片，支持多种触发方式和位置。

```tsx
import { Popover } from '@lvetechs/ui-lib'
```

#### 基础用法

```tsx
<Popover content="这是一段提示内容">
  <Button>点击显示</Button>
</Popover>
```

#### 带标题和底部

```tsx
<Popover
  title="确认删除？"
  content="此操作不可撤销。"
  footer={<Button size="sm" variant="danger">确认删除</Button>}
>
  <Button variant="danger">删除</Button>
</Popover>
```

#### 触发方式

```tsx
<Popover trigger="click" content="点击触发">
  <Button>点击</Button>
</Popover>

<Popover trigger="hover" content="悬停触发" delay={200}>
  <Button>悬停</Button>
</Popover>

<Popover trigger="focus" content="聚焦触发">
  <Input placeholder="聚焦我" />
</Popover>
```

#### 不同位置

```tsx
<Popover placement="top" content="上方">...</Popover>
<Popover placement="bottom" content="下方">...</Popover>
<Popover placement="left" content="左侧">...</Popover>
<Popover placement="right" content="右侧">...</Popover>
<Popover placement="top-start" content="上方左对齐">...</Popover>
```

#### 不同背景色

```tsx
<Popover bgColor="white" content="白色背景">...</Popover>
<Popover bgColor="dark" content="深色背景">...</Popover>
<Popover bgColor="violet" content="紫色背景">...</Popover>
```

#### Props

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `children` | `ReactElement` | - | 触发元素 |
| `title` | `ReactNode` | - | 标题 |
| `content` | `ReactNode` | `'弹出框内容'` | 内容 |
| `footer` | `ReactNode` | - | 底部操作 |
| `placement` | `'top' \| 'bottom' \| 'left' \| 'right' \| 'top-start' \| 'top-end' \| 'bottom-start' \| 'bottom-end'` | `'bottom'` | 位置 |
| `trigger` | `'hover' \| 'click' \| 'focus'` | `'click'` | 触发方式 |
| `visible` | `boolean` | - | 是否可见（受控） |
| `onVisibleChange` | `(visible: boolean) => void` | - | 可见性回调 |
| `delay` | `number` | `0` | 延迟显示（ms） |
| `disabled` | `boolean` | `false` | 是否禁用 |
| `bgColor` | `'white' \| 'dark' \| 'violet'` | `'white'` | 背景色 |
| `arrow` | `boolean` | `true` | 是否显示箭头 |
| `offset` | `number` | `12` | 偏移量（px） |
| `maxWidth` | `number` | `320` | 最大宽度（px） |
| `minWidth` | `number` | `200` | 最小宽度（px） |
| `closable` | `boolean` | `false` | 是否显示关闭按钮 |
| `zIndex` | `number` | `50` | 层叠顺序 |

---

## 媒体组件

### Image 图片

增强型图片展示组件，支持加载状态、错误回退、圆角及对象适应等功能。

```tsx
import { Image } from '@lvetechs/ui-lib'
```

#### 基础用法

```tsx
<Image
  src="https://example.com/photo.jpg"
  alt="示例图片"
  width="100%"
  height="auto"
/>
```

#### 固定尺寸

```tsx
<Image
  src="https://example.com/photo.jpg"
  alt="固定尺寸"
  width={300}
  height={200}
/>
```

#### 圆角与适应方式

```tsx
{/* 圆形头像 */}
<Image
  src="https://example.com/avatar.jpg"
  width={80}
  height={80}
  rounded="full"
  fit="cover"
/>

{/* 大圆角卡片图 */}
<Image
  src="https://example.com/banner.jpg"
  width="100%"
  height={200}
  rounded="xl"
  fit="cover"
/>
```

#### 边框与阴影

```tsx
<Image
  src="https://example.com/photo.jpg"
  width={300}
  height={200}
  bordered
  shadow
/>
```

#### 加载失败回退

```tsx
{/* 使用自定义回退图 */}
<Image
  src="https://broken-link.jpg"
  fallback="https://example.com/placeholder.jpg"
  width={300}
  height={200}
/>

{/* 无回退图时显示默认占位 */}
<Image
  src="https://broken-link.jpg"
  width={300}
  height={200}
/>
```

#### 事件回调

```tsx
<Image
  src="https://example.com/photo.jpg"
  onLoad={() => console.log('图片加载完成')}
  onError={(err) => console.error('图片加载失败', err)}
/>
```

#### Props

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `src` | `string` | - | 图片地址 |
| `alt` | `string` | `''` | 替代文本 |
| `width` | `string \| number` | `'100%'` | 宽度 |
| `height` | `string \| number` | `'auto'` | 高度 |
| `rounded` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'` | `'md'` | 圆角 |
| `fit` | `'contain' \| 'cover' \| 'fill' \| 'none' \| 'scale-down'` | `'cover'` | 对象适应方式 |
| `fallback` | `string` | - | 加载失败时的回退图地址 |
| `bordered` | `boolean` | `false` | 是否显示边框 |
| `shadow` | `boolean` | `false` | 是否显示阴影 |
| `onLoad` | `() => void` | - | 加载成功回调 |
| `onError` | `(error: unknown) => void` | - | 加载失败回调 |
| `className` | `string` | - | 自定义样式类名 |

---

### VideoPreview 视频播放器

自定义控制栏的视频播放器组件。

```tsx
import { VideoPreview } from '@lvetechs/ui-lib'
```

#### 基础用法

```tsx
<VideoPreview
  src="https://example.com/video.mp4"
  poster="https://example.com/poster.jpg"
  width="100%"
  height="auto"
/>
```

#### 自动播放和循环

```tsx
<VideoPreview
  src="/video.mp4"
  autoplay
  loop
  muted
/>
```

#### 自定义尺寸

```tsx
<VideoPreview
  src="/video.mp4"
  width={640}
  height={360}
/>
```

#### 事件回调

```tsx
<VideoPreview
  src="/video.mp4"
  onPlay={() => console.log('开始播放')}
  onPause={() => console.log('暂停')}
  onEnded={() => console.log('播放结束')}
  onError={(err) => console.error('播放错误', err)}
/>
```

#### Props

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `src` | `string` | - | 视频地址 |
| `poster` | `string` | - | 封面图片 |
| `width` | `string \| number` | `'100%'` | 宽度 |
| `height` | `string \| number` | `'auto'` | 高度 |
| `autoplay` | `boolean` | `false` | 自动播放 |
| `loop` | `boolean` | `false` | 循环播放 |
| `muted` | `boolean` | `false` | 静音 |
| `volume` | `number` | `0.6` | 默认音量（0-1） |
| `controls` | `boolean` | `true` | 是否显示控制栏 |
| `onPlay` | `() => void` | - | 播放回调 |
| `onPause` | `() => void` | - | 暂停回调 |
| `onEnded` | `() => void` | - | 结束回调 |
| `onError` | `(error: unknown) => void` | - | 错误回调 |

---

## 颜色主题

所有组件共享统一的颜色主题：

| 名称 | 用途 | Tailwind 色系 |
|------|------|--------------|
| `violet` | 主色调，品牌色 | violet-600 |
| `cyan` | 次要色，信息 | cyan-500 |
| `emerald` | 成功状态 | emerald-500 |
| `rose` | 错误/危险 | rose-500 |
| `amber` | 警告状态 | amber-500 |
| `gray` | 中性色，默认 | gray-400/600 |

---

## 依赖要求

| 依赖 | 版本 | 说明 |
|------|------|------|
| `react` | `^18.0.0` | React 核心 |
| `react-dom` | `^18.0.0` | React DOM |
| `lucide-react` | 随库安装 | VideoPreview 组件使用的图标库 |

## 📄 许可证

MIT License