1/* 2 * Copyright (c) 2025 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16/** 17 * @file 18 * @kit ArkUI 19 * @arkts 1.2 20 */ 21 22import { Builder } from './builder'; 23import { ComponentBuilder } from './../stateManagement/runtime'; 24 25/** 26 * Indicates the type of Repeat's Data Source. 27 * 28 * @typedef { Array<T> | ReadonlyArray<T> | Readonly<Array<T>> } 29 * @syscap SystemCapability.ArkUI.ArkUI.Full 30 * @since 20 31 */ 32type RepeatArray<T> = Array<T> | ReadonlyArray<T> | Readonly<Array<T>>; 33/** 34 * Function that return typed string to render one template. 35 * 36 * @typedef {function} TemplateTypedFunc<T> 37 * @param { T } item - data item. 38 * @param { number } index - data index number in array. 39 * @returns { string } template type. 40 * @syscap SystemCapability.ArkUI.ArkUI.Full 41 * @since 20 42 */ 43type TemplateTypedFunc<T> = (item: T, index: number) => string; 44/** 45 * Define builder function to render one template type. 46 * 47 * @typedef {function} RepeatItemBuilder<T> 48 * @param { RepeatItem<T> } repeatItem - the repeat item builder function. 49 * @syscap SystemCapability.ArkUI.ArkUI.Full 50 * @since 20 51 */ 52@Builder 53type RepeatItemBuilder<T> = (repeatItem: RepeatItem<T>) => void; 54 55/** 56 * Construct a new type for each item. 57 * 58 * @interface RepeatItem 59 * @syscap SystemCapability.ArkUI.ArkUI.Full 60 * @since 20 61 */ 62export interface RepeatItem<T> { 63 /** 64 * The origin data. 65 * 66 * @type { T } 67 * @syscap SystemCapability.ArkUI.ArkUI.Full 68 * @since 20 69 */ 70 item: T; 71 /** 72 * index of each item. 73 * 74 * @type { number } 75 * @syscap SystemCapability.ArkUI.ArkUI.Full 76 * @since 20 77 */ 78 index: number; 79} 80 81/** 82 * Function that is used to do lazy loading. 83 * 84 * @typedef {function} OnLazyLoadingFunc 85 * @param { number } index - data index. 86 * @syscap SystemCapability.ArkUI.ArkUI.Full 87 * @since 20 88 */ 89type OnLazyLoadingFunc = (index: number) => void; 90 91/** 92 * Define key generator function. 93 * 94 * @typedef {function} KeyGeneratorFunc<T> 95 * @param { T } item - data item. 96 * @param { number } index - data index number in array. 97 * @returns { string } key value. 98 * @syscap SystemCapability.ArkUI.ArkUI.Full 99 * @since 20 100 */ 101type KeyGeneratorFunc<T> = (item: T, index: number) => string; 102 103/** 104 * Function that is used to get total count. 105 * 106 * @typedef {function} OnTotalCountFunc 107 * @returns { number } Returns the total data count 108 * @syscap SystemCapability.ArkUI.ArkUI.Full 109 * @since 20 110 */ 111type OnTotalCountFunc = () => number; 112 113/** 114 * Define the options of repeat virtualScroll to implement reuse and lazy loading. 115 * 116 * @interface VirtualScrollOptions 117 * @syscap SystemCapability.ArkUI.ArkUI.Full 118 * @since 20 119 */ 120export interface VirtualScrollOptions { 121 /** 122 * Total data count. 123 * 124 * @type { ?number } 125 * @syscap SystemCapability.ArkUI.ArkUI.Full 126 * @since 20 127 */ 128 totalCount?: number; 129 /** 130 * Reuse or not. 131 * 132 * @type { ?boolean } 133 * @default true 134 * @syscap SystemCapability.ArkUI.ArkUI.Full 135 * @since 20 136 */ 137 reusable?: boolean; 138 /** 139 * Data lazy loading 140 * 141 * @type { ?OnLazyLoadingFunc } 142 * @syscap SystemCapability.ArkUI.ArkUI.Full 143 * @since 20 144 */ 145 onLazyLoading?: OnLazyLoadingFunc; 146 /** 147 * The function of total data count. 148 * 149 * @type { ?OnTotalCountFunc } 150 * @syscap SystemCapability.ArkUI.ArkUI.Full 151 * @since 20 152 */ 153 onTotalCount?: OnTotalCountFunc; 154 /** 155 * Indicates whether to activate virtual scroll mode. 156 * 157 * @type { ?boolean } 158 * @default false 159 * @syscap SystemCapability.ArkUI.ArkUI.Full 160 * @since 20 161 */ 162 disableVirtualScroll?: boolean; 163} 164 165/** 166 * Define a builder template option parameter. 167 * 168 * @interface TemplateOptions 169 * @syscap SystemCapability.ArkUI.ArkUI.Full 170 * @since 20 171 */ 172export interface TemplateOptions { 173 /** 174 * The cached number of each template. 175 * 176 * @type { ?number } 177 * @syscap SystemCapability.ArkUI.ArkUI.Full 178 * @since 20 179 */ 180 cachedCount?: number; 181} 182 183/** 184 * Defines the Repeat component attribute functions. 185 * 186 * @typedef RepeatAttribute<T> 187 * @syscap SystemCapability.ArkUI.ArkUI.Full 188 * @since 20 189 */ 190export interface RepeatAttribute<T> { 191 /** 192 * Executes itemGenerator of each item. 193 * 194 * @param { RepeatItemBuilder<T> } itemGenerator 195 * @returns { this } RepeatAttribute instance 196 * @syscap SystemCapability.ArkUI.ArkUI.Full 197 * @since 20 198 */ 199 each(itemGenerator: RepeatItemBuilder<T>): this; 200 /** 201 * Obtains key of each item. 202 * 203 * @param { KeyGeneratorFunc<T> } keyGenerator 204 * @returns { this } RepeatAttribute instance 205 * @syscap SystemCapability.ArkUI.ArkUI.Full 206 * @since 20 207 */ 208 key(keyGenerator: KeyGeneratorFunc<T>): this; 209 /** 210 * Enable UI lazy loading when scroll up or down. 211 * 212 * @param { VirtualScrollOptions } [virtualScrollOptions] that defines the options of repeat virtual scroll to 213 * implement reuse and lazy loading. 214 * @returns { this } RepeatAttribute instance 215 * @syscap SystemCapability.ArkUI.ArkUI.Full 216 * @since 20 217 */ 218 virtualScroll(virtualScrollOptions?: VirtualScrollOptions): this; 219 /** 220 * Type builder function to render specific type of data item. 221 * 222 * @param { string } type that defines the template id. 223 * @param { RepeatItemBuilder<T> } itemBuilder that defines UI builder function. 224 * @param { TemplateOptions } [templateOptions] that defines a builder template option parameter. 225 * @returns { this } RepeatAttribute instance 226 * @syscap SystemCapability.ArkUI.ArkUI.Full 227 * @since 20 228 */ 229 template(type: string, itemBuilder: RepeatItemBuilder<T>, templateOptions?: TemplateOptions): this; 230 /** 231 * Typed function to render specific type of data item. 232 * 233 * @param { TemplateTypedFunc<T> } typedFunc that define template typed function. 234 * @returns { this } RepeatAttribute instance 235 * @syscap SystemCapability.ArkUI.ArkUI.Full 236 * @since 20 237 */ 238 templateId(typedFunc: TemplateTypedFunc<T>): this; 239} 240 241/** 242 * Indicates the type of Repeat. 243 * 244 * @param { RepeatArray<T> } arr - The Data Source 245 * @returns { RepeatAttribute<T> } 246 * @syscap SystemCapability.ArkUI.ArkUI.Full 247 * @since 20 248 */ 249@ComponentBuilder 250export declare function Repeat<T>(arr: RepeatArray<T>): RepeatAttribute<T>;