@bscjc/webui 0.0.2

package/README.md

@@ -0,0 +1,476 @@
+# @bscjc/webui
+
+一个 Vue3 组件库，使用 Vite，Element Plus 和 TypeScript 构建
+
+# webui 组件库文档
+
+## 目录
+
+- [组件目录介绍](#组件目录介绍)
+- [安装使用说明](#安装使用说明)
+- [组件文档](#组件文档)
+  - [JcSelectQuery](#JcSelectQuery)
+  - [JcDatePicker](#JcDatePicker)
+  - [JcInputSwitch](#JcInputSwitch)
+  - [JcInputComplex](#JcInputComplex)
+  - [JcTagQuery](#JcTagQuery)
+  - [JcMoreQueryContain](#JcMoreQueryContain)
+- [配套 Hooks 使用说明](#配套Hooks使用说明)
+
+## 组件目录介绍
+
+@bscjc/webui 是一个基于 Element Plus 的 Vue3 组件库，包含以下组件：
+
+| 组件名             | 说明                                          |
+| ------------------ | --------------------------------------------- |
+| JcSelectQuery      | 下拉选择器组件，支持多选、shi、搜索和全选功能 |
+| JcDatePicker       | 日期选择器组件，支持日期范围和月份范围选择    |
+| JcInputSwitch      | 输入切换组件，支持多字段切换输入              |
+| JcInputComplex     | 复杂输入切换组件，支持单行和多行文本输入      |
+| JcTagQuery         | 标签查询组件，用于展示和管理查询标签          |
+| JcMoreQueryContain | 查询容器，用于包裹更多查询条件                |
+
+## 安装使用说明
+
+### 安装
+
+```shell
+npm i @bscjc/webui
+```
+
+### 完整导入
+
+```typescript
+// src/main.ts
+import { createApp } from "vue";
+import App from "./App.vue";
+import JcWebui from "@bscjc/webui";
+import "@bscjc/webui/dist/style.css";
+
+const app = createApp(App);
+app.use(JcWebui);
+app.mount("#app");
+```
+
+### 按需导入
+
+```vue
+<template>
+  <jc-select-query
+    ref="selectRef"
+    field="selectList"
+    :options="options"
+    @change="(val:any) => console.log(val)"
+  >
+  </jc-select-query>
+</template>
+
+<script setup>
+import { JcSelectQuery } from "@bscjc/webui";
+</script>
+```
+
+## 组件文档
+
+### JcSelectQuery
+
+#### 概述
+
+基于 Element Plus 的`el-select`组件封装，支持多选、搜索、全选和虚拟滚动等高级功能。
+
+#### 基本使用
+
+```vue
+<template>
+  <jc-select-query :options="options" field="selectedList" />
+</template>
+
+<script setup lang="ts">
+import { ref } from "vue";
+import { JcSelectQuery } from "@bscjc/webui";
+const options = ref([
+  { label: "选项1", value: "1" },
+  { label: "选项2", value: "2" },
+  { label: "选项3", value: "3" },
+]);
+</script>
+```
+
+#### 核心功能
+
+1. 支持多选和全选操作
+2. 内置搜索功能，支持模糊匹配
+3. 支持虚拟滚动，优化大数据量渲染
+4. 支持创建新选项
+5. 支持按住 Shift 键快速多选
+
+#### Props
+
+| 参数            | 类型                                  | 默认值             | 说明                 |
+| --------------- | ------------------------------------- | ------------------ | -------------------- |
+| field           | string                                | -                  | 绑定的字段名，必填   |
+| options         | Array<{label: string, value: string}> | []                 | 选项数据，必填       |
+| allowCreate     | boolean                               | true               | 是否允许创建新选项   |
+| keyField        | Array<string>                         | ['label', 'value'] | 选项的键名配置       |
+| width           | string                                | '160px'            | 组件宽度             |
+| size            | 'small' \| 'default' \| 'large'       | 'default'          | 组件尺寸             |
+| footerBtnName   | string                                | '搜索'             | 底部按钮文本         |
+| maxScrollHeight | string                                | '240px'            | 下拉框最大高度       |
+| isNeedFooter    | boolean                               | true               | 是否显示底部按钮区域 |
+
+#### Events
+
+| 事件名         | 参数             | 说明                  |
+| -------------- | ---------------- | --------------------- |
+| change         | value: string[]  | 选中值变化时触发      |
+| remove-tag     | tag: any         | 移除标签时触发        |
+| visible-change | visible: boolean | 下拉框显示/隐藏时触发 |
+
+#### 方法
+
+| 方法名 | 说明       |
+| ------ | ---------- |
+| focus  | 获取焦点   |
+| blur   | 失去焦点   |
+| clear  | 清空选中值 |
+
+#### 原组件 API
+
+继承自 Element Plus 的`el-select`组件，支持其所有 Props 和 Events。
+
+### JcDatePicker
+
+#### 概述
+
+基于 Element Plus 的`el-date-picker`组件封装，支持多字段切换的日期选择功能。
+
+#### 基本使用
+
+```vue
+<template>
+  <jc-date-picker :field-list="fieldList" />
+</template>
+
+<script setup lang="ts">
+import { ref } from "vue";
+import { JcDatePicker } from "@bscjc/webui";
+
+const fieldList = ref([
+  { label: "创建时间", value: "createTimeList" },
+  { label: "更新时间", value: "updateTimeList" },
+]);
+</script>
+```
+
+#### 核心功能
+
+1. 支持多字段切换选择
+2. 支持日期范围和月份范围选择
+3. 自动集成查询表单状态管理
+
+#### Props
+
+| 参数      | 类型                                  | 默认值      | 说明           |
+| --------- | ------------------------------------- | ----------- | -------------- |
+| fieldList | Array<{label: string, value: string}> | []          | 字段列表，必填 |
+| type      | 'daterange' \| 'monthrange'           | 'daterange' | 日期选择类型   |
+| size      | 'small' \| 'default' \| 'large'       | 'default'   | 组件尺寸       |
+| width     | string                                | '320px'     | 日期选择器宽度 |
+
+#### Events
+
+| 事件名      | 参数        | 说明             |
+| ----------- | ----------- | ---------------- |
+| fieldChange | val: string | 字段切换时触发   |
+| change      | val: any    | 日期值变化时触发 |
+
+#### 方法
+
+| 方法名      | 说明             |
+| ----------- | ---------------- |
+| focus       | 获取焦点         |
+| blur        | 失去焦点         |
+| handleOpen  | 打开日期选择面板 |
+| handleClose | 关闭日期选择面板 |
+
+#### 原组件 API
+
+继承自 Element Plus 的`el-date-picker`组件，支持其所有 Props 和 Events。
+
+### JcInputSwitch
+
+#### 概述
+
+基于 Element Plus 的`el-input`组件封装，支持多字段切换的输入组件。
+
+#### 基本使用
+
+```vue
+<template>
+  <jc-input-switch :field-list="fieldList" />
+</template>
+
+<script setup lang="ts">
+import { ref } from "vue";
+import { JcInputSwitch } from "@bscjc/webui";
+
+const fieldList = ref([
+  { label: "名称", value: "name" },
+  { label: "ID", value: "id" },
+]);
+</script>
+```
+
+#### 核心功能
+
+1. 支持多字段切换输入
+2. 内置清除和搜索功能
+3. 自动集成查询表单状态管理
+
+#### Props
+
+| 参数      | 类型                                  | 默认值    | 说明           |
+| --------- | ------------------------------------- | --------- | -------------- |
+| fieldList | Array<{label: string, value: string}> | []        | 字段列表，必填 |
+| size      | 'small' \| 'default' \| 'large'       | 'default' | 组件尺寸       |
+| width     | string                                | '320px'   | 组件宽度       |
+
+#### Events
+
+| 事件名      | 参数        | 说明             |
+| ----------- | ----------- | ---------------- |
+| fieldChange | val: string | 字段切换时触发   |
+| input       | val: string | 输入值变化时触发 |
+
+#### 方法
+
+| 方法名 | 说明       |
+| ------ | ---------- |
+| focus  | 获取焦点   |
+| blur   | 失去焦点   |
+| clear  | 清空输入值 |
+
+#### 原组件 API
+
+继承自 Element Plus 的`el-input`组件，支持其所有 Props 和 Events。
+
+### JcInputComplex
+
+#### 概述
+
+基于 Element Plus 的`el-input`组件封装，支持单行和多行文本输入的复杂输入组件。
+
+#### 基本使用
+
+```vue
+<template>
+  <jc-input-complex :field-list="fieldList" />
+</template>
+
+<script setup lang="ts">
+import { ref } from "vue";
+import { JcInputComplex } from "@bscjc/webui";
+
+const fieldList = ref([
+  { label: "关键词", value: "keyword" },
+  { label: "描述", value: "description" },
+]);
+</script>
+```
+
+#### 核心功能
+
+1. 支持多字段切换输入
+2. 支持单行和多行文本输入切换
+3. 内置清除和搜索功能
+4. 自动集成查询表单状态管理
+
+#### Props
+
+| 参数      | 类型                                  | 默认值    | 说明           |
+| --------- | ------------------------------------- | --------- | -------------- |
+| fieldList | Array<{label: string, value: string}> | []        | 字段列表，必填 |
+| size      | 'small' \| 'default' \| 'large'       | 'default' | 组件尺寸       |
+| width     | string                                | '320px'   | 组件宽度       |
+
+#### Events
+
+| 事件名      | 参数        | 说明             |
+| ----------- | ----------- | ---------------- |
+| fieldChange | val: string | 字段切换时触发   |
+| input       | val: string | 输入值变化时触发 |
+
+#### 方法
+
+| 方法名 | 说明       |
+| ------ | ---------- |
+| focus  | 获取焦点   |
+| blur   | 失去焦点   |
+| clear  | 清空输入值 |
+
+#### 原组件 API
+
+继承自 Element Plus 的`el-input`组件，支持其所有 Props 和 Events。
+
+### JcTagQuery
+
+#### 概述
+
+基于 Element Plus 的`el-tag`组件封装，用于展示和管理查询标签的组件。
+
+#### 基本使用
+
+```vue
+<template>
+  <jc-tag-query />
+</template>
+
+<script setup lang="ts">
+import { JcTagQuery } from "@bscjc/webui";
+</script>
+```
+
+#### 核心功能
+
+1. 展示当前查询条件标签
+2. 支持单个标签删除
+3. 支持全部标签清除
+
+#### Props
+
+| 参数     | 类型    | 默认值  | 说明       |
+| -------- | ------- | ------- | ---------- |
+| closable | boolean | true    | 是否可关闭 |
+| type     | string  | 'info'  | 标签类型   |
+| effect   | string  | 'light' | 标签主题   |
+
+#### Events
+
+| 事件名 | 参数                       | 说明           |
+| ------ | -------------------------- | -------------- |
+| close  | tag: object, index: number | 标签关闭时触发 |
+| click  | tag: object, index: number | 点击标签时触发 |
+
+#### 原组件 API
+
+继承自 Element Plus 的`el-tag`组件，支持其所有 Props 和 Events。
+
+### JcMoreQueryContain
+
+#### 概述
+
+基于 Element Plus 的`el-popover`组件封装，用于包裹更多查询条件的高级查询容器。
+
+#### 基本使用
+
+```vue
+<template>
+  <jc-more-query-contain :field-list="fieldList" :width="500" :size="'small'">
+    <!-- 高级查询条件内容 -->
+    <el-form-item label="状态">
+      <el-select v-model="moreQueryForm.status" placeholder="请选择状态">
+        <el-option label="启用" value="1"></el-option>
+        <el-option label="禁用" value="0"></el-option>
+      </el-select>
+    </el-form-item>
+  </jc-more-query-contain>
+</template>
+
+<script setup lang="ts">
+import { ref } from "vue";
+import { JcMoreQueryContain } from "@bscjc/webui";
+const fieldList = ref([
+  { label: "状态", value: "status" },
+  { label: "类型", value: "type" },
+]);
+const moreQueryForm = ref({ status: "", type: "" });
+</script>
+```
+
+#### 核心功能
+
+1. 弹出式高级查询面板
+2. 支持多字段复杂查询
+3. 内置清空和搜索功能
+4. 自动集成查询表单状态管理
+
+#### Props
+
+| 参数         | 类型                                  | 默认值    | 说明           |
+| ------------ | ------------------------------------- | --------- | -------------- |
+| fieldList    | Array<{label: string, value: string}> | []        | 字段列表，必填 |
+| customTagObj | { [key: string]: string }             | {}        | 自定义标签对象 |
+| width        | number                                | 400       | 弹窗宽度       |
+| size         | 'small' \| 'default' \| 'large'       | 'default' | 组件尺寸       |
+
+#### Events
+
+| 事件名 | 参数 | 说明               |
+| ------ | ---- | ------------------ |
+| clear  | -    | 清空按钮点击时触发 |
+| search | -    | 搜索按钮点击时触发 |
+
+#### 方法
+
+| 方法名 | 说明         |
+| ------ | ------------ |
+| hide   | 隐藏 popover |
+
+#### 原组件 API
+
+继承自 Element Plus 的`el-popover`组件，支持其所有 Props 和 Events。
+
+## 配套 Hooks 使用说明
+
+### useQuery.ts
+
+#### 概述
+
+`useQuery`是 QueryFormComponents 组件库的配套 Hooks，提供查询表单状态管理功能。
+
+#### 基本使用
+
+```typescript
+import { reactiveQuery } from from "@bscjc/webui"
+const { queryForm, setQuery, addTag, reduceTag, reduceAllTag, clearQuery } = reactiveQuery()
+
+// 设置查询条件
+setQuery('name', 'test')
+
+// 添加标签
+addTag({ label: 'name', value: '名称:test' })
+
+// 移除标签
+reduceTag({ label: 'name', value: '名称:test' })
+
+// 移除所有标签
+reduceAllTag()
+
+// 清空查询条件
+clearQuery()
+```
+
+#### 方法
+
+| 方法名       | 参数                                  | 说明             |
+| ------------ | ------------------------------------- | ---------------- |
+| setQuery     | key: string, value: any               | 设置查询条件     |
+| addTag       | tag: { label: string, value: string } | 添加查询标签     |
+| reduceTag    | tag: { label: string, value: string } | 移除指定标签     |
+| reduceAllTag | -                                     | 移除所有标签     |
+| clearQuery   | -                                     | 清空所有查询条件 |
+
+#### 返回值
+
+| 名称         | 类型     | 说明               |
+| ------------ | -------- | ------------------ |
+| queryForm    | object   | 响应式查询表单对象 |
+| setQuery     | Function | 设置查询条件的方法 |
+| addTag       | Function | 添加标签的方法     |
+| reduceTag    | Function | 移除标签的方法     |
+| reduceAllTag | Function | 移除所有标签的方法 |
+| clearQuery   | Function | 清空查询条件的方法 |
+
+## License
+
+MIT