@lvetechs/ui-lib

v1.1.6

Published

6 days ago

🎨 @lvetechs/ui-lib - 现代化 React UI 组件库，支持可视化设计器

0High
0Medium
0Low

lindadayo1998

react ui components tailwindcss micro-frontend design-system visual-designer

🎨 @lvetechs/ui-lib 组件库

一个现代化的 React/Vue UI 组件库，基于 Tailwind CSS，支持可视化设计编辑器。

安装与引入

pnpm add @lvetechs/ui-lib

// 引入样式（在应用入口文件中引入一次即可）
import '@lvetechs/ui-lib/style.css'

// 按需导入组件
import { Button, Input, Card } from '@lvetechs/ui-lib'

// 导入类型（TypeScript）
import type { ButtonProps, InputProps } from '@lvetechs/ui-lib'

基础组件

Button 按钮

用户交互的主要入口，支持多种变体、尺寸、加载状态和图标。

import { Button } from '@lvetechs/ui-lib'

基础用法

<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>

不同尺寸

<Button size="xs">超小</Button>
<Button size="sm">小</Button>
<Button size="md">中等</Button>
<Button size="lg">大</Button>
<Button size="xl">超大</Button>

加载状态

<Button loading>提交中...</Button>

带图标

<Button leftIcon={<PlusIcon />}>新增</Button>
<Button rightIcon={<ArrowIcon />}>下一步</Button>
<Button iconOnly rounded><SearchIcon /></Button>

全宽按钮

<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 输入框

文本输入控件，支持标签、错误提示、图标、前后缀、清除功能。

import { Input } from '@lvetechs/ui-lib'

基础用法

<Input placeholder="请输入" />
<Input label="用户名" required />
<Input label="邮箱" error="邮箱格式不正确" />
<Input label="备注" helper="选填，最多 200 字" />

样式变体

<Input variant="default" placeholder="默认边框" />
<Input variant="filled" placeholder="填充背景" />
<Input variant="flushed" placeholder="底部边框" />

带图标

<Input leftIcon={<SearchIcon />} placeholder="搜索..." />
<Input rightIcon={<EyeIcon />} type="password" />

前后缀

<Input prefix="$" placeholder="金额" />
<Input suffix="kg" placeholder="重量" />

可清除

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 卡片

内容容器，支持标题、封面、底部操作等。

import { Card } from '@lvetechs/ui-lib'

基础用法

<Card title="卡片标题">
  这是卡片内容
</Card>

变体样式

<Card variant="elevated">阴影卡片</Card>
<Card variant="outlined">描边卡片</Card>
<Card variant="filled">填充卡片</Card>
<Card variant="glass">毛玻璃卡片</Card>

可交互卡片

<Card hoverable clickable onClick={() => console.log('clicked')}>
  可悬浮可点击的卡片
</Card>

带封面和底部

<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 选择器

下拉选择框，支持搜索、清除、键盘导航。

import { Select } from '@lvetechs/ui-lib'

基础用法

const options = [
  { value: 'apple', label: '苹果' },
  { value: 'banana', label: '香蕉' },
  { value: 'orange', label: '橙子' },
]

<Select options={options} placeholder="请选择水果" />

带标签和搜索

<Select
  label="城市"
  options={cityOptions}
  searchable
  clearable
  required
  onChange={(value) => console.log(value)}
/>

受控模式

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 类型：

interface SelectOption {
  value: string | number
  label: string
  disabled?: boolean
  icon?: ReactNode
}

Checkbox 复选框

多选控件，支持三种状态（选中、未选中、不确定）。

import { Checkbox } from '@lvetechs/ui-lib'

基础用法

<Checkbox label="同意用户协议" />
<Checkbox label="记住我" defaultChecked />
<Checkbox label="订阅通知" description="每周接收产品更新邮件" />

受控模式

const [checked, setChecked] = useState(false)
<Checkbox checked={checked} onChange={setChecked} label="选中我" />

不确定状态（全选场景）

<Checkbox indeterminate label="全选" />

不同颜色和尺寸

