@das-fed/upf-ui 6.4.0-dev.311 → 6.4.0-dev.312

package/packages/components/search-form/skills/DasSearchForm/345/215/207/347/272/247/346/214/207/345/215/227.md

@@ -0,0 +1,141 @@
+# DasSearchForm 升级指南
+
+本文以当前最新 `DasSearchForm` 实现为准，说明从旧版表单迁移到工具栏布局、接入园区/楼栋通用筛选，以及保证业务请求时序正确的完整方式。它不是某个业务页面的复制模板；示例中的 `options`、列表接口和业务字段必须替换为目标页面自己的实现。
+
+## 1. 这次改动解决了什么
+
+新版 toolbar 不只是换布局，核心变化是把多园区空间筛选抽离成公共能力，弥补之前的项目切换：
+
+1. 业务原本接口的请求参数保持不变。页面需要按空间过滤时才配置空间控件；不需要空间过滤时不配置，组件不会请求园区数据，也不会生成空间条件。
+2. 公共请求层会把 `park(园区)`、`building(园区下空间)` 提升到 URL query；后端统一从 query 读取，POST/GET 等请求保持同一约定。
+3. 园区变化时先清空旧楼栋和普通筛选状态，加载新园区对应空间数据后再提交查询；楼栋实际变化后提交一次最新查询。
+6. `spaceChange` 只用于通知空间状态变化，不应在其中再次请求业务列表；业务查询统一使用 `@confirm`。
+
+## 2. 迁移前后
+
+### 旧版
+
+```vue
+<DasSearchForm ref="searchFormRef" :options="options" @confirm="searchData" />
+```
+
+旧版默认是 `legacy`，字段可能按历史配置自动触发查询。迁移前应盘点字段回调、日期/重复规则、弹窗提交、分页和导出的所有请求路径。
+
+### toolbar 版
+
+```vue
+<DasSearchForm
+  ref="searchFormRef"
+  layout-mode="toolbar"
+  :options="options"
+  :space-config="{
+    visible: true,
+    showPark: true,
+    showBuilding: true,
+    defaultPark: true,
+    parkMultiple: true,
+    buildingMultiple: false,
+  }"
+  @confirm="searchData"
+  @reset="resetAuxiliary"
+  @space-change="handleSpaceChange"
+  @space-error="handleSpaceError"
+/>
+```
+
+toolbar 中普通字段变化只更新字段并执行字段回调，不自动提交列表查询；点击查询、调用实例 `confirm()`，以及空间初始化/园区联动完成后的内部确认会触发 `confirm`。字段回调中不要保留会造成重复列表请求的逻辑。
+
+## 3. Props 与空间配置
+
+以下是 toolbar 相关公共 Props：
+
+| Prop | 默认值 | 说明 |
+| --- | --- | --- |
+| `layoutMode` | `legacy` | 传 `toolbar` 启用新版；不传不改变旧页面。 |
+| `options` | `[]` | 普通筛选字段配置，可为 `null`。为空时不渲染普通筛选区域及查询/重置按钮，但空间控件仍可独立显示。 |
+| `spaceConfig` | `{}` | 控制园区/楼栋显示、选择模式、默认值和数据源。 |
+| `spaceValue` | 空空间值 | 受控空间状态，结构为 `{ parkIds: [], buildingIds: [] }`；推荐使用 `v-model:space-value` 接收组件变更。 |
+| `searchOrder` | `last` | toolbar 普通字段的排列策略，不改变请求参数。 |
+
+### `spaceConfig`
+
+| 字段 | 默认值 | 行为 |
+| --- | --- | --- |
+| `visible` | `false` | 空间能力总开关。关闭时不显示内置控件、不加载默认园区数据，也不输出 `park/building`。 |
+| `showPark` | 跟随 `visible` | 是否显示园区下拉；关闭时 `confirm` 不输出 `park`。 |
+| `showBuilding` | 跟随 `visible` | 是否显示楼栋/空间树；关闭时 `confirm` 不输出 `building`。 |
+| `defaultPark` | `true` | 园区列表加载后且外部没有有效园区值时，是否自动选中第一项。关闭时不补默认园区，但仍会完成空间初始化并提交一次不带默认 `park` 的首次查询。 |
+| `parkMultiple` | `true` | 园区是否多选。多选时 `confirm.park` 为 ID 数组；单选时为单个 ID 或空字符串。 |
+| `buildingMultiple` | `false` | 楼栋/空间是否多选。`confirm.building` 始终是 ID 数组。 |
+| `size` | `small` | 同时控制园区和楼栋控件尺寸。 |
+| `load` | 默认数据源 | 自定义 `(signal) => Promise<{ parks, buildings }>`，提供后替代默认空间请求；应遵守 `AbortSignal`。 |
+
+### 配置边界
+
+- 只有 `visible=true` 且至少一个空间控件启用时，组件才需要完成空间初始化并建立首次查询。
+- `visible=true, showPark=false, showBuilding=true` 时，默认楼栋树缺少当前园区上下文；需要业务通过 `load` 返回完整可用树，不能期待组件自动选择全部园区。
+- 仅显示园区时仍会加载园区列表；不显示楼栋时不会请求楼栋详情或空间树。
+- 没有任何空间控件时，组件不初始化园区数据，不影响普通业务查询的首次加载。
+
+## 4. confirm、spaceChange 与请求时序
+
+### `confirm(formValues, selectedSpace)`
+
+`confirm` 是业务列表查询的唯一推荐入口：
+
+- `formValues` 是当前提交快照，包含普通字段和当前可见空间字段。
+- 园区控件显示时字段名为 `park`；多选为数组，单选为标量，无选择时分别为 `[]` 或 `''`。
+- 楼栋控件显示时字段名为 `building`，值为楼栋/楼层/空间 ID 数组。
+- 控件隐藏时对应字段被省略，不是 `undefined` 或空数组。
+- `selectedSpace` 是内部空间状态快照，结构为 `parkIds/buildingIds`，主要用于受控同步和调试；业务请求优先读取第一个参数。
+
+组件保证以下时序：
+
+1. 空间初始化未完成时，查询按钮和 `confirm()` 都不会提交业务查询。
+2. 初始化完成后只提交一次首次查询；`defaultPark` 只决定是否补选第一项，不决定是否跳过首次查询。
+3. 园区切换会先发布新园区并清空楼栋，再加载新园区空间数据，最后用最新空间快照确认。
+4. 楼栋选择实际改变后确认一次；同一个值被控件重复回写时不会再次确认。
+5. 选择已加载节点不会额外请求业务列表以外的空间详情；展开未加载节点可能触发合法的楼栋子节点懒加载。
+
+### `spaceChange`
+
+`spaceChange` 在空间状态实际变化时触发，参数是复制后的 `{ parkIds, buildingIds }`。它适合：
+
+- 同步父组件的 `spaceValue`；
+- 更新页面标题、权限或其它依赖空间的 UI 状态；
+
+不要在 `spaceChange` 中直接调用业务列表接口，也不要再手动调用 `confirm`。空间选择完成后的业务查询由组件统一触发 `confirm`。
+
+
+## 5. reset 与实例方法
+
+`DasSearchForm` 对外转发以下实例方法：
+
+| 方法 | 用途 |
+| --- | --- |
+| `confirm()` | 等待字段异步回调完成后提交当前查询快照。空间未初始化完成时不会提交。 |
+| `resetSearch()` | 恢复 `options` 的初始值，触发一次 `reset`，随后提交一次确认；默认保留园区/楼栋。 |
+| `closeSearch(target)` | 清理指定普通筛选字段并触发 `clearSearch`；不修改空间状态。 |
+| `treeSelectResetLazyLoad(key)` | 重置指定普通树选择字段的懒加载状态。 |
+| `getCollapseStatus()` | 读取 toolbar 展开/收起状态。 |
+
+
+## 6. 典型边界场景
+
+| 场景 | 预期行为 |
+| --- | --- |
+| 无空间控件、无默认值 | 不请求园区数据；普通表单按业务自己的查询时机提交。 |
+| 仅园区控件、`defaultPark=true` | 加载园区列表，自动选首项，初始化完成后查询一次，query 带 `park`。 |
+| 仅园区控件、`defaultPark=false` | 加载园区列表但不选首项，初始化完成后查询一次，query 不带有效 `park`。 |
+| 园区和楼栋控件、默认值开启 | 首园区确定、楼栋数据加载完成后才首次查询；不会先发空 `park` 请求。 |
+| 园区和楼栋控件、默认值关闭 | 不补园区；仍完成初始化并首次查询一次，后续用户选择园区/楼栋再查询。 |
+| 切换园区 | 清空旧楼栋和普通筛选，加载新空间后查询一次，query 使用新 `park`。 |
+| 选择楼栋 | query 同时带稳定的 `park` 和最新 `building`；重复回写不重复请求。 |
+| 未配置园区/楼栋但业务接口可用 | 不产生空间字段；后端按通用接口逻辑处理，不强行关联园区。 |
+
+## 7. 其他说明
+
+- 未配置 `layout-mode` 的旧页面行为不变。
+- `park/building` 只在对应控件显示且有配置时出现.
+- Network 中业务接口的 `park/building` 在 query中包含这两个字段。
+

