Sunlight UI

主题

Teeker2025-12-14
1379
6.4m

快速开始 ​

使用条件 ​

信息

  • Node.js 16.0.0 及以上版本
  • Vue 3.2.0 及以上版本
  • ElementPlus 2.0.0 及以上版本
  • 在使用 Sunlight-ui 前，要求至少会 Vue3 和 ElementPlus 的基本使用

验证你的环境是否满足以上要求，你可以通过以下命令查看版本：

sh
# 查看 Node.js 版本
node -v

# 查看 Vue 版本（在项目目录下）
npm list vue

# 查看 ElementPlus 版本（在项目目录下）
npm list element-plus

建议使用如下包管理器安装：

VSCode 插件 ​

推荐使用 VSCode/Cursor 进行开发，以下为推荐的插件：

安装 Sunlight-ui ​

方式一：通过 npm/yarn/pnpm 安装 ​

在你的 Vue3 项目中执行以下命令安装 Sunlight-ui：

sh
npm install sunlight-ui
sh
yarn add sunlight-ui
sh
pnpm add sunlight-ui

方式二：本地开发安装 ​

如果你需要在本地开发或贡献代码，可以克隆仓库并安装：

sh
# 克隆仓库
git clone <sunlight-ui-repository-url>

# 进入目录
cd sunlight-ui

# 安装依赖
pnpm install

# 构建组件库
pnpm build

配置 Sunlight-ui ​

全局配置 ​

在项目入口文件（通常是 main.ts 或 main.js）中配置 Sunlight-ui：

ts
import { createApp } from 'vue'
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'
import SunlightUI from 'sunlight-ui'
import 'sunlight-ui/dist/style.css'
import App from './App.vue'

const app = createApp(App)

// 配置 ElementPlus
app.use(ElementPlus)

// 配置 Sunlight-ui
app.use(SunlightUI, {
  // 全局配置项
  table: {
    // 表格组件全局配置
    defaultPageSize: 10, // 默认每页条数
    defaultLayout: 'total, sizes, prev, pager, next, jumper' // 默认分页布局
  },
  input: {
    // 输入框组件全局配置
    defaultClearable: true // 默认显示清除按钮
  }
})

app.mount('#app')

局部配置 ​

在单个组件中使用 Sunlight-ui 组件时，可以通过 props 进行局部配置，局部配置会覆盖全局配置：

vue
<template>
  <div>
    <!-- 表格组件局部配置 -->
    <SunlightTable
      :data="tableData"
      :columns="columns"
      :page-size="20" <!-- 局部配置每页条数，覆盖全局配置 -->
      :layout="'total, prev, pager, next'" <!-- 局部配置分页布局 -->
    />

    <!-- 输入框组件局部配置 -->
    <SunlightInput
      v-model="inputValue"
      :clearable="false" <!-- 局部配置不显示清除按钮，覆盖全局配置 -->
      placeholder="请输入内容"
    />
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { SunlightTable, SunlightInput } from 'sunlight-ui'

// 表格数据
const tableData = ref([
  { id: 1, name: '张三', age: 28, status: '启用' },
  { id: 2, name: '李四', age: 32, status: '禁用' }
])

// 表格列配置
const columns = ref([
  { prop: 'id', label: 'ID', width: 80 },
  { prop: 'name', label: '姓名', width: 120 },
  { prop: 'age', label: '年龄', width: 80 },
  { prop: 'status', label: '状态', width: 100 }
])

// 输入框数据
const inputValue = ref('')
</script>

基本使用示例 ​

使用 SunlightTable 组件 ​

vue
<template>
  <div>
    <h3>表格组件示例</h3>
    <SunlightTable
      :data="tableData"
      :columns="columns"
      v-model:hide-columns="hideColumns"
      :show-toolbar="true"
      :show-pagination="true"
    />
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { SunlightTable } from 'sunlight-ui'

// 表格数据
const tableData = ref([
  { id: 1, name: '张三', age: 28, status: '启用', email: 'zhangsan@example.com' },
  { id: 2, name: '李四', age: 32, status: '禁用', email: 'lisi@example.com' },
  { id: 3, name: '王五', age: 25, status: '启用', email: 'wangwu@example.com' }
])

