feat(cascader): add panelHeader/panelFooter slots with cascade filter support

RSS1102 · RSS1102 · commit 2e85fa62575f · 2026-01-26T17:07:02.000+08:00
diff --git a/packages/components/cascader/_example/base.vue b/packages/components/cascader/_example/base.vue
@@ -1,9 +1,31 @@
 <template>
-  <t-cascader v-model="value" :options="options" clearable @change="onChange" @focus="onFocus" @blur="onBlur" />
+  <t-space direction="vertical" style="width: 100%">
+    <!-- 基础搜索：每个层级独立过滤 -->
+    <t-cascader v-model="value" :options="options">
+      <template #panelHeader="{ panelIndex, onFilter }">
+        <t-input
+          v-model="searchValues1[panelIndex]"
+          :placeholder="`搜索第${panelIndex + 1}级`"
+          @change="(val) => onFilter(val)"
+        />
+      </template>
+    </t-cascader>
+
+    <!-- 级联搜索：搜索某级后，后续级别只显示匹配项的子节点 -->
+    <t-cascader v-model="value2" :options="options">
+      <template #panelHeader="{ panelIndex, onFilter }">
+        <t-input
+          v-model="searchValues2[panelIndex]"
+          :placeholder="`搜索第${panelIndex + 1}级（级联）`"
+          @change="(val) => onFilter(val, { cascade: true })"
+        />
+      </template>
+    </t-cascader>
+  </t-space>
 </template>
 
 <script setup>