package/packages/components/search-form/skills/das-search-form-toolbar-migration/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: das-search-form-toolbar-migration
+description: 将业务页面的 DasSearchForm 迁移到 toolbar 布局，并接入可选的园区/楼栋通用筛选，保证空间初始化、confirm 时序、query 参数和业务查询行为正确。适用于按页面逐项升级，不用于无关组件重构。
+---
+
+# DasSearchForm Toolbar 迁移 Skill
+
+## 先理解公共契约
+
+本 Skill 的核心不是把 `legacy` 改成 `toolbar`，而是把空间筛选从业务请求参数中抽离：
+
+- 业务 JSON payload 不定义 `park`、`building`；需要空间过滤时才配置空间控件。
+- Toolbar 内部状态为 `parkIds`、`buildingIds`；`confirm` 对外映射为 `park`、`building`。
+- `createService` 在发送前把这两个字段放进 query，并从 JSON body 删除；后端统一从 query 读取。
+- `spaceChange` 只通知空间状态变化；业务列表请求只从 `@confirm` 触发。
+- 空间初始化、园区切换和楼栋变化都必须保证 query 使用稳定的最新空间值，不能通过业务页面 watcher 另行补请求。
+
+源码和测试优先于本文档：
+
+- 组件入口：`packages/das-ui/packages/components/search-form/src/Index.vue`
+- toolbar 实现：`.../src/Toolbar.vue`
+- 空间类型：`.../src/toolbar-types.ts`
+- 空间值映射：`.../src/hooks/toolbar-state.ts`
+- 默认空间 API：`.../src/api/park-space.ts`
+- 主指南：`../DasSearchForm升级指南.md`
+
+## 迁移步骤
+
+1. 读取目标页面和真实 API，盘点普通字段、异步字段回调、分页、日期/重复规则、弹窗提交和所有列表请求路径。
+2. 确认页面是否需要空间筛选。无空间筛选时不要配置 `spaceConfig.visible`，也不要为通用接口强行补 `park/building`。
+3. 若需要空间筛选，逐项确认 `visible`、`showPark`、`showBuilding`、`defaultPark`、`parkMultiple`、`buildingMultiple` 和是否自定义 `load`。
+4. 显式设置 `layout-mode="toolbar"`，优先保留原 `options`、字段 key/value、业务 handler 和页面辅助状态。
+5. 在 `@confirm` 中读取快照；不要在 `spaceChange`、字段 `change` 回调或 `@reset` 中重复请求列表。
+6. 使用 `createService` 发送请求，不在业务 API 中手动拼 `park/building` query，也不保留旧 `parkIds/buildingIds` 兼容字段。
+7. 验证首次进入、默认值开关、园区切换、楼栋选择、重置、分页和快速重复操作的请求次数与参数。
+
+## 空间配置决策
+
+| 配置 | 默认 | 关键含义 |
+| --- | --- | --- |
+| `visible` | `false` | 总开关；关闭时不加载默认园区数据。 |
+| `showPark` | 跟随 `visible` | 显示园区并决定是否输出 `park`。 |
+| `showBuilding` | 跟随 `visible` | 显示空间树并决定是否输出 `building`。 |
+| `defaultPark` | `true` | 是否自动选中首园区；关闭不等于跳过首次查询。 |
+| `parkMultiple` | `true` | 园区多选模式。 |
+| `buildingMultiple` | `false` | 楼栋/空间多选模式。 |
+| `size` | `small` | 空间控件尺寸。 |
+| `load` | 默认数据源 | 返回 `{ parks, buildings }` 的自定义数据适配器。 |
+
+重要边界：
+
+- 仅园区控件且 `defaultPark=true`：首项加载后查询一次并带 `park`。
+- 仅园区控件且 `defaultPark=false`：仍加载园区并完成首次查询，但首次不带有效 `park`。
+- 园区+楼栋控件：首次查询必须等待园区和楼栋数据初始化完成。
+- `showPark=false, showBuilding=true`：默认数据源没有园区上下文；需要自定义 `load` 提供完整树。
+- 无空间控件：不初始化空间数据，不改变普通业务首次请求。
+
+## 事件与方法
+
+- `@confirm="searchData"`：唯一推荐的业务查询入口，参数为 `(formValues, selectedSpace)`。
+- `@reset="resetAuxiliary"`：清理业务页面在组件外维护的辅助状态；组件随后自动确认一次。
+- `@space-change="handleSpaceChange"`：接收 `{ parkIds, buildingIds }` 状态快照，只做同步或 UI 联动，不发列表请求。
+- `@space-error="handleSpaceError"`：空间数据加载失败诊断入口；失败时组件不会拿空空间条件抢先查询。
+- `v-model:space-value`：需要受控空间状态时使用，值结构为 `{ parkIds, buildingIds }`。
+- `confirm()`：等待字段异步回调和空间门禁后提交查询。
+- `resetSearch()`：恢复普通字段、触发 reset 并确认，默认保留空间值。
+- `closeSearch(target)`：清理普通字段，不清理空间值。
+- `treeSelectResetLazyLoad(key)`：重置普通树字段的懒加载。
+- `getCollapseStatus()`：读取 toolbar 折叠状态。
+
+## 推荐接入
+
+```vue
+<das-search-form
+  ref="searchFormRef"
+  layout-mode="toolbar"
+  :options="options"
+  :space-config="{
+    visible: true,
+    showPark: true,
+    showBuilding: true,
+    defaultPark: true,
+    parkMultiple: true,
+    buildingMultiple: false,
+  }"
+  @confirm="searchData"
+  @reset="resetAuxiliary"
+  @space-change="handleSpaceChange"
+/>
+```
+
+```ts
+function searchData(values: Record<string, any>) {
+  const data = { ...mapBusinessFields(values) }
+  if (Object.prototype.hasOwnProperty.call(values, 'park')) data.park = values.park
+  if (Object.prototype.hasOwnProperty.call(values, 'building')) data.building = values.building
+
+  requestList({ params: { project: projectId }, data })
+}
+```
+
+`park` 单选是标量、多选是数组；`building` 是 ID 数组。不要在这里把字段改回 `parkIds/buildingIds`，也不要手动同时放入 query 和 body。
+
+## 验收清单
+
+- 首次空间初始化只提交一次业务查询，且不会先发空 `park` 的请求。
+- 园区切换后旧楼栋被清空；新空间数据完成后 query 使用新 `park`。
+- 楼栋选择后 query 同时包含最新 `park` 和 `building`，相同值重复回写不重复请求。
+- `park/building` 在 query，JSON body 不包含它们；未配置空间控件的业务不出现这些字段。
+- reset、字段变化、分页和业务回调不会各自重复请求。
+- `options=null/[]` 时普通过滤区域和按钮隐藏，但空间控件仍可独立工作。
+- 运行定向测试、受影响包类型检查和真实页面 Chrome 验证；未验证项必须在结论中说明。
+

