refactor(Cascader): doc improve

components/cascader/cascader.tsx

@@ -118,84 +118,29 @@ class Cascader extends Component<CascaderProps, CascaderState> {
         rtl: PropTypes.bool,
         pure: PropTypes.bool,
         className: PropTypes.string,
-        /**
-         * 数据源，结构可参考下方说明
-         */
         dataSource: PropTypes.arrayOf(PropTypes.object),
-        /**
-         * （非受控）默认值
-         */
         defaultValue: PropTypes.oneOfType([PropTypes.string, PropTypes.arrayOf(PropTypes.string)]),
-        /**
-         * （受控）当前值
-         */
         value: PropTypes.oneOfType([PropTypes.string, PropTypes.arrayOf(PropTypes.string)]),
-        /**
-         * 选中值改变时触发的回调函数
-         */
         onChange: PropTypes.func,
         onSelect: PropTypes.func,
-        /**
-         * （非受控）默认展开值，如果不设置，组件内部会根据 defaultValue/value 进行自动设置
-         */
         defaultExpandedValue: PropTypes.arrayOf(PropTypes.string),
-        /**
-         * （受控）当前展开值
-         */
         expandedValue: PropTypes.arrayOf(PropTypes.string),
-        /**
-         * 展开触发的方式
-         */
         expandTriggerType: PropTypes.oneOf(['click', 'hover']),
-        /**
-         * 展开时触发的回调函数
-         */
         onExpand: PropTypes.func,
-        /**
-         * 是否开启虚拟滚动
-         */
         useVirtual: PropTypes.bool,
-        /**
-         * 是否多选
-         */
         multiple: PropTypes.bool,
-        /**
-         * 单选时是否只能选中叶子节点
-         */
         canOnlySelectLeaf: PropTypes.bool,
-        /**
-         * 多选时是否只能选中叶子节点
-         */
         canOnlyCheckLeaf: PropTypes.bool,
-        /**
-         * 父子节点是否选中不关联
-         */
         checkStrictly: PropTypes.bool,
-        /**
-         * 每列列表样式对象
-         */
         listStyle: PropTypes.object,
-        /**
-         * 每列列表类名
-         */
         listClassName: PropTypes.string,
-        /**
-         * 每列列表项渲染函数
-         */
         itemRender: PropTypes.func,
-        /**
-         * 异步加载数据函数
-         */
         loadData: PropTypes.func,
         searchValue: PropTypes.string,
         onBlur: PropTypes.func,
         filteredPaths: PropTypes.array,
         filteredListStyle: PropTypes.object,
         resultRender: PropTypes.func,
-        /**
-         * 是否是不可变数据
-         * @version 1.23
-         */
         immutable: PropTypes.bool,
     };
 

components/cascader/types.ts

@@ -4,6 +4,9 @@ import type { CheckboxItemProps, MenuProps, ItemProps as MenuItemProps } from '.
 
 interface HTMLAttributesWeak extends React.HTMLAttributes<HTMLElement> {}
 