<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 开关

布尔值切换组件，适合即时生效的设置场景。

import { Switch } from '@lvetechs/ui-lib'

基础用法

<Switch label="开启通知" />
<Switch label="深色模式" defaultChecked />
<Switch label="飞行模式" description="关闭所有网络连接" />

受控模式

const [enabled, setEnabled] = useState(false)
<Switch checked={enabled} onChange={setEnabled} label="启用功能" />

状态图标和内嵌标签

<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 使用。

import { Radio, RadioGroup } from '@lvetechs/ui-lib'

基础用法

<RadioGroup value={selected} onChange={setSelected}>
  <Radio value="a" label="选项 A" />
  <Radio value="b" label="选项 B" />
  <Radio value="c" label="选项 C" />
</RadioGroup>

水平排列

<RadioGroup direction="horizontal" defaultValue="a">
  <Radio value="a" label="选项 A" />
  <Radio value="b" label="选项 B" />
  <Radio value="c" label="选项 C" />
</RadioGroup>

带描述

<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 文本域

多行文本输入组件，支持自动调整高度和字数统计。

import { Textarea } from '@lvetechs/ui-lib'

基础用法

<Textarea label="描述" placeholder="请输入描述..." />
<Textarea label="备注" rows={6} resize="vertical" />

字数统计

<Textarea
  label="评论"
  showCount
  maxLength={200}
  placeholder="请输入评论，最多 200 字"
/>

自动调整高度

<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 弹框

模态对话框，用于确认操作、显示表单等需要用户关注的场景。

import { Dialog } from '@lvetechs/ui-lib'

基础用法

const [visible, setVisible] = useState(false)

<Button onClick={() => setVisible(true)}>打开弹框</Button>

<Dialog
  visible={visible}
  title="确认删除"
  onClose={() => setVisible(false)}
  onOk={() => handleDelete()}
  onCancel={() => setVisible(false)}
>
  确定要删除这条记录吗？此操作不可撤销。
</Dialog>

不同尺寸

<Dialog size="sm" title="小弹框">内容</Dialog>
<Dialog size="md" title="中弹框">内容</Dialog>
<Dialog size="lg" title="大弹框">内容</Dialog>
<Dialog size="xl" title="超大弹框">内容</Dialog>

自定义底部

<Dialog
  visible={visible}
  title="自定义操作"
  footer={
    <>
      <Button variant="ghost" onClick={onClose}>稍后再说</Button>
      <Button variant="primary" onClick={onConfirm}>立即升级</Button>
    </>
  }
>
  发现新版本，是否升级？
</Dialog>

异步确认

<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 轻提示

轻量级消息提示，不打断用户操作，自动消失。

import { ToastProvider, useToast } from '@lvetechs/ui-lib'

配置 Provider

在应用根组件中包裹 ToastProvider：

function App() {
  return (
    <ToastProvider position="top-right" maxToasts={5}>
      <YourApp />
    </ToastProvider>
  )
}

使用 Toast

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>
    </>
  )
}

自定义持续时间

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 警告提示

重要信息提示，常驻页面中直到用户关闭。

import { Alert } from '@lvetechs/ui-lib'

基础用法

<Alert type="info">这是一条信息提示。</Alert>
<Alert type="success">操作成功完成！</Alert>
<Alert type="warning">请注意操作风险。</Alert>
<Alert type="error">发生了一个错误。</Alert>

带标题

<Alert type="warning" title="注意">
  您的账户即将到期，请及时续费。
</Alert>

变体样式

<Alert variant="soft" type="info">柔和样式（默认）</Alert>
<Alert variant="solid" type="info">实心样式</Alert>
<Alert variant="outline" type="info">描边样式</Alert>

可关闭

<Alert type="info" closable onClose={() => console.log('关闭了')}>
  这条提示可以关闭。
</Alert>

带操作按钮

<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 进度条

进度指示器，支持线性和圆形两种形式。

import { Progress } from '@lvetechs/ui-lib'

基础用法

<Progress value={50} />
<Progress value={75} color="emerald" />
<Progress value={30} color="rose" />