package/packages/components/search-form/skills/das-search-form-toolbar-migration//350/277/201/347/247/273/350/246/201/347/202/271/344/270/216/345/270/270/350/247/201/351/227/256/351/242/230.md

@@ -0,0 +1,47 @@
+# DasSearchForm Toolbar 迁移要点与常见问题
+
+## 参数边界
+
+`park`、`building` 是跨业务的通用 query 条件，不是业务 payload 字段。只有页面配置并展示对应空间控件时，`confirm` 才会输出对应字段；未配置时组件不请求园区数据，也不生成空字段。
+
+业务使用 `createService` 发送请求即可：公共请求层会把数组参数按逗号放入 query，并从 JSON body 删除 `park/building`。后端无论 POST 还是 GET 都从 query 读取。不要在业务层自行拼接认证头、URL 或重复拆装空间参数。
+
+## 最容易误解的行为
+
+### `defaultPark=false` 是否意味着没有首次请求？
+
+不是。它只关闭“自动选择园区列表第一项”，不关闭空间初始化，也不关闭首次业务查询。组件仍会完成初始化并提交一次 `confirm`，此时没有有效默认园区，业务请求不应带有效 `park`。
+
+### 为什么不能在 `spaceChange` 中请求列表？
+
+`spaceChange` 发生在内部空间状态发布时，适合做受控同步和 UI 联动；园区切换还需要等待楼栋数据加载，楼栋选择也可能发生重复回写。若业务在这里请求，会与组件自己的 `confirm` 竞争，产生空条件请求、重复请求或页面闪烁。列表请求统一放在 `@confirm`。
+
+### 楼栋选择为什么现在会查询？
+
+楼栋是业务过滤条件。选择值实际变化后，toolbar 会用最新 `park/building` 快照确认一次；同一值重复回写会被组件忽略。展开未加载节点触发的是空间子节点懒加载，不等同于业务列表查询。
+
+### 为什么首次请求不应该先发一次空 `park`？
+
+园区是全局通用条件，业务接口可能依赖它。toolbar 对空间初始化增加了门禁：园区列表、默认值和必要的楼栋数据完成后才允许首次 `confirm`，避免先展示错误结果再被第二次响应覆盖。
+
+## 快速排查
+
+1. 看 `spaceConfig.visible/showPark/showBuilding` 是否与页面实际显示一致。
+2. 看 `defaultPark` 是否被显式关闭，以及业务是否接受首次无 `park` 查询。
+3. 看业务是否在 `spaceChange`、字段 change 回调、watcher 和 `@confirm` 中重复请求。
+4. 看 Network：`park/building` 应在 query，request payload 不应包含它们。
+5. 看是否误用了旧 `parkIds/buildingIds`。它们只属于组件内部 `spaceValue`，不是对外业务参数。
+6. `showPark=false` 但楼栋为空时，检查自定义 `load` 是否提供了完整楼栋树和园区归属。
+
+## 预期请求次数
+
+| 操作 | 预期业务列表请求 |
+| --- | ---: |
+| 无空间控件首次进入 | 按业务原有逻辑 |
+| 空间控件首次初始化 | 1 |
+| 园区切换 | 1，等待新空间数据完成后发送 |
+| 楼栋实际变化 | 1 |
+| 楼栋重复回写同一值 | 0 |
+| toolbar 重置 | 1 |
+| 仅展开未加载楼栋节点 | 0，只有空间子节点请求 |
+

