Tencent · anlyyao · Jun 3, 2026 · Jun 3, 2026
@@ -10,9 +10,9 @@ style | Object | - | CSS(Cascading Style Sheets) | N
 custom-style | Object | - | CSS(Cascading Style Sheets)，used to set style on virtual component | N
 check-strictly | Boolean | false | \- | N
 close-btn | Boolean | true | \- | N
-filterable | Boolean | false | Enable searching. When on, a search box is shown at the top; typing switches the panel to a flat list of matched paths | N
-filter | Function | - | Custom filter function. Typescript: `(keyword: string, option: CascaderOption, path: CascaderOption[]) => boolean`. Falls back to a case-insensitive built-in matcher on label/text | N
-filter-placeholder | String | - | Placeholder text of the search box, falls back to global locale | N
+filter | Function | - | Typescript: `CascaderFilterFunction ` `type CascaderFilterFunction<CascaderOption extends TreeOptionData = TreeOptionData> = (keyword: string, option: CascaderOption, path: CascaderOption[]) => boolean`。[see more ts definition](https://github.com/Tencent/tdesign-miniprogram/blob/develop/packages/components/common/common.ts)。[see more ts definition](https://github.com/Tencent/tdesign-miniprogram/blob/develop/packages/components/cascader/type.ts) | N
+filter-placeholder | String | - | \- | N
+filterable | Boolean | false | \- | N
 keys | Object | - | Typescript: `CascaderKeysType` `type CascaderKeysType = TreeKeysType`。[see more ts definition](https://github.com/Tencent/tdesign-miniprogram/blob/develop/packages/components/common/common.ts)。[see more ts definition](https://github.com/Tencent/tdesign-miniprogram/blob/develop/packages/components/cascader/type.ts) | N
 options | Array | [] | Typescript: `Array<CascaderOption>` | N
 placeholder | String | - | \- | N
@@ -28,6 +28,7 @@ visible | Boolean | false | \- | N
 name | params | description
 -- | -- | --
 change | `(value: string \| number, selectedOptions: string[])` | `1.0.1`
+change | `(detail: { value: string \| number, selectedOptions: string[] })` | `1.0.1`
 close | `(trigger: CascaderTriggerSource)` | `1.0.1`。[see more ts definition](https://github.com/Tencent/tdesign-miniprogram/blob/develop/packages/components/cascader/type.ts)。<br/>`type CascaderTriggerSource = 'overlay' \| 'close-btn' \| 'finish'`<br/>
 pick | `(value: string \| number, label: string, index: number, level: number)` | `1.0.1`
 

@@ -71,9 +71,9 @@ style | Object | - | 样式 | N
 custom-style | Object | - | 样式，一般用于开启虚拟化组件节点场景 | N
 check-strictly | Boolean | false | 父子节点选中状态不再关联，可各自选中或取消 | N
 close-btn | Boolean | true | 关闭按钮 | N
-filterable | Boolean | false | 是否可搜索。开启后顶部展示搜索框，输入关键字将层级面板切换为扁平的匹配路径列表 | N
-filter | Function | - | 自定义过滤函数，返回 true 表示匹配。TS 类型：`(keyword: string, option: CascaderOption, path: CascaderOption[]) => boolean`。缺省时使用大小写不敏感的内置匹配规则（命中路径中任一 label 或叶子节点 text） | N
-filter-placeholder | String | - | 搜索框占位文案，缺省回退到全局语言包 | N
+filter | Function | - |  自定义过滤函数。返回 true 表示匹配，未设置时使用内置匹配规则：对路径中所有 label 拼接后做大小写不敏感的 includes 匹配。TS 类型：`CascaderFilterFunction ` `type CascaderFilterFunction<CascaderOption extends TreeOptionData = TreeOptionData> = (keyword: string, option: CascaderOption, path: CascaderOption[]) => boolean`。[通用类型定义](https://github.com/Tencent/tdesign-miniprogram/blob/develop/packages/components/common/common.ts)。[详细类型定义](https://github.com/Tencent/tdesign-miniprogram/blob/develop/packages/components/cascader/type.ts) | N
+filter-placeholder | String | - | 搜索框占位符描述文本 | N
+filterable | Boolean | false | 是否可搜索，开启后顶部会展示一个搜索框  | N
 keys | Object | - | 用来定义 value / label / children / disabled 在 `options` 中对应的字段别名。TS 类型：`CascaderKeysType` `type CascaderKeysType = TreeKeysType`。[通用类型定义](https://github.com/Tencent/tdesign-miniprogram/blob/develop/packages/components/common/common.ts)。[详细类型定义](https://github.com/Tencent/tdesign-miniprogram/blob/develop/packages/components/cascader/type.ts) | N
 options | Array | [] | 可选项数据源。TS 类型：`Array<CascaderOption>` | N
 placeholder | String | - | 未选中时的提示文案。组件内置默认值为：'选择选项' | N
@@ -89,6 +89,7 @@ visible | Boolean | false | 是否展示 | N
 名称 | 参数 | 描述
 -- | -- | --
 change | `(value: string \| number, selectedOptions: string[])` | `1.0.1`。值发生变更时触发
+change | `(detail: { value: string \| number, selectedOptions: string[] })` | `1.0.1`。值发生变更时触发
 close | `(trigger: CascaderTriggerSource)` | `1.0.1`。关闭时触发。[详细类型定义](https://github.com/Tencent/tdesign-miniprogram/blob/develop/packages/components/cascader/type.ts)。<br/>`type CascaderTriggerSource = 'overlay' \| 'close-btn' \| 'finish'`<br/>
 pick | `(value: string \| number, label: string, index: number, level: number)` | `1.0.1`。选择后触发
 

@@ -16,21 +16,20 @@ const props: TdCascaderProps = {
     type: Boolean,
     value: true,
   },
-  /** 是否可搜索。开启后顶部展示搜索框，输入关键字将层级面板切换为扁平的匹配路径列表 */
-  filterable: {
-    type: Boolean,
-    value: false,
-  },
-  /** 自定义过滤函数。返回 true 表示匹配；签名为 `(keyword, option, path) => boolean` */
+  /**  自定义过滤函数。返回 true 表示匹配，未设置时使用内置匹配规则：对路径中所有 label 拼接后做大小写不敏感的 includes 匹配 */
   filter: {
     type: null,
-    value: null,
   },
-  /** 搜索框占位文案 */
+  /** 搜索框占位符描述文本 */
   filterPlaceholder: {
     type: String,
     value: '',
   },
+  /** 是否可搜索，开启后顶部会展示一个搜索框  */
+  filterable: {
+    type: Boolean,
+    value: false,
+  },
   /** 用来定义 value / label / children / disabled 在 `options` 中对应的字段别名 */
   keys: {
     type: Object,

@@ -4,7 +4,7 @@
  * 该文件为脚本自动生成文件，请勿随意修改。如需修改请联系 PMC
  * */
 
-import { TreeOptionData, TreeKeysType } from '../common/common';
+import type { TreeOptionData, TreeKeysType } from '../common/common';
 
 export interface TdCascaderProps<CascaderOption extends TreeOptionData = TreeOptionData> {
   /**
@@ -24,28 +24,28 @@ export interface TdCascaderProps<CascaderOption extends TreeOptionData = TreeOpt
     value?: boolean;
   };
   /**
-   * 是否可搜索。开启后顶部会展示一个搜索框，输入关键字将层级面板切换为扁平的匹配路径列表
-   * @default false
-   */
-  filterable?: {
-    type: BooleanConstructor;
-    value?: boolean;
-  };
-  /**
-   * 自定义过滤函数。返回 true 表示匹配；签名为 `(keyword, option, path) => boolean`。未设置时使用内置匹配规则：对路径中所有 label/text 拼接后做大小写不敏感的 includes 匹配
+   *  自定义过滤函数。返回 true 表示匹配，未设置时使用内置匹配规则：对路径中所有 label 拼接后做大小写不敏感的 includes 匹配
    */
   filter?: {
-    type: null;
+    type: undefined;
     value?: CascaderFilterFunction;
   };
   /**
-   * 搜索框占位文案
+   * 搜索框占位符描述文本
    * @default ''
    */
   filterPlaceholder?: {
     type: StringConstructor;
     value?: string;
   };
+  /**
+   * 是否可搜索，开启后顶部会展示一个搜索框
+   * @default false
+   */
+  filterable?: {
+    type: BooleanConstructor;
+    value?: boolean;
+  };
   /**
    * 用来定义 value / label / children / disabled 在 `options` 中对应的字段别名
    */
@@ -118,10 +118,10 @@ export interface TdCascaderProps<CascaderOption extends TreeOptionData = TreeOpt
   };
 }
 
-export type CascaderKeysType = TreeKeysType;
-
 export type CascaderFilterFunction<CascaderOption extends TreeOptionData = TreeOptionData> = (
   keyword: string,
   option: CascaderOption,
   path: CascaderOption[],
 ) => boolean;
+
+export type CascaderKeysType = TreeKeysType;