@yeepay/yee-boss-ui 0.1.20 → 0.1.22

package/README.md

@@ -12,13 +12,11 @@
 - `PlatformConfigProvider`。
 - `usePlatformTheme` 只读主题上下文。
 - `YeePage` 页面容器。
-- `YeeForm` Schema 查询表单。
-- `useYeeGrid` 与 `gridApi/formApi`。
+- `useYeeGrid` 与内置 Schema 查询区。
 - `YeeDescriptions` 配置驱动的详情展示。
 - `YeeEllipsisText` 单行/多行省略文本与按需完整提示。
 - `YeeFileUpload` 业务无关的文件选择与上传生命周期。
 - `YeeModal` 统一的 Modal / Drawer 容器。
-- `YeeSelect` 带完整文案提示的选择器。
 - `YeeAppShell`、`YeeHeader`、`YeeSidebar` 应用壳层布局。
 - `YeeMenu` 路由菜单样式与 `YeeTabs` 标签栏样式。
 - Tailwind CSS 语义主题 preset。
@@ -73,7 +71,7 @@ import '@yeepay/yee-boss-ui/style.css'
 createApp(App).use(YeeBossUI).mount('#app')
 ```
 
-组件库会自动注册 `YeeAppShell`、`YeeDescriptions`、`YeeEllipsisText`、`YeeFileUpload`、`YeeForm`、`YeeModal`、`YeePage`、`YeeSelect` 以及应用壳层组件。`useYeeGrid` 仍按组合式 API 使用，首次调用时会由组件库自动加载 Grid 样式。
+组件库会自动注册 `YeeAppShell`、`YeeDescriptions`、`YeeEllipsisText`、`YeeFileUpload`、`YeeModal`、`YeePage` 以及应用壳层组件。`useYeeGrid` 仍按组合式 API 使用，首次调用时会由组件库自动加载 Grid 样式；查询区只在 Grid 内部渲染。
 
 如果只希望在脚本中使用全部导出，也可以从包根入口统一导入：
 
@@ -84,12 +82,10 @@ import {
   YeeDescriptions,
   YeeEllipsisText,
   YeeFileUpload,
-  YeeForm,
-  YeeFormApi,
+  YeeGridFormApi,
   YeeHeader,
   YeeModal,
   YeePage,
-  YeeSelect,
   YeeSidebar,
   YeeTabs,
   useYeeGrid,
@@ -103,13 +99,32 @@ import {
 页面只使用少量能力、需要减少初始体积时，从根入口只导入实际使用的组件：
 
 ```ts
-import { YeeModal, YeePage, YeeSelect } from '@yeepay/yee-boss-ui'
-import type { YeeSelectOption } from '@yeepay/yee-boss-ui'
+import { YeeModal, YeePage } from '@yeepay/yee-boss-ui'
 import '@yeepay/yee-boss-ui/style.css'
 ```
 
 `style.css` 是唯一需要业务引入的组件样式入口。`useYeeGrid()` 首次执行时，组件库会自动加载内部 Grid 样式；业务不需要区分或引入其它样式文件。
 
+### Vite 模板自动导入
+
+如果项目使用 `unplugin-vue-components`，可以直接复用组件库提供的 resolver。它会按组件的 feature entry 自动注入导入，并生成 `GlobalComponents` 类型声明：
+
+```ts
+import { AntDesignVueResolver } from 'unplugin-vue-components/resolvers'
+import Components from 'unplugin-vue-components/vite'
+import { YeeBossUIResolver } from '@yeepay/yee-boss-ui/resolver'
+
+Components({
+  dts: 'src/types/components.d.ts',
+  resolvers: [
+    YeeBossUIResolver(),
+    AntDesignVueResolver(),
+  ],
+})
+```
+
+该 resolver 只覆盖可以按名称自动导入的公共组件；`useYeeGrid()` 返回的 Grid 适配器仍应在脚本中显式使用。
+
 ### 应用壳层
 
 应用壳层只提供布局和展示状态，不读取路由、权限、用户 Store 或 Wujie 上下文。菜单权限、路由跳转、标签增删、刷新、主题切换、全屏和用户操作由应用处理，再通过 Props、Events 和插槽接入。
@@ -220,11 +235,10 @@ import type {
   YeeFileUploadExpose,
   YeeGridSlots,
   YeeModalProps,
-  YeeSelectProps,
 } from '@yeepay/yee-boss-ui'
 ```
 