+/**
+ * @api CascaderDataItem
+ */
 export type CascaderDataItem = {
     value: string;
     label?: string;
@@ -18,6 +21,9 @@ export type CascaderDataItem = {
  * @api CascaderDataItemWithPosInfo
  */
 export type CascaderDataItemWithPosInfo = CascaderDataItem & {
+    /**
+     * 位置信息
+     */
     pos: string;
     _source: CascaderDataItem;
 };
@@ -31,6 +37,9 @@ export type NormalizeValueReturns<T> = T extends undefined | null
       ? T
       : [T];
 
+/**
+ * @api extra
+ */
 type extra = {
     /**
      * 单选时选中的数据的路径
@@ -95,25 +104,30 @@ export interface CascaderProps
     extends Omit<HTMLAttributesWeak, 'onChange' | 'onSelect' | 'defaultValue'>,
         CommonProps {
     /**
-     * 数据源，结构可参考下方说明
+     * 数据源
+     * @en data source
+     * @defaultValue []
      */
     dataSource: Array<CascaderDataItem>;
 
     /**
      * （非受控）默认值
+     * @en default value
      */
     defaultValue?: string | Array<string>;
 
     /**
      * （受控）当前值
+     * @en current value
      */
     value?: string | Array<string>;
 
     /**
      * 选中值改变时触发的回调函数
-     * @param value - 选中的值，单选时返回单个值，多选时返回数组
-     * @param data - 选中的数据，包括 value 和 label，单选时返回单个值，多选时返回数组，父子节点选中关联时，同时选中，只返回父节点
-     * @param extra - 额外参数
+     * @en callback when value changed
+     * @param value - 选中的值，单选时返回单个值，多选时返回数组 - selected value, single value when single select, array when multiple select
+     * @param data - 选中的数据，包括 value 和 label，单选时返回单个值，多选时返回数组，父子节点选中关联时，同时选中，只返回父节点 - selected data, including value and label, single value when single select, array when multiple select
+     * @param extra - 额外参数 - extra parameters
      */
     onChange?: (
         value: string | Array<string>,
@@ -123,22 +137,31 @@ export interface CascaderProps
 
     /**
      * 选中时触发的回调函数
-     * @remarks 无论选中与否
+     * @en callback when selected
+     * @remarks 无论值是否发生变化 - no matter value changed
+     * @param v - 选中的值 - selected value
+     * @param data - 选中的数据，包括 value 和 label - selected data, including value and label
+     * @param extra - 额外参数 - extra parameters
      */
     onSelect?: (v: string, data: CascaderDataItemWithPosInfo, extra: extra) => void;
 
     /**
-     * （非受控）默认展开值，如果不设置，组件内部会根据 defaultValue/value 进行自动设置
+     * （非受控）默认展开值
+     * @en default expanded value
+     * @remarks 如果不设置，组件内部会根据 defaultValue/value 进行自动设置 - if not set, component will set automatically based on defaultValue/value
      */
     defaultExpandedValue?: Array<string>;
 
     /**
      * （受控）当前展开值
+     * @en current expanded value
      */
     expandedValue?: Array<string>;
 
     /**
      * 展开触发的方式
+     * @en expand trigger type
+     * @defaultValue 'click'
      */
     expandTriggerType?: 'click' | 'hover';
 
@@ -150,71 +173,119 @@ export interface CascaderProps
 
     /**
      * 展开时触发的回调函数
-     * @param expandedValue - 各列展开值的数组
+     * @en callback when expanded
+     * @param expandedValue - 各列展开值的数组 - expanded value
      */
     onExpand?: (expandedValue: Array<string>) => void;
 
     /**
      * 是否开启虚拟滚动
+     * @en use virtual scroll
+     * @defaultValue false
      */
     useVirtual?: boolean;
 
     /**
      * 是否多选
+     * @en multiple
+     * @defaultValue false
      */
     multiple?: boolean;
 
     /**
      * 单选时是否只能选中叶子节点
+     * @en can only select leaf when single select
+     * @defaultValue false
      */
     canOnlySelectLeaf?: boolean;
 
     /**
      * 多选时是否只能选中叶子节点
+     * @en can only check leaf when multiple select
+     * @defaultValue false
      */
     canOnlyCheckLeaf?: boolean;
 
     /**
      * 父子节点是否选中不关联
+     * @en check parent and child not associated
+     * @defaultValue false
      */
     checkStrictly?: boolean;
 
     /**
      * 每列列表样式对象
+     * @en list style
      */
     listStyle?: React.CSSProperties;
 
     /**
      * 每列列表类名
+     * @en list class
      */
     listClassName?: string;
 
     /**
      * 每列列表项渲染函数
-     * @param data - 数据
-     * @returns 列表项内容
+     * @en list item render
+     * @param data - 数据 - data
+     * @param props - 列表项属性 - list item props
+     * @returns 列表项内容 - list item content
+     * @defaultValue (item: CascaderDataItem) =\> item.label
      */
     itemRender?: (data: CascaderDataItem, props: ItemProps) => React.ReactNode;
 
     /**
      * 异步加载数据函数，source 是原始对象
-     * @param data - 当前点击异步加载的数据
-     * @param source - 当前点击数据，source 是原始对象
+     * @en async load data function
+     * @param data - 当前点击异步加载的数据 - current click data
+     * @param source - 当前点击数据，source 是原始对象 - current click data, source is original object
      */
     loadData?: (data: CascaderDataItem, source: CascaderDataItem) => Promise<unknown>;
 
     /**
      * 是否是不可变数据
+     * @en immutable
+     * @defaultValue false
+     * @version 1.23.0
      */
     immutable?: boolean;
-
+    /**
+     * 搜索值
+     * @en search value
+     * @skip
+     */
     searchValue?: string;
 
+    /**
+     * 过滤后的路径
+     * @en filtered paths
+     * @skip
+     */
     filteredPaths?: CascaderDataItemWithPosInfo[][];
 
+    /**
+     * 结果渲染函数
+     * @en result render
+     * @param searchValue - 搜索值 - search value
+     * @param path - 路径 - path
+     * @returns 结果内容 - result content
+     * @skip
+     */
     resultRender?: (searchValue: string, path: CascaderDataItemWithPosInfo[]) => React.ReactNode;
 
+    /**
+     * 过滤后的列表样式对象
+     * @en filter list style
+     * @skip
+     */
     filteredListStyle?: React.CSSProperties;
 
+    /**
+     * 是否可聚焦
+     * @en focusable
+     * @defaultValue false
+     * @skip
+     */
     focusable?: boolean;
 }