// 表格列配置
const columns = ref([
  { prop: 'id', label: 'ID', width: 80 },
  { prop: 'name', label: '姓名', width: 120 },
  { prop: 'age', label: '年龄', width: 80 },
  { prop: 'status', label: '状态', width: 100 },
  { prop: 'email', label: '邮箱' }
])

// 隐藏列配置
const hideColumns = ref(['email']) // 默认隐藏邮箱列
</script>

使用 SunlightInput 组件 ​

vue
<template>
  <div>
    <h3>输入框组件示例</h3>
    <SunlightInput
      v-model="inputValue"
      :clearable="true"
      :placeholder="'请输入内容'"
      @input="handleInput"
      @change="handleChange"
      @focus="handleFocus"
      @blur="handleBlur"
      @clear="handleClear"
      @keydown="handleKeydown"
    />
    
    <div style="margin-top: 20px;">
      <h4>事件触发状态：</h4>
      <ul>
        <li>input 事件：{{ eventStatus.input ? '✅' : '❌' }}</li>
        <li>change 事件：{{ eventStatus.change ? '✅' : '❌' }}</li>
        <li>focus 事件：{{ eventStatus.focus ? '✅' : '❌' }}</li>
        <li>blur 事件：{{ eventStatus.blur ? '✅' : '❌' }}</li>
        <li>clear 事件：{{ eventStatus.clear ? '✅' : '❌' }}</li>
        <li>keydown 事件：{{ eventStatus.keydown ? '✅' : '❌' }}</li>
      </ul>
    </div>
  </div>
</template>

<script setup lang="ts">
import { ref, reactive } from 'vue'
import { SunlightInput } from 'sunlight-ui'

// 输入框数据
const inputValue = ref('')

// 事件状态
const eventStatus = reactive({
  input: false,
  change: false,
  focus: false,
  blur: false,
  clear: false,
  keydown: false
})

// 事件处理函数
const handleInput = (value: string) => {
  eventStatus.input = true
  setTimeout(() => { eventStatus.input = false }, 500)
}

const handleChange = (value: string) => {
  eventStatus.change = true
  setTimeout(() => { eventStatus.change = false }, 500)
}

const handleFocus = () => {
  eventStatus.focus = true
  setTimeout(() => { eventStatus.focus = false }, 500)
}

const handleBlur = () => {
  eventStatus.blur = true
  setTimeout(() => { eventStatus.blur = false }, 500)
}

const handleClear = () => {
  eventStatus.clear = true
  setTimeout(() => { eventStatus.clear = false }, 500)
}

const handleKeydown = (e: KeyboardEvent) => {
  eventStatus.keydown = true
  setTimeout(() => { eventStatus.keydown = false }, 500)
}
</script>

开发流程 ​

创建新组件 ​

  1. 在 src/components 目录下创建新组件文件夹
  2. 编写组件代码，遵循 Vue3 Composition API 和 TypeScript 规范
  3. 在 src/index.ts 中导出新组件
  4. 编写组件文档和示例

运行开发服务器 ​

sh
# 启动开发服务器
pnpm dev

构建组件库 ​

sh
# 构建组件库
pnpm build

运行测试 ​

sh
# 运行单元测试
pnpm test

# 运行 ESLint 检查
pnpm lint

常见问题 ​

1. 为什么组件样式不生效？ ​

请确保你已经正确导入了样式文件：

ts
import 'sunlight-ui/dist/style.css'

2. 为什么全局配置不生效？ ​

请确保在使用组件之前配置 Sunlight-ui：

ts
// 先配置
app.use(SunlightUI, {
  // 配置项
})

// 再挂载应用
app.mount('#app')

3. 如何自定义组件样式？ ​

你可以通过以下方式自定义组件样式：

  1. 使用 CSS 选择器覆盖样式
  2. 使用 ElementPlus 的主题定制功能
  3. 通过组件的 class 或 style 属性自定义

更多使用请参考各组件的详细文档。