显示标签

<Progress value={60} showLabel />
<Progress value={80} showLabel labelPosition="top" />
<Progress value={45} showLabel labelPosition="inside" size="lg" />

圆形进度

<Progress value={75} circular showLabel />
<Progress value={60} circular circleSize={80} color="cyan" showLabel />

条纹和动画

<Progress value={50} variant="striped" />
<Progress value={30} variant="animated" />

自定义标签

<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 骨架屏

内容加载占位符，提升加载体验。

import { Skeleton, SkeletonCard, SkeletonAvatar, SkeletonButton, SkeletonTable } from '@lvetechs/ui-lib'

基础用法

{/* 单行文本 */}
<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} />

动画效果

<Skeleton animation="pulse" variant="text" />  {/* 脉冲（默认） */}
<Skeleton animation="wave" variant="text" />   {/* 波浪 */}
<Skeleton animation="none" variant="text" />   {/* 无动画 */}

预设组合

<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 加载指示器

加载状态指示器，多种动画变体。

import { Spinner } from '@lvetechs/ui-lib'

基础用法

<Spinner />
<Spinner size="lg" label="加载中..." />

变体

<Spinner variant="spinner" /> {/* 经典旋转 */}
<Spinner variant="dots" />    {/* 跳动圆点 */}
<Spinner variant="bars" />    {/* 跳动条 */}
<Spinner variant="ring" />    {/* 圆环 */}

颜色和速度

<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 的布局容器，提供快捷的布局配置。

import { Container } from '@lvetechs/ui-lib'

基础用法

{/* 水平排列 */}
<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 封装，适合精细控制。

import Flex from '@lvetechs/ui-lib' // 需要单独导入

基础用法

<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 的二维网格布局。

import Grid, { GridItem } from '@lvetechs/ui-lib' // 需要单独导入

基础用法

<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 控制跨度

<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 分割线

内容分隔线，支持水平/垂直方向和文字标签。

import { Divider } from '@lvetechs/ui-lib'

基础用法

<Divider />
<Divider variant="dashed" />
<Divider variant="dotted" />

带文字

<Divider>或者</Divider>
<Divider textPosition="left">标题</Divider>
<Divider textPosition="right">更多</Divider>

垂直分割线

<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 头像

用户头像展示，支持图片、首字母、状态指示。

import { Avatar, AvatarGroup } from '@lvetechs/ui-lib'

基础用法

{/* 图片头像 */}
<Avatar src="https://example.com/avatar.jpg" alt="用户" />

{/* 首字母头像 */}
<Avatar name="张三" />
<Avatar name="John Doe" />

{/* 默认图标 */}
<Avatar />

不同尺寸和形状

<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" />   {/* 正方形 */}

状态指示

<Avatar name="张三" status="online" />   {/* 在线 - 绿色 */}
<Avatar name="李四" status="offline" />  {/* 离线 - 灰色 */}
<Avatar name="王五" status="busy" />     {/* 忙碌 - 红色 */}
<Avatar name="赵六" status="away" />     {/* 离开 - 黄色 */}

头像组

<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 标签

小型标签组件，用于标记、分类或展示状态。

import { Tag } from '@lvetechs/ui-lib'

基础用法

<Tag>默认标签</Tag>
<Tag color="violet">紫色</Tag>
<Tag color="emerald">绿色</Tag>
<Tag color="rose">红色</Tag>
<Tag color="cyan">青色</Tag>
<Tag color="amber">黄色</Tag>

变体样式

<Tag variant="soft" color="emerald">已完成</Tag>   {/* 柔和（默认） */}
<Tag variant="solid" color="rose">紧急</Tag>        {/* 实心 */}
<Tag variant="outline" color="blue">进行中</Tag>    {/* 描边 */}

可关闭

<Tag closable onClose={() => console.log('关闭')}>
  React
</Tag>

药丸形状和图标

<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 标签页

选项卡式导航，在多个面板之间切换。

import { Tabs } from '@lvetechs/ui-lib'

