1 | import { Component, ComponentType, CSSProperties, ReactNode } from 'react'
|
2 | import { StandardProps, BaseEventOrigFunction } from '../../types/common'
|
3 | import { ScrollViewProps } from '../../types/ScrollView'
|
4 |
|
5 | interface VirtualListProps extends StandardProps {
|
6 | /** 列表的高度。 */
|
7 | height: string | number
|
8 | /** 列表的宽度。 */
|
9 | width: string | number
|
10 | /** 列表的长度 */
|
11 | itemCount: number
|
12 | /** 渲染数据 */
|
13 | itemData: any[]
|
14 | /** 列表单项的大小,垂直滚动时为高度,水平滚动时为宽度。 */
|
15 | itemSize: number
|
16 | /** 解开高度列表单项大小限制,默认值使用: itemSize (请注意,初始高度与实际高度差异过大会导致隐患)。 */
|
17 | unlimitedSize?: boolean
|
18 | /** 布局方式,默认采用 "absolute" */
|
19 | position?: 'absolute' | 'relative'
|
20 | /** 初始滚动偏移值,水平滚动影响 scrollLeft,垂直滚动影响 scrollTop。 */
|
21 | initialScrollOffset?: number
|
22 | /** 列表内部容器组件类型,默认值为 View。 */
|
23 | innerElementType?: ComponentType
|
24 | /** 顶部区域 */
|
25 | renderTop?: ReactNode
|
26 | /** 底部区域 */
|
27 | renderBottom?: ReactNode
|
28 | /** 滚动方向。vertical 为垂直滚动,horizontal 为平行滚动。默认为 vertical。 */
|
29 | layout?: 'vertical' | 'horizontal'
|
30 | /** 列表滚动时调用函数 */
|
31 | onScroll?: (event: VirtualListEvent<VirtualListProps.onScrollDetail>) => void
|
32 | /** 调用平台原生的滚动监听函数。 */
|
33 | onScrollNative?: BaseEventOrigFunction<ScrollViewProps.onScrollDetail>
|
34 | /** 在可视区域之外渲染的列表单项数量,值设置得越高,快速滚动时出现白屏的概率就越小,相应地,每次滚动的性能会变得越差。 */
|
35 | overscanCount?: number
|
36 | /** 是否注入 isScrolling 属性到 children 组件。这个参数一般用于实现滚动骨架屏(或其它 placeholder) 时比较有用。 */
|
37 | useIsScrolling?: boolean
|
38 | children?: ComponentType<{
|
39 | /** 组件 ID */
|
40 | id: string
|
41 | /** 单项的样式,样式必须传入组件的 style 中 */
|
42 | style?: CSSProperties
|
43 | /** 组件渲染的数据 */
|
44 | data: any
|
45 | /** 组件渲染数据的索引 */
|
46 | index: number
|
47 | /** 组件是否正在滚动,当 useIsScrolling 值为 true 时返回布尔值,否则返回 undefined */
|
48 | isScrolling?: boolean
|
49 | }>
|
50 | }
|
51 |
|
52 | declare namespace VirtualListProps {
|
53 | // eslint-disable-next-line @typescript-eslint/class-name-casing
|
54 | interface onScrollDetail {
|
55 | clientWidth: number
|
56 | clientHeight: number
|
57 | }
|
58 | }
|
59 |
|
60 | interface VirtualListEvent<T> {
|
61 | /** 滚动方向,可能值为 forward 往前, backward 往后。 */
|
62 | scrollDirection: 'forward' | 'backward'
|
63 | /** 滚动距离 */
|
64 | scrollOffset: number
|
65 | /** 当滚动是由 scrollTo() 或 scrollToItem() 调用时返回 true,否则返回 false */
|
66 | scrollUpdateWasRequested: boolean
|
67 | /** 当前只有 React 支持 */
|
68 | detail?: {
|
69 | scrollLeft: number
|
70 | scrollTop: number
|
71 | scrollHeight: number
|
72 | scrollWidth: number
|
73 | clientWidth: number
|
74 | clientHeight: number
|
75 | }
|
76 | }
|
77 |
|
78 | /**
|
79 | * @classification viewContainer
|
80 | * @supported weapp, swan, alipay, tt, qq, jd, h5
|
81 | * @example
|
82 | * ```tsx
|
83 | * import VirtualList from `@tarojs/components/virtual-list`
|
84 | *
|
85 | * function buildData (offset = 0) {
|
86 | * return Array(100).fill(0).map((_, i) => i + offset);
|
87 | * }
|
88 | *
|
89 | * const Row = React.memo(({ id, index, style, data }) => {
|
90 | * return (
|
91 | * <View id={id} className={index % 2 ? 'ListItemOdd' : 'ListItemEven'} style={style}>
|
92 | * Row {index}
|
93 | * </View>
|
94 | * );
|
95 | * })
|
96 | *
|
97 | * export default class Index extends Component {
|
98 | * state = {
|
99 | * data: buildData(0),
|
100 | * }
|
101 | *
|
102 | * render() {
|
103 | * const { data } = this.state
|
104 | * const dataLen = data.length
|
105 | * return (
|
106 | * <VirtualList
|
107 | * height={500} // 列表的高度
|
108 | * width='100%' // 列表的宽度
|
109 | * itemData={data} // 渲染列表的数据
|
110 | * itemCount={dataLen} // 渲染列表的长度
|
111 | * itemSize={100} // 列表单项的高度
|
112 | * >
|
113 | * {Row} // 列表单项组件,这里只能传入一个组件
|
114 | * </VirtualList>
|
115 | * );
|
116 | * }
|
117 | * }
|
118 | * ```
|
119 | * @see https://taro-docs.jd.com/taro/docs/virtual-list/
|
120 | */
|
121 | declare class VirtualList extends Component<VirtualListProps> {}
|
122 |
|
123 | export = VirtualList
|