a zip code crypto-currency system good for red ONLY

virtual-scroll.d.ts 16KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426
  1. import { AfterContentInit, ChangeDetectorRef, DoCheck, ElementRef, IterableDiffer, IterableDiffers, NgZone, OnChanges, OnDestroy, Renderer, SimpleChanges, TrackByFunction } from '@angular/core';
  2. import { Config } from '../../config/config';
  3. import { Content, ScrollEvent } from '../content/content';
  4. import { DomController } from '../../platform/dom-controller';
  5. import { Platform } from '../../platform/platform';
  6. import { ViewController } from '../../navigation/view-controller';
  7. import { VirtualCell, VirtualData, VirtualNode } from './virtual-util';
  8. import { VirtualItem } from './virtual-item';
  9. import { VirtualFooter } from './virtual-footer';
  10. import { VirtualHeader } from './virtual-header';
  11. /**
  12. * @name VirtualScroll
  13. * @description
  14. * Virtual Scroll displays a virtual, "infinite" list. An array of records
  15. * is passed to the virtual scroll containing the data to create templates
  16. * for. The template created for each record, referred to as a cell, can
  17. * consist of items, headers, and footers.
  18. *
  19. * For performance reasons, not every record in the list is rendered at once;
  20. * instead a small subset of records (enough to fill the viewport) are rendered
  21. * and reused as the user scrolls.
  22. *
  23. * ### The Basics
  24. *
  25. * The array of records should be passed to the `virtualScroll` property.
  26. * The data given to the `virtualScroll` property must be an array. An item
  27. * template with the `*virtualItem` property is required in the `virtualScroll`.
  28. * The `virtualScroll` and `*virtualItem` properties can be added to any element.
  29. *
  30. * ```html
  31. * <ion-list [virtualScroll]="items">
  32. *
  33. * <ion-item *virtualItem="let item">
  34. * {% raw %}{{ item }}{% endraw %}
  35. * </ion-item>
  36. *
  37. * </ion-list>
  38. * ```
  39. *
  40. *
  41. * ### Section Headers and Footers
  42. *
  43. * Section headers and footers are optional. They can be dynamically created
  44. * from developer-defined functions. For example, a large list of contacts
  45. * usually has a divider for each letter in the alphabet. Developers provide
  46. * their own custom function to be called on each record. The logic in the
  47. * custom function should determine whether to create the section template
  48. * and what data to provide to the template. The custom function should
  49. * return `null` if a template shouldn't be created.
  50. *
  51. * ```html
  52. * <ion-list [virtualScroll]="items" [headerFn]="myHeaderFn">
  53. *
  54. * <ion-item-divider *virtualHeader="let header">
  55. * Header: {% raw %}{{ header }}{% endraw %}
  56. * </ion-item-divider>
  57. *
  58. * <ion-item *virtualItem="let item">
  59. * Item: {% raw %}{{ item }}{% endraw %}
  60. * </ion-item>
  61. *
  62. * </ion-list>
  63. * ```
  64. *
  65. * Below is an example of a custom function called on every record. It
  66. * gets passed the individual record, the record's index number,
  67. * and the entire array of records. In this example, after every 20
  68. * records a header will be inserted. So between the 19th and 20th records,
  69. * between the 39th and 40th, and so on, a `<ion-item-divider>` will
  70. * be created and the template's data will come from the function's
  71. * returned data.
  72. *
  73. * ```ts
  74. * myHeaderFn(record, recordIndex, records) {
  75. * if (recordIndex % 20 === 0) {
  76. * return 'Header ' + recordIndex;
  77. * }
  78. * return null;
  79. * }
  80. * ```
  81. *
  82. *
  83. * ### Approximate Widths and Heights
  84. *
  85. * If the height of items in the virtual scroll are not close to the
  86. * default size of 40px, it is extremely important to provide a value for
  87. * approxItemHeight height. An exact pixel-perfect size is not necessary,
  88. * but without an estimate the virtual scroll will not render correctly.
  89. *
  90. * The approximate width and height of each template is used to help
  91. * determine how many cells should be created, and to help calculate
  92. * the height of the scrollable area. Note that the actual rendered size
  93. * of each cell comes from the app's CSS, whereas this approximation
  94. * is only used to help calculate initial dimensions.
  95. *
  96. * It's also important to know that Ionic's default item sizes have
  97. * slightly different heights between platforms, which is perfectly fine.
  98. *
  99. *
  100. * ### Images Within Virtual Scroll
  101. *
  102. * HTTP requests, image decoding, and image rendering can cause jank while
  103. * scrolling. In order to better control images, Ionic provides `<ion-img>`
  104. * to manage HTTP requests and image rendering. While scrolling through items
  105. * quickly, `<ion-img>` knows when and when not to make requests, when and
  106. * when not to render images, and only loads the images that are viewable
  107. * after scrolling. [Read more about `ion-img`.](../../img/Img/)
  108. *
  109. * It's also important for app developers to ensure image sizes are locked in,
  110. * and after images have fully loaded they do not change size and affect any
  111. * other element sizes. Simply put, to ensure rendering bugs are not introduced,
  112. * it's vital that elements within a virtual item does not dynamically change.
  113. *
  114. * For virtual scrolling, the natural effects of the `<img>` are not desirable
  115. * features. We recommend using the `<ion-img>` component over the native
  116. * `<img>` element because when an `<img>` element is added to the DOM, it
  117. * immediately makes a HTTP request for the image file. Additionally, `<img>`
  118. * renders whenever it wants which could be while the user is scrolling. However,
  119. * `<ion-img>` is governed by the containing `ion-content` and does not render
  120. * images while scrolling quickly.
  121. *
  122. * ```html
  123. * <ion-list [virtualScroll]="items">
  124. *
  125. * <ion-item *virtualItem="let item">
  126. * <ion-avatar item-start>
  127. * <ion-img [src]="item.avatarUrl"></ion-img>
  128. * </ion-avatar>
  129. * {% raw %} {{ item.firstName }} {{ item.lastName }}{% endraw %}
  130. * </ion-item>
  131. *
  132. * </ion-list>
  133. * ```
  134. *
  135. *
  136. * ### Custom Components
  137. *
  138. * If a custom component is going to be used within Virtual Scroll, it's best
  139. * to wrap it with a good old `<div>` to ensure the component is rendered
  140. * correctly. Since each custom component's implementation and internals can be
  141. * quite different, wrapping within a `<div>` is a safe way to make sure
  142. * dimensions are measured correctly.
  143. *
  144. * ```html
  145. * <ion-list [virtualScroll]="items">
  146. *
  147. * <div *virtualItem="let item">
  148. * <my-custom-item [item]="item">
  149. * {% raw %} {{ item }}{% endraw %}
  150. * </my-custom-item>
  151. * </div>
  152. *
  153. * </ion-list>
  154. * ```
  155. *
  156. *
  157. * ## Virtual Scroll Performance Tips
  158. *
  159. * #### iOS Cordova WKWebView
  160. *
  161. * When deploying to iOS with Cordova, it's highly recommended to use the
  162. * [WKWebView plugin](http://blog.ionic.io/cordova-ios-performance-improvements-drop-in-speed-with-wkwebview/)
  163. * in order to take advantage of iOS's higher performimg webview. Additionally,
  164. * WKWebView is superior at scrolling efficiently in comparision to the older
  165. * UIWebView.
  166. *
  167. * #### Lock in element dimensions and locations
  168. *
  169. * In order for virtual scroll to efficiently size and locate every item, it's
  170. * very important every element within each virtual item does not dynamically
  171. * change its dimensions or location. The best way to ensure size and location
  172. * does not change, it's recommended each virtual item has locked in its size
  173. * via CSS.
  174. *
  175. * #### Use `ion-img` for images
  176. *
  177. * When including images within Virtual Scroll, be sure to use
  178. * [`ion-img`](../img/Img/) rather than the standard `<img>` HTML element.
  179. * With `ion-img`, images are lazy loaded so only the viewable ones are
  180. * rendered, and HTTP requests are efficiently controlled while scrolling.
  181. *
  182. * #### Set Approximate Widths and Heights
  183. *
  184. * As mentioned above, all elements should lock in their dimensions. However,
  185. * virtual scroll isn't aware of the dimensions until after they have been
  186. * rendered. For the initial render, virtual scroll still needs to set
  187. * how many items should be built. With "approx" property inputs, such as
  188. * `approxItemHeight`, we're able to give virtual scroll an approximate size,
  189. * therefore allowing virtual scroll to decide how many items should be
  190. * created.
  191. *
  192. * #### Changing dataset should use `virtualTrackBy`
  193. *
  194. * It is possible for the identities of elements in the iterator to change
  195. * while the data does not. This can happen, for example, if the iterator
  196. * produced from an RPC to the server, and that RPC is re-run. Even if the
  197. * "data" hasn't changed, the second response will produce objects with
  198. * different identities, and Ionic will tear down the entire DOM and rebuild
  199. * it. This is an expensive operation and should be avoided if possible.
  200. *
  201. * #### Efficient headers and footer functions
  202. *
  203. * Each virtual item must stay extremely efficient, but one way to really
  204. * kill its performance is to perform any DOM operations within section header
  205. * and footer functions. These functions are called for every record in the
  206. * dataset, so please make sure they're performant.
  207. *
  208. */
  209. export declare class VirtualScroll implements DoCheck, OnChanges, AfterContentInit, OnDestroy {
  210. private _iterableDiffers;
  211. private _elementRef;
  212. private _renderer;
  213. private _zone;
  214. private _cd;
  215. private _content;
  216. private _plt;
  217. private _ctrl;
  218. private _config;
  219. private _dom;
  220. _differ: IterableDiffer<any>;
  221. _scrollSub: any;
  222. _scrollEndSub: any;
  223. _resizeSub: any;
  224. _init: boolean;
  225. _lastEle: boolean;
  226. _hdrFn: Function;
  227. _ftrFn: Function;
  228. _records: any[];
  229. _cells: VirtualCell[];
  230. _nodes: VirtualNode[];
  231. _vHeight: number;
  232. _lastCheck: number;
  233. _recordSize: number;
  234. _data: VirtualData;
  235. _queue: number;
  236. _itmTmp: VirtualItem;
  237. _hdrTmp: VirtualHeader;
  238. _ftrTmp: VirtualFooter;
  239. /**
  240. * @input {array} The data that builds the templates within the virtual scroll.
  241. * This is the same data that you'd pass to `*ngFor`. It's important to note
  242. * that when this data has changed, then the entire virtual scroll is reset,
  243. * which is an expensive operation and should be avoided if possible.
  244. */
  245. virtualScroll: any;
  246. /**
  247. * @input {number} The buffer ratio is used to decide how many cells
  248. * should get created when initially rendered. The number is a
  249. * multiplier against the viewable area's height. For example, if it
  250. * takes `20` cells to fill up the height of the viewable area, then
  251. * with a buffer ratio of `3` it will create `60` cells that are
  252. * available for reuse while scrolling. For better performance, it's
  253. * better to have more cells than what are required to fill the
  254. * viewable area. Default is `3`.
  255. */
  256. bufferRatio: number;
  257. /**
  258. * @input {string} The approximate width of each item template's cell.
  259. * This dimension is used to help determine how many cells should
  260. * be created when initialized, and to help calculate the height of
  261. * the scrollable area. This value can use either `px` or `%` units.
  262. * Note that the actual rendered size of each cell comes from the
  263. * app's CSS, whereas this approximation is used to help calculate
  264. * initial dimensions before the item has been rendered. Default is
  265. * `100%`.
  266. */
  267. approxItemWidth: string;
  268. /**
  269. * @input {string} It is important to provide this
  270. * if virtual item height will be significantly larger than the default
  271. * The approximate height of each virtual item template's cell.
  272. * This dimension is used to help determine how many cells should
  273. * be created when initialized, and to help calculate the height of
  274. * the scrollable area. This height value can only use `px` units.
  275. * Note that the actual rendered size of each cell comes from the
  276. * app's CSS, whereas this approximation is used to help calculate
  277. * initial dimensions before the item has been rendered. Default is
  278. * `40px`.
  279. */
  280. approxItemHeight: string;
  281. /**
  282. * @input {string} The approximate width of each header template's cell.
  283. * This dimension is used to help determine how many cells should
  284. * be created when initialized, and to help calculate the height of
  285. * the scrollable area. This value can use either `px` or `%` units.
  286. * Note that the actual rendered size of each cell comes from the
  287. * app's CSS, whereas this approximation is used to help calculate
  288. * initial dimensions. Default is `100%`.
  289. */
  290. approxHeaderWidth: string;
  291. /**
  292. * @input {string} The approximate height of each header template's cell.
  293. * This dimension is used to help determine how many cells should
  294. * be created when initialized, and to help calculate the height of
  295. * the scrollable area. This height value can only use `px` units.
  296. * Note that the actual rendered size of each cell comes from the
  297. * app's CSS, whereas this approximation is used to help calculate
  298. * initial dimensions before the item has been rendered. Default is `40px`.
  299. */
  300. approxHeaderHeight: string;
  301. /**
  302. * @input {string} The approximate width of each footer template's cell.
  303. * This dimension is used to help determine how many cells should
  304. * be created when initialized, and to help calculate the height of
  305. * the scrollable area. This value can use either `px` or `%` units.
  306. * Note that the actual rendered size of each cell comes from the
  307. * app's CSS, whereas this approximation is used to help calculate
  308. * initial dimensions before the item has been rendered. Default is `100%`.
  309. */
  310. approxFooterWidth: string;
  311. /**
  312. * @input {string} The approximate height of each footer template's cell.
  313. * This dimension is used to help determine how many cells should
  314. * be created when initialized, and to help calculate the height of
  315. * the scrollable area. This height value can only use `px` units.
  316. * Note that the actual rendered size of each cell comes from the
  317. * app's CSS, whereas this approximation is used to help calculate
  318. * initial dimensions before the item has been rendered. Default is `40px`.
  319. */
  320. approxFooterHeight: string;
  321. /**
  322. * @input {function} Section headers and the data used within its given
  323. * template can be dynamically created by passing a function to `headerFn`.
  324. * For example, a large list of contacts usually has dividers between each
  325. * letter in the alphabet. App's can provide their own custom `headerFn`
  326. * which is called with each record within the dataset. The logic within
  327. * the header function can decide if the header template should be used,
  328. * and what data to give to the header template. The function must return
  329. * `null` if a header cell shouldn't be created.
  330. */
  331. headerFn: Function;
  332. /**
  333. * @input {function} Section footers and the data used within its given
  334. * template can be dynamically created by passing a function to `footerFn`.
  335. * The logic within the footer function can decide if the footer template
  336. * should be used, and what data to give to the footer template. The function
  337. * must return `null` if a footer cell shouldn't be created.
  338. */
  339. footerFn: Function;
  340. /**
  341. * @input {function} Same as `ngForTrackBy` which can be used on `ngFor`.
  342. */
  343. virtualTrackBy: TrackByFunction<any>;
  344. constructor(_iterableDiffers: IterableDiffers, _elementRef: ElementRef, _renderer: Renderer, _zone: NgZone, _cd: ChangeDetectorRef, _content: Content, _plt: Platform, _ctrl: ViewController, _config: Config, _dom: DomController);
  345. /**
  346. * @hidden
  347. */
  348. firstRecord(): number;
  349. /**
  350. * @hidden
  351. */
  352. lastRecord(): number;
  353. /**
  354. * @hidden
  355. */
  356. ngOnChanges(changes: SimpleChanges): void;
  357. /**
  358. * @hidden
  359. */
  360. ngDoCheck(): void;
  361. /**
  362. * @hidden
  363. */
  364. readUpdate(needClean: boolean): void;
  365. /**
  366. * @hidden
  367. */
  368. writeUpdate(needClean: boolean): void;
  369. /**
  370. * @hidden
  371. */
  372. private calcDimensions();
  373. /**
  374. * @hidden
  375. * DOM WRITE
  376. */
  377. renderVirtual(needClean: boolean): void;
  378. /**
  379. * @hidden
  380. */
  381. resize(): void;
  382. /**
  383. * @hidden
  384. */
  385. private _stepDOMWrite();
  386. /**
  387. * @hidden
  388. */
  389. private _stepChangeDetection();
  390. /**
  391. * @hidden
  392. */
  393. private _stepNoChanges();
  394. /**
  395. * @hidden
  396. */
  397. scrollUpdate(ev: ScrollEvent): void;
  398. /**
  399. * @hidden
  400. * DOM WRITE
  401. */
  402. scrollEnd(): void;
  403. /**
  404. * @hidden
  405. * NO DOM
  406. */
  407. private _listeners();
  408. /**
  409. * @hidden
  410. * DOM WRITE
  411. */
  412. private _setHeight(newVirtualHeight);
  413. /**
  414. * @hidden
  415. */
  416. ngAfterContentInit(): void;
  417. /**
  418. * @hidden
  419. */
  420. setElementClass(className: string, add: boolean): void;
  421. /**
  422. * @hidden
  423. */
  424. ngOnDestroy(): void;
  425. }