-`YeeModal` 和 `YeeSelect` 的 Props 同时包含 Ant Design Vue 原生透传属性。`useYeeGrid<Row, QueryValues>` 会把行类型传递给列、事件、查询函数和具名插槽，不需要在页面中重复断言类型。
+`YeeModal` 的 Props 包含 Ant Design Vue 原生透传属性。`useYeeGrid<Row, QueryValues>` 会把行类型传递给列、事件、查询函数和具名插槽，不需要在页面中重复断言类型。
 
 ## Tailwind CSS
 
@@ -377,80 +391,72 @@ async function submit(): Promise<void> {
 
 Drawer 模式使用 `<YeeModal v-model:open="open" type="drawer" placement="right">`，`placement`、`getContainer`、`zIndex` 等原生属性会继续透传。
 
-### YeeSelect
+### YeeGrid 查询区
 
-`YeeSelect` 保持 Ant Design Vue `Select` 的透传能力，并针对当前选中项和默认 option 提供完整文案提示。
+查询区不再作为独立组件提供。`useYeeGrid` 配置 `formOptions` 后，`YeeGrid` 内部会使用 Ant Design Vue `Form` / `FormItem` 渲染查询区。Schema 的 `component` 是判别字段，选择组件后，`componentProps` 会提示对应 Ant Design Vue 组件或 `YeeFileUpload` 的原生属性。
 
-```vue
-<script setup lang="ts">
-import { shallowRef } from 'vue'
-import {
-  YeeSelect,
-  type YeeSelectExpose,
-  type YeeSelectOption,
-  type YeeSelectValue,
-} from '@yeepay/yee-boss-ui'
+查询区默认使用 `layout: 'horizontal'`，标签右对齐；未设置 `labelWidth` 或传入 `labelWidth: 'auto'` 时，标签列按当前标签内容自适应。传入数字时使用固定标签宽度，例如 `labelWidth: 120`；需要上下排列时传入 `layout: 'vertical'`，此时标签左对齐且不使用 `labelWidth`。当字段的 `label` 为空字符串时，标签节点和标签间距都会省略，控件会占满当前字段区域。
 
-const status = shallowRef<YeeSelectValue>()
-const selectRef = shallowRef<YeeSelectExpose>()
-const statusOptions: YeeSelectOption[] = [
-  { label: '成功', value: 'SUCCESS' },
-  { label: '失败', value: 'FAILED' },
-]
+查询字段默认占用 1 列。可以在字段 Schema 上设置 `span` 控制字段（包括标签和值）横跨的网格列数，支持 `1`、`2`、`3`，例如 `span: 2` 表示占用两列：
 
-function focusSelect(): void {
-  selectRef.value?.focus()
+```ts
+{
+  component: 'Textarea',
+  componentProps: {
+    autoSize: { minRows: 1, maxRows: 3 },
+    placeholder: '请输入备注',
+  },
+  fieldName: 'remark',
+  label: '备注',
+  span: 2,
 }
-</script>
+```
 
-<template>
-  <YeeSelect
-    ref="selectRef"
-    v-model:value="status"
-    allow-clear
-    show-search
-    :options="statusOptions"
-  >
-    <template #option="option">
-      {{ option.label }}
-    </template>
-  </YeeSelect>
-  <a-button @click="focusSelect">
-    聚焦选择器
-  </a-button>
-</template>
+网格按屏幕宽度响应：默认（`>= 1024px`）为 3 列，`768px` 到 `1023px` 为 2 列，小于 `768px` 为 1 列。当 `span` 大于当前屏幕可用列数时，会自动收窄到当前可用列数，不会产生横向溢出。`span` 控制的是字段外层网格宽度，`labelWidth` 只控制水平布局中的标签列宽度。
+
+`span` 的类型是公开导出的 `YeeGridFormFieldSpan`（`1 | 2 | 3`），通常直接在 Schema 字面量中配置即可；需要单独声明布局变量时，可以从包根入口导入该类型：
+
+```ts
+import type { YeeGridFormFieldSpan } from '@yeepay/yee-boss-ui'
+
+const detailSpan: YeeGridFormFieldSpan = 2
 ```
 
-通过 `YeeSelectExpose` 可以调用 `focus()`、`blur()` 和 `scrollTo()`。`change`、`select`、`deselect`、`search`、`clear`、`focus`、`blur`、`popupScroll`、`dropdownVisibleChange` 等原生事件均有参数提示；`option`、`optionLabel`、`tagRender`、`dropdownRender`、`maxTagPlaceholder` 等作用域插槽也会提示对应参数。
+启用 `showCollapseButton` 时，`collapsedRows` 按实际网格行数计算，跨列字段会消耗对应的列数；字段无法完整放入当前行时会自动换到下一行。展开后仍会显示全部未隐藏字段。`gridApi.formApi.updateSchema` 也支持动态更新字段的 `span`。
 
-### YeeForm
+字段设置 `required: true` 后会参与必填校验。点击查询、按 Enter 查询或开启 `submitOnChange` 触发提交时，查询区会先校验所有未隐藏的必填字段；校验失败时不会发起查询，标签显示必填标记，Ant Design Vue 原生支持 `status` 的控件显示红色错误状态。错误信息不渲染在控件下方；字段修改后会重新校验已经出错的字段，重置查询会清除错误状态。
 
-`YeeForm` 可以独立使用，也会在 `useYeeGrid` 配置 `formOptions` 后自动挂载。Schema 的 `component` 是判别字段，选择组件后，`componentProps` 会提示对应 Ant Design Vue 组件或 `YeeFileUpload` 的原生属性。
+必填校验将 `undefined`、`null`、空字符串（包括只包含空白字符的字符串）、空数组和 `NaN` 视为空值；`false`、`0` 和空对象会被视为有值。隐藏字段不会参与校验。
 
 内置支持：`AutoComplete`、`Cascader`、`Checkbox`、`CheckboxGroup`、`DatePicker`、`Input`、`InputNumber`、`InputPassword`、`Mentions`、`Radio`、`RadioGroup`、`RangePicker`、`Rate`、`Segmented`、`Select`、`Slider`、`Switch`、`Textarea`、`TimePicker`、`TimeRangePicker`、`TreeSelect` 和 `Upload`。
 
 ```vue
 <script setup lang="ts">
-import {
-  YeeForm,
-  YeeFormApi,
-  type YeeFormOptions,
-} from '@yeepay/yee-boss-ui'
+import { useYeeGrid } from '@yeepay/yee-boss-ui'
+import type { YeeGridFormOptions, YeeGridOptions, YeeGridPage, YeeGridQueryParams } from '@yeepay/yee-boss-ui'
 
 interface QueryValues {
   channel?: 'OFFLINE' | 'ONLINE'
   enabled?: boolean
   orderNo?: string
+  remark?: string
 }
 
-const formApi = new YeeFormApi<QueryValues>()
-const formOptions: YeeFormOptions<QueryValues> = {
+const formOptions: YeeGridFormOptions<QueryValues> = {
   schema: [
     {
       component: 'Input',
       componentProps: { allowClear: true, placeholder: '请输入订单号' },
       fieldName: 'orderNo',
       label: '订单号',
+      required: true,
+    },
+    {
+      component: 'Textarea',
+      componentProps: { autoSize: { minRows: 1, maxRows: 3 }, placeholder: '请输入备注' },
+      fieldName: 'remark',
+      label: '备注',
+      span: 2,
     },
     {
       component: 'Switch',
@@ -465,25 +471,46 @@ const formOptions: YeeFormOptions<QueryValues> = {
   ],
 }
 
-function query(values: QueryValues): void {
-  console.info(values.orderNo)
+const gridOptions: YeeGridOptions<{ orderNo: string }, QueryValues> = {
+  columns: [{ field: 'orderNo', title: '订单号' }],
+  proxyConfig: {
+    ajax: {
+      query: async (
+        _params: YeeGridQueryParams<{ orderNo: string }>,
+        values: QueryValues,
+      ): Promise<YeeGridPage<{ orderNo: string }>> => ({
+        items: [{ orderNo: values.orderNo ?? '-' }],
+        total: 1,
+      }),
+    },
+  },
 }
+
+const [OrderGrid] = useYeeGrid({ formOptions, gridOptions })
 </script>
 
 <template>
-  <YeeForm :api="formApi" :on-submit="query" :options="formOptions">
-    <template #channel="{ field, setValue, value, values }">
+  <OrderGrid>
+    <template #form-channel="{ field, setValue, value, values }">
       <button type="button" @click="setValue(value === 'ONLINE' ? 'OFFLINE' : 'ONLINE')">
         {{ field.label }}：{{ values.channel ?? '未选择' }}
       </button>
     </template>
-  </YeeForm>
+  </OrderGrid>
 </template>
 ```
 
-字段同名插槽可以覆盖任意内置组件；只使用自定义内容时，将 `component` 设置为 `Custom`。插槽提供 `field`、`value`、`values` 和 `setValue`，其中字段值会根据 `QueryValues` 自动提示类型，并统一写回 `YeeFormApi`。
+查询字段插槽使用 `form-${fieldName}` 命名，可以覆盖任意内置组件；只使用自定义内容时，将 `component` 设置为 `Custom`。插槽提供 `field`、`value`、`values` 和 `setValue`，其中字段值会根据 `QueryValues` 自动提示类型，并统一写回 `gridApi.formApi`。
 
-`YeeFormApi` 提供 `getFieldValue`、`getValues`、`setFieldValue`、`setValues`、`resetForm` 和 `updateSchema`；字段名和值会保持 `QueryValues` 中声明的类型。
+`gridApi.formApi` 提供 `getFieldValue`、`getValues`、`setFieldValue`、`setValues`、`resetForm` 和 `updateSchema`；字段名和值会保持 `QueryValues` 中声明的类型。
+
+例如，字段已经存在时可以只更新它的布局：
+
+```ts
+gridApi.formApi.updateSchema([
+  { fieldName: 'remark', span: 3 },
+])
+```
 
 ## YeePage 与 VXE Grid
 
@@ -495,7 +522,7 @@ function query(values: QueryValues): void {
 
 ```vue
 <script setup lang="ts">
-import type { YeeFormOptions, YeeGridOptions } from '@yeepay/yee-boss-ui'
+import type { YeeGridFormOptions, YeeGridOptions } from '@yeepay/yee-boss-ui'
 import { useYeeGrid, YeePage } from '@yeepay/yee-boss-ui'
 
 interface OrderItem {
@@ -506,7 +533,7 @@ interface QueryValues {
   orderNo?: string
 }
 
-const formOptions: YeeFormOptions<QueryValues> = {
+const formOptions: YeeGridFormOptions<QueryValues> = {
   schema: [
     {
       component: 'Input',
@@ -576,7 +603,7 @@ defineExpose({ reload: gridApi.reload })
 
 `table-title`、`toolbar-actions`、`toolbar-tools` 以及列配置中的具名插槽都有类型提示，其中列插槽的 `row` 会保持 `OrderItem` 类型。`YeeGridApi` 提供 `query`、`reload`、`setGridOptions`、`setLoading`、`setState` 和 `toggleSearchForm`；需要隐藏查询区时，可在 `useYeeGrid` 配置中设置 `showSearchForm: false`，不再提供工具栏显隐按钮。
 
-组件的 TypeScript 导出使用 `YeeForm`、`YeeGrid`、`YeePage`，Vue 模板标签对应 `yee-form`、`yee-grid`、`yee-page`。新代码统一使用 `useYeeGrid`，不提供旧命名兼容别名。查询接口统一返回 `{ items, total }`。
+组件的 TypeScript 导出使用 `YeeGrid`（由 `useYeeGrid` 返回）和 `YeePage`，Vue 模板标签对应 `yee-grid`、`yee-page`。查询区只通过 `YeeGrid` 的 `formOptions` 配置，不再提供独立查询表单组件。查询接口统一返回 `{ items, total }`。
 
 ## 开发