package/packages/components/search-form/src/Index.vue.d.ts

@@ -1,56 +1,18 @@
-import type { SearchFormProp } from './hooks/searchFormItem';
-interface DasSearchFormProp {
-    title?: string;
-    options?: SearchFormProp[];
-    labelLength?: string | number;
-    showFilterPanel?: boolean;
-    layout?: 'horizontal' | 'vertical';
-    /**当无过滤面板时，部分设计右侧有间距 */
-    isMarginRight?: boolean;
-    labelPosition?: 'left' | 'top' | 'right';
-    hasBtn?: boolean;
-    isExpandAtFocus?: boolean;
-    isExpandFilter?: boolean;
-}
-declare var __VLS_1: {}, __VLS_18: any, __VLS_19: {}, __VLS_31: any, __VLS_32: {}, __VLS_50: {}, __VLS_92: any, __VLS_93: {}, __VLS_105: any, __VLS_106: {}, __VLS_119: any, __VLS_120: {};
+type __VLS_Props = {
+    layoutMode?: 'legacy' | 'toolbar';
+};
+declare var __VLS_8: string | number, __VLS_9: {};
 type __VLS_Slots = {} & {
-    [K in NonNullable<typeof __VLS_18>]?: (props: typeof __VLS_19) => any;
-} & {
-    [K in NonNullable<typeof __VLS_31>]?: (props: typeof __VLS_32) => any;
-} & {
-    [K in NonNullable<typeof __VLS_92>]?: (props: typeof __VLS_93) => any;
-} & {
-    [K in NonNullable<typeof __VLS_105>]?: (props: typeof __VLS_106) => any;
-} & {
-    [K in NonNullable<typeof __VLS_119>]?: (props: typeof __VLS_120) => any;
-} & {
-    left?: (props: typeof __VLS_1) => any;
-} & {
-    right?: (props: typeof __VLS_50) => any;
+    [K in NonNullable<typeof __VLS_8>]?: (props: typeof __VLS_9) => any;
 };