基础用法（items 模式）

<Tabs
  items={[
    { key: 'tab1', label: '标签一', children: <div>内容一</div> },
    { key: 'tab2', label: '标签二', children: <div>内容二</div> },
    { key: 'tab3', label: '标签三', children: <div>内容三</div> },
  ]}
/>

变体样式

<Tabs variant="line" items={items} />      {/* 下划线（默认） */}
<Tabs variant="enclosed" items={items} />  {/* 包围式 */}
<Tabs variant="pills" items={items} />     {/* 药丸 */}
<Tabs variant="soft" items={items} />      {/* 柔和 */}

受控模式

const [activeTab, setActiveTab] = useState('tab1')

<Tabs
  value={activeTab}
  onChange={setActiveTab}
  items={items}
/>

禁用某些标签

<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 气泡卡片

弹出式气泡卡片，支持多种触发方式和位置。

import { Popover } from '@lvetechs/ui-lib'

基础用法

<Popover content="这是一段提示内容">
  <Button>点击显示</Button>
</Popover>

带标题和底部

<Popover
  title="确认删除？"
  content="此操作不可撤销。"
  footer={<Button size="sm" variant="danger">确认删除</Button>}
>
  <Button variant="danger">删除</Button>
</Popover>

触发方式

<Popover trigger="click" content="点击触发">
  <Button>点击</Button>
</Popover>

<Popover trigger="hover" content="悬停触发" delay={200}>
  <Button>悬停</Button>
</Popover>

<Popover trigger="focus" content="聚焦触发">
  <Input placeholder="聚焦我" />
</Popover>

不同位置

<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>

不同背景色

<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 图片

增强型图片展示组件，支持加载状态、错误回退、圆角及对象适应等功能。

import { Image } from '@lvetechs/ui-lib'

基础用法

<Image
  src="https://example.com/photo.jpg"
  alt="示例图片"
  width="100%"
  height="auto"
/>

固定尺寸

<Image
  src="https://example.com/photo.jpg"
  alt="固定尺寸"
  width={300}
  height={200}
/>

圆角与适应方式

{/* 圆形头像 */}
<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"
/>

边框与阴影

<Image
  src="https://example.com/photo.jpg"
  width={300}
  height={200}
  bordered
  shadow
/>

加载失败回退

{/* 使用自定义回退图 */}
<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}
/>

事件回调

<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 视频播放器

自定义控制栏的视频播放器组件。

import { VideoPreview } from '@lvetechs/ui-lib'

基础用法

<VideoPreview
  src="https://example.com/video.mp4"
  poster="https://example.com/poster.jpg"
  width="100%"
  height="auto"
/>

自动播放和循环

<VideoPreview
  src="/video.mp4"
  autoplay
  loop
  muted
/>

自定义尺寸

<VideoPreview
  src="/video.mp4"
  width={640}
  height={360}
/>

事件回调

<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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

🎨 @lvetechs/ui-lib 组件库

安装与引入

目录

基础组件

Button 按钮

基础用法

不同尺寸

加载状态

带图标

全宽按钮

Props

Input 输入框

基础用法

样式变体

带图标

前后缀

可清除

Props

Card 卡片

基础用法

变体样式

可交互卡片

带封面和底部

Props

表单组件

Select 选择器

基础用法

带标签和搜索

受控模式

Props

Checkbox 复选框

基础用法

受控模式

不确定状态（全选场景）

不同颜色和尺寸

Props

Switch 开关

基础用法

受控模式

状态图标和内嵌标签

Props

Radio 单选框

基础用法

水平排列

带描述

RadioGroup Props

Radio Props

Textarea 文本域

基础用法

字数统计

自动调整高度

Props

反馈组件

Dialog 弹框

基础用法

不同尺寸

自定义底部

异步确认

Props

Toast 轻提示

配置 Provider

使用 Toast

自定义持续时间

ToastProvider Props

useToast 返回方法

Alert 警告提示

基础用法

带标题

变体样式

可关闭

带操作按钮

Props

Progress 进度条

基础用法