lw-ui-lib

跨 Vue / React UI 组件库

特性

• ✅ 跨框架支持：同时支持 Vue 3 和 React 18
• ✅ 主题系统：基于 CSS 变量的强大主题系统
• ✅ 暗黑模式：内置暗黑模式支持
• ✅ TypeScript：完整的类型定义支持
• ✅ 灵活引入：支持全量引入和按需引入
  • Vue：支持 app.use() 全量注册和按需引入
  • React：支持按需引入和手动引入组件文件
• ✅ 按需加载：支持 ES Module 按需加载，Tree-shaking 友好
• ✅ 轻量级：最小化包体积
• ✅ 完整文档：通过 Storybook 提供交互式文档

项目结构

lw-ui-lib/
├── .storybook/          # Storybook 配置和文档
│   ├── stories/         # Stories 文件
│   │   ├── vue/        # Vue 组件 Stories
│   │   └── react/      # React 组件 Stories
│   ├── main.ts         # Vue Storybook 配置
│   └── main-react.ts   # React Storybook 配置
├── packages/           # 组件源码
│   ├── vue/           # Vue 组件实现
│   ├── react/         # React 组件实现
│   ├── core/          # 核心工具函数
│   ├── icons/         # 图标资源
│   └── styles/        # 样式文件
├── docs/              # VitePress 文档
├── examples/          # 使用示例
└── package.json

快速开始

安装

npm install lw-ui-lib

或使用 yarn：

yarn add lw-ui-lib

Vue 项目使用

方式一：全量引入（推荐）

一次性引入所有组件，适合中小型项目：

import { createApp } from 'vue'
import LwUiLib from 'lw-ui-lib/vue'
import 'lw-ui-lib/styles'
import App from './App.vue'

const app = createApp(App)

// 注册所有组件
app.use(LwUiLib)

app.mount('#app')

使用时直接在模板中使用组件：

<template>
  <div>
    <LwButton type="primary">点击我</LwButton>
    <LwInput placeholder="请输入内容" />
  </div>
</template>

方式二：按需引入

只引入需要的组件，适合大型项目或对包体积有要求的场景：

import { createApp } from 'vue'
import { LwButton, LwInput } from 'lw-ui-lib/vue'
import 'lw-ui-lib/styles'
import App from './App.vue'

const app = createApp(App)

// 只注册需要的组件
app.component('LwButton', LwButton)
app.component('LwInput', LwInput)

app.mount('#app')

方式三：手动引入组件文件

对于极致的按需加载，可以直接引入组件文件：

import { createApp } from 'vue'
import LwButton from 'lw-ui-lib/vue/LwButton.vue'
import LwInput from 'lw-ui-lib/vue/LwInput.vue'
import 'lw-ui-lib/styles'
import App from './App.vue'

const app = createApp(App)

app.component('LwButton', LwButton)
app.component('LwInput', LwInput)

app.mount('#app')

React 项目使用

方式一：按需引入（推荐）

只引入需要的组件，减少最终打包体积：

import { LwButton, LwInput } from 'lw-ui-lib/react'
import 'lw-ui-lib/styles'

function App() {
  return (
    <div>
      <LwButton type="primary">点击我</LwButton>
      <LwInput placeholder="请输入内容" />
    </div>
  )
}

export default App

方式二：手动引入组件文件

对于极致的按需加载，可以直接引入组件文件：

import LwButton from 'lw-ui-lib/react/LwButton'
import LwInput from 'lw-ui-lib/react/LwInput'
import 'lw-ui-lib/styles'

function App() {
  return (
    <div>
      <LwButton type="primary">点击我</LwButton>
      <LwInput placeholder="请输入内容" />
    </div>
  )
}

export default App

提示：React 框架没有类似 Vue 的 app.use() 全量引入方式，建议使用按需引入以获得最佳性能。

文档

在线文档

• 交互式组件文档（Storybook）: 启动 Storybook 查看所有组件的交互示例和 API 文档
• VitePress 文档: 项目的详细使用指南和最佳实践

启动本地文档

Storybook（交互式文档）

Vue 版本：

npm run storybook

访问 http://localhost:6006

React 版本：

npx storybook dev -c .storybook --framework @storybook/react-vite -p 6007

访问 http://localhost:6007

VitePress（文档站点）

npm run docs:dev

构建文档

# 构建 Storybook
npm run build-storybook

# 构建 VitePress
npm run docs:build

组件列表

基础组件

| 组件名 | Vue | React | 说明 | |--------|-----|-------|------| | LwButton | ✅ | ✅ | 按钮，支持多种类型和状态 | | LwInput | ✅ | ✅ | 输入框，支持多种输入类型 | | LwTextarea | ✅ | ✅ | 多行文本输入 | | LwSearch | ✅ | ✅ | 搜索输入，内置搜索图标 | | LwIcon | ✅ | ✅ | 图标，支持自定义尺寸和颜色 |

更多组件开发中...

主题定制

CSS 变量

:root {
  /* 主题色 */
  --lw-primary: #409eff;
  --lw-success: #67c23a;
  --lw-warning: #e6a23c;
  --lw-danger: #f56c6c;
  --lw-info: #909399;

  /* 文字颜色 */
  --lw-text-primary: #303133;
  --lw-text-regular: #606266;
  --lw-text-secondary: #909399;
  --lw-text-placeholder: #c0c4cc;

  /* 边框颜色 */
  --lw-border-base: #dcdfe6;
  --lw-border-light: #e4e7ed;
  --lw-border-lighter: #ebeef5;
  --lw-border-extra-light: #f2f6fc;

  /* 背景颜色 */
  --lw-bg-color: #ffffff;
  --lw-bg-color-page: #f5f7fa;

  /* 圆角 */
  --lw-border-radius-base: 4px;
  --lw-border-radius-small: 2px;
  --lw-border-radius-large: 8px;

  /* 字体大小 */
  --lw-font-size-extra-large: 20px;
  --lw-font-size-large: 18px;
  --lw-font-size-medium: 16px;
  --lw-font-size-base: 14px;
  --lw-font-size-small: 13px;
  --lw-font-size-extra-small: 12px;
}

暗黑模式

// 开启暗黑模式
document.documentElement.setAttribute('data-theme', 'dark')

// 关闭暗黑模式
document.documentElement.setAttribute('data-theme', 'light')

开发

安装依赖

npm install

开发组件

1. 在 packages/vue/ 或 packages/react/ 中开发组件
2. 在 .storybook/stories/ 中添加对应的 stories 文件
3. 运行 Storybook 查看效果
4. 在 packages/styles/ 中添加或修改样式

可用脚本

# 构建组件库
npm run build

# 开发文档站点
npm run docs:dev

# 构建 Storybook
npm run build-storybook

# 启动 Storybook（Vue）
npm run storybook

浏览器支持

• Chrome >= 87
• Firefox >= 78
• Safari >= 14
• Edge >= 88

贡献指南

欢迎贡献代码！请遵循以下步骤：

1. Fork 本仓库
2. 创建你的特性分支 (git checkout -b feature/AmazingFeature)
3. 提交你的修改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启一个 Pull Request

开发规范

• 组件代码放在 packages/vue/ 或 packages/react/
• Stories 文件放在 .storybook/stories/vue/ 或 .storybook/stories/react/
• 样式文件放在 packages/styles/
• 遵循 TypeScript 类型规范
• 为新组件添加完整的 Storybook 文档

License

MIT

相关链接

• Storybook 文档
• 更新日志（待创建）
• 问题反馈