-declare const __VLS_component: import("vue").DefineComponent<DasSearchFormProp, {
-    /**treeSelect 调用懒加载树刷新 */
-    treeSelectResetLazyLoad: (key: string) => void;
-    closeSearch: (data: SearchFormProp | any[]) => Promise<void>;
-    resetSearch: (isTriggerEvent?: boolean) => Promise<void>;
+declare const __VLS_component: import("vue").DefineComponent<__VLS_Props, {
+    closeSearch: (...args: any[]) => any;
+    resetSearch: (...args: any[]) => any;
+    confirm: (...args: any[]) => any;
+    treeSelectResetLazyLoad: (...args: any[]) => any;
     getCollapseStatus: () => any;
-}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {} & {
-    confirm: (e: any) => any;
-    clearSearch: (e: any) => any;
-}, string, import("vue").PublicProps, Readonly<DasSearchFormProp> & Readonly<{
-    onConfirm?: ((e: any) => any) | undefined;
-    onClearSearch?: ((e: any) => any) | undefined;
-}>, {
-    options: SearchFormProp[];
-    title: string;
-    layout: "horizontal" | "vertical";
-    labelLength: string | number;
-    labelPosition: "left" | "top" | "right";
-    isExpandAtFocus: boolean;
-    showFilterPanel: boolean;
-    isMarginRight: boolean;
-    hasBtn: boolean;
-    isExpandFilter: boolean;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    layoutMode: "legacy" | "toolbar";
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const _default: __VLS_WithSlots<typeof __VLS_component, __VLS_Slots>;
 export default _default;

package/packages/components/search-form/src/Legacy.vue.d.ts

@@ -0,0 +1,61 @@
+import type { SearchFormProp } from './hooks/searchFormItem';
+interface DasSearchFormProp {
+    title?: string;
+    options?: SearchFormProp[];
+    labelLength?: string | number;
+    showFilterPanel?: boolean;
+    layout?: 'horizontal' | 'vertical';
+    /**当无过滤面板时，部分设计右侧有间距 */
+    isMarginRight?: boolean;
+    labelPosition?: 'left' | 'top' | 'right';
+    hasBtn?: boolean;
+    isExpandAtFocus?: boolean;
+    isExpandFilter?: boolean;
+}
+declare var __VLS_1: {}, __VLS_18: any, __VLS_19: {}, __VLS_31: any, __VLS_32: {}, __VLS_50: {}, __VLS_92: any, __VLS_93: {}, __VLS_105: any, __VLS_106: {}, __VLS_119: any, __VLS_120: {};
+type __VLS_Slots = {} & {
+    [K in NonNullable<typeof __VLS_18>]?: (props: typeof __VLS_19) => any;
+} & {
+    [K in NonNullable<typeof __VLS_31>]?: (props: typeof __VLS_32) => any;
+} & {
+    [K in NonNullable<typeof __VLS_92>]?: (props: typeof __VLS_93) => any;
+} & {
+    [K in NonNullable<typeof __VLS_105>]?: (props: typeof __VLS_106) => any;
+} & {
+    [K in NonNullable<typeof __VLS_119>]?: (props: typeof __VLS_120) => any;
+} & {
+    left?: (props: typeof __VLS_1) => any;
+} & {
+    right?: (props: typeof __VLS_50) => any;
+};
+declare const __VLS_component: import("vue").DefineComponent<DasSearchFormProp, {
+    /**treeSelect 调用懒加载树刷新 */
+    treeSelectResetLazyLoad: (key: string) => void;
+    closeSearch: (data: SearchFormProp | any[]) => Promise<void>;
+    resetSearch: (isTriggerEvent?: boolean) => Promise<void>;
+    getCollapseStatus: () => any;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {} & {
+    confirm: (e: any) => any;
+    clearSearch: (e: any) => any;
+}, string, import("vue").PublicProps, Readonly<DasSearchFormProp> & Readonly<{
+    onConfirm?: ((e: any) => any) | undefined;
+    onClearSearch?: ((e: any) => any) | undefined;
+}>, {
+    options: SearchFormProp[];
+    title: string;
+    layout: "horizontal" | "vertical";
+    labelLength: string | number;
+    labelPosition: "left" | "top" | "right";
+    isExpandAtFocus: boolean;
+    showFilterPanel: boolean;
+    isMarginRight: boolean;
+    hasBtn: boolean;
+    isExpandFilter: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: __VLS_WithSlots<typeof __VLS_component, __VLS_Slots>;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/packages/components/search-form/src/SearchDateRange.vue.d.ts

@@ -1,12 +1,15 @@
 import type { Props } from './hooks/searchFormItem';
-declare const _default: import("vue").DefineComponent<Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {} & {
+type __VLS_Props = Props & {
+    size?: 'large' | 'default' | 'middle' | 'small' | 'table';
+};
+declare const _default: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {} & {
     "update:modelValue": (value: any) => any;
     "update:optionValue": (value: string | number) => any;
     selectChange: (value: string | number) => any;
     dateRangeChange: (value: any) => any;
     openDialogHandle: () => any;
     openDialogChange: (value: any) => any;
-}, string, import("vue").PublicProps, Readonly<Props> & Readonly<{
+}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
     "onUpdate:modelValue"?: ((value: any) => any) | undefined;
     "onUpdate:optionValue"?: ((value: string | number) => any) | undefined;
     onSelectChange?: ((value: string | number) => any) | undefined;

package/packages/components/search-form/src/Toolbar.vue.d.ts

@@ -0,0 +1,57 @@
+import type { SearchFormProp } from './hooks/searchFormItem';
+import type { SpaceConfig, SpaceValue } from './toolbar-types';
+type __VLS_Props = {
+    title?: string;
+    options?: SearchFormProp[] | null;
+    spaceConfig?: SpaceConfig;
+    spaceValue?: SpaceValue;
+    searchOrder?: 'last' | 'original';
+};
+declare function confirm(): Promise<void>;
+declare function resetSearch(): Promise<void>;
+declare function closeSearch(target: SearchFormProp | SearchFormProp[]): void;
+declare var __VLS_1: {}, __VLS_3: {}, __VLS_31: {}, __VLS_33: {}, __VLS_99: string | undefined, __VLS_100: {};
+type __VLS_Slots = {} & {
+    [K in NonNullable<typeof __VLS_99>]?: (props: typeof __VLS_100) => any;
+} & {
+    left?: (props: typeof __VLS_1) => any;
+} & {
+    space?: (props: typeof __VLS_3) => any;
+} & {
+    space?: (props: typeof __VLS_31) => any;
+} & {
+    right?: (props: typeof __VLS_33) => any;
+};
+declare const __VLS_component: import("vue").DefineComponent<__VLS_Props, {
+    confirm: typeof confirm;
+    resetSearch: typeof resetSearch;
+    closeSearch: typeof closeSearch;
+    getCollapseStatus: () => boolean;
+    treeSelectResetLazyLoad: (key: string) => void;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    reset: (...args: any[]) => void;
+    confirm: (...args: any[]) => void;
+    clearSearch: (...args: any[]) => void;
+    "update:spaceValue": (...args: any[]) => void;
+    spaceChange: (...args: any[]) => void;
+    spaceError: (...args: any[]) => void;
+}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onReset?: ((...args: any[]) => any) | undefined;
+    onConfirm?: ((...args: any[]) => any) | undefined;
+    onClearSearch?: ((...args: any[]) => any) | undefined;
+    "onUpdate:spaceValue"?: ((...args: any[]) => any) | undefined;
+    onSpaceChange?: ((...args: any[]) => any) | undefined;
+    onSpaceError?: ((...args: any[]) => any) | undefined;
+}>, {
+    options: SearchFormProp[] | null;
+    title: string;
+    spaceConfig: SpaceConfig;
+    searchOrder: "last" | "original";
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: __VLS_WithSlots<typeof __VLS_component, __VLS_Slots>;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/packages/components/search-form/src/api/park-space.d.ts

@@ -0,0 +1,8 @@
+import type { SpaceId, SpaceNode } from '../toolbar-types';
+export declare function loadParkOptions(signal: AbortSignal): Promise<SpaceNode[]>;
+export declare function loadParkDetail(parkId: SpaceId, signal: AbortSignal): Promise<any>;
+export declare function extractRegions(detail: any): {
+    id: string;
+    name?: string;
+}[];
+export declare function loadSpaceChildren(spaceId: SpaceId | '', signal: AbortSignal): Promise<any[]>;

package/packages/components/search-form/src/hooks/common-query.d.ts

@@ -0,0 +1,7 @@
+import type { Ref } from 'vue';
+export declare function useCommonSpaceQuery(root: Ref<HTMLElement | undefined>, enabled: () => boolean, read: () => Record<string, any> | undefined, onActive: () => void): {
+    isActive: () => boolean;
+    notify(): void;
+    fail(error: unknown): void;
+    dispose(): void;
+};

package/packages/components/search-form/src/hooks/searchFormItem.d.ts

@@ -2,34 +2,36 @@ type DateType = 'date' | 'dateTime' | 'week' | 'month' | 'quarter' | 'year' | 't
 type DateRangeType = 'dateRange' | 'dateTimeRange' | 'weekRange' | 'monthRange' | 'yearRange' | 'timeRange';
 type FormType = 'input' | 'textarea' | 'password' | 'select' | 'treeSelect' | 'radio' | 'checkbox' | 'switch' | 'custom' | DateType | DateRangeType | 'cascader' | 'colorPicker' | 'selectInput' | 'inputDialogSelect' | 'inputNumber';
 export interface SearchFormProp {
-    /**过滤条件key值 */
+    /** 查询结果对象中的字段名；未配置时该项不进入查询值。 */
     key?: string;
-    /** v-model绑定值 */
+    /** 当前控件值，支持普通值或 Vue ref。 */
     value?: any;
-    /** 若type为treeSelect，且需要有默认值，checkedNodes必传，为选中node数组类型 */
+    /** treeSelect 当前选中节点；设置树默认值时同步提供，保证标签和节点状态一致。 */
     checkedNodes?: any[];
-    /** 过滤条件标签文本 */
+    /** 筛选字段显示名称。 */
     label?: any;
-    /** 过滤条件的类型 过滤条件内的普通搜索框使用searchInput类型；带select的搜索框使用selectSearch ；带select搜索框的日期范围使用selectDateRange*；inputSelect选择弹窗*/
+    /** 控件类型；toolbar 模式会把 searchInput/selectSearch 默认排到字段末尾。 */
     type?: FormType | 'searchInput' | 'selectSearch' | 'selectDateRange' | 'inputSelect';
-    /**过滤条件放顶部部还是过滤区内部 */
+    /** legacy 模式中控制字段位于顶部还是过滤面板内部；toolbar 模式不使用此布局字段。 */
     layout?: 'out' | 'inner';
-    /** 在顶部已选择筛选区-是否可删除 */
+    /** legacy 已选条件标签是否允许删除。 */
     closable?: boolean;
-    /** 是否启用自定义录入模式 */
+    /** 是否启用自定义录入与普通选项切换。 */
     custom?: boolean;
-    /**自定义录入模式下：是否处于自定义筛选 */
+    /** 自定义录入模式当前是否处于自定义输入状态。 */
     customerActive?: boolean;
-    /**自定义录入模式下：自定义项前面单选组的配置 */
+    /** 自定义录入模式的选项配置。 */
     customOption?: any;
-    /**当type为selectDateRange，日期type使用dateType字段 */
+    /** type 为 selectDateRange 时，指定实际日期范围类型。 */
     dateType?: string;
-    /**当type为selectDateRange，mode模式分为default,optional;默认default;其余组件mode赋值根据对应组件 */
+    /** 日期范围或底层控件的模式；具体取值由对应控件决定。 */
     mode?: string;
-    /**当前配置项change事件是否需要自动触发confirm查询事件:默认为true --isChangeTrigger为false的使用情景：change需要调用的事件和confirm事件不一样*/
+    /** legacy 模式字段变化后是否自动查询；toolbar 模式始终由查询按钮或实例方法提交。 */
     isChangeTrigger?: boolean;
-    /** 右边距 */
+    /** legacy 字段布局的右侧间距。 */
     marginRight?: string;
+    /** 单字段控件尺寸；toolbar 下未配置时，searchInput/selectDateRange/treeSelect 使用 middle。 */
+    size?: 'small' | 'middle' | 'large' | 'default' | 'table';
     [idx: string]: any;
 }
 export interface Props {

package/packages/components/search-form/src/hooks/submission.d.ts

@@ -0,0 +1,23 @@
+import type { SearchFormProp } from './searchFormItem';
+export declare function createSearchSubmission(getOptions: () => SearchFormProp[]): {
+    read: () => {
+        value?: any;
+        optionValue?: any;
+        key?: string;
+        checkedNodes?: any[];
+        label?: any;
+        type?: ("input" | "select" | "textarea" | "custom" | "switch" | "password" | "treeSelect" | "radio" | "checkbox" | "cascader" | "colorPicker" | "selectInput" | "inputDialogSelect" | "inputNumber" | ("date" | "year" | "month" | "week" | "time" | "dateTime" | "quarter") | ("dateRange" | "dateTimeRange" | "weekRange" | "monthRange" | "yearRange" | "timeRange")) | "searchInput" | "selectSearch" | "selectDateRange" | "inputSelect";
+        layout?: "out" | "inner";
+        closable?: boolean;
+        custom?: boolean;
+        customerActive?: boolean;
+        customOption?: any;
+        dateType?: string;
+        mode?: string;
+        isChangeTrigger?: boolean;
+        marginRight?: string;
+        size?: "small" | "middle" | "large" | "default" | "table";
+    }[];
+    commit: () => void;
+    commitIfSubmitted: (payload?: unknown) => void;
+};

package/packages/components/search-form/src/hooks/toolbar-state.d.ts

@@ -0,0 +1,22 @@
+import type { SearchFormProp } from './searchFormItem';
+import type { SpaceConfig, SpaceId, SpaceNode, SpaceValue } from '../toolbar-types';
+export declare function copyValue(value: any): any;
+export declare function setField(item: any, key: string, value: any): void;
+export declare function formValues(options: SearchFormProp[]): {
+    [k: string]: any;
+};
+export declare function includeVisibleSpaceValues(values: Record<string, any>, space: SpaceValue, config: SpaceConfig): Record<string, any>;
+export declare function shouldLoadParkOptions(config: SpaceConfig): boolean;
+export declare function shouldInitializeSpace(config: SpaceConfig): boolean;
+export declare function normalizeSpace(value?: Partial<SpaceValue>): SpaceValue;
+export declare function selectDefaultPark(space: SpaceValue, parks: SpaceNode[], config: SpaceConfig): SpaceValue;
+export declare function mapSpaceNodes(nodes: any[], parkId?: SpaceId): SpaceNode[];
+export declare function buildParkTrees(parks: {
+    park: SpaceNode;
+    regions: {
+        id: string;
+        name?: string;
+    }[];
+}[], nodes: any[]): SpaceNode[];
+export declare function buildingTree(nodes: SpaceNode[], parks: SpaceId[], inheritedPark?: SpaceId): SpaceNode[];
+export declare function selectableBuildingIds(nodes: SpaceNode[]): SpaceId[];