-import { ref } from 'vue';
+import { ref, reactive } from 'vue';
 
 const options = [
   {
@@ -13,10 +35,15 @@ const options = [
       {
         label: '子选项一',
         value: '1.1',
+        children: [
+          { label: '三级-1', value: '1.1.1' },
+          { label: '三级-2', value: '1.1.2' },
+        ],
       },
       {
         label: '子选项二',
         value: '1.2',
+        children: [{ label: '三级-3', value: '1.2.1' }],
       },
       {
         label: '子选项三',
@@ -31,26 +58,30 @@ const options = [
       {
         label: '子选项一',
         value: '2.1',
+        children: [{ label: '三级-4', value: '2.1.1' }],
       },
       {
         label: '子选项二',
         value: '2.2',
       },
     ],
   },
+  {
+    label: '选项三',
+    value: '3',
+    children: [
+      {
+        label: '子选项一',
+        value: '3.1',
+      },
+    ],
+  },
 ];
 
-const value = ref('1.1');
-
-const onChange = (val, context) => {
-  console.log(val, context);
-};
-
-const onFocus = (ctx) => {
-  console.log('focus', ctx);
-};
+const value = ref('1.1.1');
+const value2 = ref('1.1.1');
 
-const onBlur = (ctx) => {
-  console.log('blur', ctx);
-};
+// 使用 reactive 维护搜索状态
+const searchValues1 = reactive({});
+const searchValues2 = reactive({});
 </script>
diff --git a/packages/components/cascader/cascader.tsx b/packages/components/cascader/cascader.tsx
@@ -190,7 +190,12 @@ export default defineComponent({
                   loading={props.loading}
                   loadingText={props.loadingText}
                   cascaderContext={cascaderContext.value}
-                  v-slots={{ option: slots.option, empty: slots.empty, loadingText: slots.loadingText }}
+                  v-slots={{
+                    option: slots.option,
+                    empty: slots.empty,
+                    loadingText: slots.loadingText,
+                    panelHeader: slots.panelHeader,
+                  }}
                 />
                 {renderTNodeJSX('panelBottomContent')}
               </>
diff --git a/packages/components/cascader/components/Panel.tsx b/packages/components/cascader/components/Panel.tsx
@@ -1,13 +1,19 @@
-import { defineComponent, PropType, computed, h } from 'vue';
+import { defineComponent, PropType, computed, h, shallowRef } from 'vue';
 
 import Item from './Item';
 import { TreeNode, CascaderContextType } from '../types';
 import CascaderProps from '../props';
-import { useConfig, usePrefixClass, useTNodeDefault } from '@tdesign/shared-hooks';
+import { useConfig, usePrefixClass, useTNodeDefault, useTNodeJSX } from '@tdesign/shared-hooks';
 
 import { getDefaultNode } from '@tdesign/shared-utils';
 import { getPanels, expandClickEffect, valueChangeEffect } from '../utils';
 
+interface FilterState {
+  filters: Record<number, string>;
+  cascade: boolean;
+  maxLevel: number;
+}
+
 export default defineComponent({
   name: 'TCascaderSubPanel',
   props: {
@@ -22,17 +28,76 @@ export default defineComponent({
       type: Object as PropType<CascaderContextType>,
     },
   },
-
   setup(props) {
     const renderTNodeJSXDefault = useTNodeDefault();
+    const renderTNodeJSX = useTNodeJSX();
     const COMPONENT_NAME = usePrefixClass('cascader');
     const { globalConfig } = useConfig('cascader');
 
     const panels = computed(() => getPanels(props.cascaderContext.treeNodes));
 
-    const handleExpand = (node: TreeNode, trigger: 'hover' | 'click') => {
-      const { trigger: propsTrigger, cascaderContext } = props;
-      expandClickEffect(propsTrigger, trigger, node, cascaderContext);
+    // 过滤状态 - 惰性初始化，不使用时为 null，无性能开销
+    const filterState = shallowRef<FilterState | null>(null);
+
+    // 处理过滤
+    const handleFilter = (index: number, keyword: string, options?: { cascade?: boolean }) => {
+      const prev = filterState.value;
+      const cascade = options?.cascade ?? prev?.cascade ?? false;
+      const filters = { ...prev?.filters, [index]: keyword };
+
+      let maxLevel = prev?.maxLevel ?? -1;
+      if (cascade) {
+        // 有新搜索词时重置 maxLevel；全部清空时重置为 -1
+        if (keyword?.trim()) {
+          maxLevel = index;
+        } else if (!Object.values(filters).some((f) => f?.trim())) {
+          maxLevel = -1;
+        }
+      }
+
+      filterState.value = { filters, cascade, maxLevel };
+    };
+
+    // 获取过滤后的节点 - 直接应用搜索词，确保父级变化后子级搜索仍生效
+    const getFilteredNodes = (nodes: TreeNode[], index: number): TreeNode[] => {
+      const state = filterState.value;
+      if (!state) return nodes;
+
+      // 直接应用当前层级的搜索词（无论级联模式还是基础模式）
+      const keyword = state.filters[index]?.trim().toLowerCase();
+      if (!keyword) return nodes;
+
+      return nodes.filter((n) => n.label?.toLowerCase().includes(keyword));
+    };
+
+    // 判断面板是否应该显示
+    const shouldShowPanel = (index: number): boolean => {
+      const state = filterState.value;
+      if (!state?.cascade || state.maxLevel < 0) return true;
+      // 只显示 maxLevel 范围内的面板
+      return index <= state.maxLevel;
+    };
+
+    // 处理节点展开
+    const handleExpand = (node: TreeNode, trigger: 'hover' | 'click', level: number) => {
+      const state = filterState.value;
+
+      // 级联模式下更新 maxLevel 以显示子级面板
+      const { children } = node;
+      if (
+        state?.cascade &&
+        state.maxLevel >= 0 &&
+        props.trigger === trigger &&
+        Array.isArray(children) &&
+        children.length
+      ) {
+        const childLevel = level + 1;
+        if (childLevel > state.maxLevel) {
+          filterState.value = { ...state, maxLevel: childLevel };
+        }
+      }
+
+      expandClickEffect(props.trigger, trigger, node, props.cascaderContext);
     };
 
     const renderItem = (node: TreeNode, index: number) => {
@@ -42,7 +107,7 @@ export default defineComponent({
             params: {
               item: node.data,
               index,
-              onExpand: () => handleExpand(node, 'click'),
+              onExpand: () => handleExpand(node, 'click', index),
               onChange: () => valueChangeEffect(node, props.cascaderContext),
             },
           });
@@ -52,42 +117,53 @@ export default defineComponent({
           node={node}
           optionChild={optionChild}
           cascaderContext={props.cascaderContext}
-          onClick={() => {
-            handleExpand(node, 'click');
-          }}
-          onMouseenter={() => {
-            handleExpand(node, 'hover');
-          }}
-          onChange={() => {
-            valueChangeEffect(node, props.cascaderContext);
-          }}
+          onClick={() => handleExpand(node, 'click', index)}
+          onMouseenter={() => handleExpand(node, 'hover', index)}
+          onChange={() => valueChangeEffect(node, props.cascaderContext)}
         />
       );
     };
 
-    const renderList = (treeNodes: TreeNode[], isFilter = false, segment = true, index = 1) => (
-      <ul
-        class={[
-          `${COMPONENT_NAME.value}__menu`,
-          'narrow-scrollbar',
-          {
-            [`${COMPONENT_NAME.value}__menu--segment`]: segment,
-            [`${COMPONENT_NAME.value}__menu--filter`]: isFilter,
-          },
-        ]}
-        key={`${COMPONENT_NAME}__menu${index}`}
-      >
-        {treeNodes.map((node: TreeNode) => renderItem(node, index))}
-      </ul>
-    );
+    const renderList = (treeNodes: TreeNode[], isFilter = false, segment = true, index = 0) => {
+      const displayNodes = filterState.value ? getFilteredNodes(treeNodes, index) : treeNodes;
+
+      return (
+        <ul
+          class={[
+            `${COMPONENT_NAME.value}__menu`,
+            'narrow-scrollbar',
+            {
+              [`${COMPONENT_NAME.value}__menu--segment`]: segment,
+              [`${COMPONENT_NAME.value}__menu--filter`]: isFilter,
+            },
+          ]}
+          key={`${COMPONENT_NAME}__menu${index}`}
+        >
+          {renderTNodeJSX('panelHeader', {
+            params: {
+              panelIndex: index,
+              options: treeNodes,
+              onFilter: (filter: string, opts?: { cascade?: boolean }) => handleFilter(index, filter, opts),
+            },
+          })}
+          {displayNodes.map((node: TreeNode) => renderItem(node, index))}
+          {renderTNodeJSX('panelFooter', { params: { panelIndex: index } })}
+        </ul>
+      );
+    };
 
     const renderPanels = () => {
       const { inputVal, treeNodes } = props.cascaderContext;
-      return inputVal
-        ? renderList(treeNodes, true)
-        : panels.value.map((treeNodes, index: number) =>
-            renderList(treeNodes, false, index !== panels.value.length - 1, index),
-          );
+      if (inputVal) return renderList(treeNodes, true);
+
+      const result = [];
+      const len = panels.value.length;
+      for (let i = 0; i < len; i++) {
+        if (shouldShowPanel(i)) {
+          result.push(renderList(panels.value[i], false, i !== len - 1, i));
+        }
+      }
+      return result;
     };
 
     return () => {
diff --git a/packages/components/cascader/props.ts b/packages/components/cascader/props.ts
@@ -95,6 +95,14 @@ export default {
   panelTopContent: {
     type: [String, Function] as PropType<TdCascaderProps['panelTopContent']>,
   },
+  /** 面板内的标题 */
+  panelHeader: {
+    type: Function as PropType<TdCascaderProps['panelHeader']>,
+  },
+  /** 面板内的页脚 */
+  panelFooter: {
+    type: Function as PropType<TdCascaderProps['panelFooter']>,
+  },
   /** 占位符 */
   placeholder: {
     type: String,
diff --git a/packages/components/cascader/type.ts b/packages/components/cascader/type.ts
@@ -126,6 +126,26 @@ export interface TdCascaderProps<CascaderOption extends TreeOptionData = TreeOpt
    * 面板内的顶部内容
    */
   panelTopContent?: string | TNode;
+  /**
+   * 面板内的标题
+   */
+  panelHeader?: TNode<{
+    panelIndex: number;
+    options: CascaderOption[];
+    /**
+     * 过滤当前面板选项的回调函数
+     * @param filter - 过滤条件，可以是字符串或自定义过滤函数
+     * @param options - 配置项，cascade 为 true 时启用级联过滤（搜索某级后，后续级别只显示匹配项的子节点）
+     */
+    onFilter: (
+      filter: string | ((node: CascaderOption, panelIndex: number) => boolean),
+      options?: { cascade?: boolean },
+    ) => void;
+  }>;
+  /**
+   * 面板内的页脚
+   */
+  panelFooter?: TNode<{ panelIndex: number }>;
   /**
    * 占位符
    */
