blob: 1d94a6e3e4b392e54ef8370e5ec8eae96f00cc5f [file] [log] [blame]
/**
* @license
* Copyright Google LLC All Rights Reserved.
*
* Use of this source code is governed by an MIT-style license that can be
* found in the LICENSE file at https://angular.io/license
*/
import { Directionality } from '@angular/cdk/bidi';
import { CollectionViewer, DataSource } from '@angular/cdk/collections';
import { Platform } from '@angular/cdk/platform';
import { AfterContentChecked, ChangeDetectorRef, ElementRef, IterableDiffers, OnDestroy, OnInit, QueryList, TrackByFunction, ViewContainerRef } from '@angular/core';
import { BehaviorSubject, Observable } from 'rxjs';
import { CdkColumnDef } from './cell';
import { CdkCellOutletMultiRowContext, CdkCellOutletRowContext, CdkFooterRowDef, CdkHeaderRowDef, CdkRowDef } from './row';
/** Interface used to provide an outlet for rows to be inserted into. */
export interface RowOutlet {
viewContainer: ViewContainerRef;
}
/**
* Union of the types that can be set as the data source for a `CdkTable`.
* @docs-private
*/
declare type CdkTableDataSourceInput<T> = DataSource<T> | Observable<ReadonlyArray<T> | T[]> | ReadonlyArray<T> | T[];
/**
* Provides a handle for the table to grab the view container's ng-container to insert data rows.
* @docs-private
*/
export declare class DataRowOutlet implements RowOutlet {
viewContainer: ViewContainerRef;
elementRef: ElementRef;
constructor(viewContainer: ViewContainerRef, elementRef: ElementRef);
}
/**
* Provides a handle for the table to grab the view container's ng-container to insert the header.
* @docs-private
*/
export declare class HeaderRowOutlet implements RowOutlet {
viewContainer: ViewContainerRef;
elementRef: ElementRef;
constructor(viewContainer: ViewContainerRef, elementRef: ElementRef);
}
/**
* Provides a handle for the table to grab the view container's ng-container to insert the footer.
* @docs-private
*/
export declare class FooterRowOutlet implements RowOutlet {
viewContainer: ViewContainerRef;
elementRef: ElementRef;
constructor(viewContainer: ViewContainerRef, elementRef: ElementRef);
}
/**
* The table template that can be used by the mat-table. Should not be used outside of the
* material library.
* @docs-private
*/
export declare const CDK_TABLE_TEMPLATE = "\n <ng-content select=\"caption\"></ng-content>\n <ng-container headerRowOutlet></ng-container>\n <ng-container rowOutlet></ng-container>\n <ng-container footerRowOutlet></ng-container>\n";
/**
* Interface used to conveniently type the possible context interfaces for the render row.
* @docs-private
*/
export interface RowContext<T> extends CdkCellOutletMultiRowContext<T>, CdkCellOutletRowContext<T> {
}
/**
* Set of properties that represents the identity of a single rendered row.
*
* When the table needs to determine the list of rows to render, it will do so by iterating through
* each data object and evaluating its list of row templates to display (when multiTemplateDataRows
* is false, there is only one template per data object). For each pair of data object and row
* template, a `RenderRow` is added to the list of rows to render. If the data object and row
* template pair has already been rendered, the previously used `RenderRow` is added; else a new
* `RenderRow` is * created. Once the list is complete and all data objects have been itereated
* through, a diff is performed to determine the changes that need to be made to the rendered rows.
*
* @docs-private
*/
export interface RenderRow<T> {
data: T;
dataIndex: number;
rowDef: CdkRowDef<T>;
}
/**
* A data table that can render a header row, data rows, and a footer row.
* Uses the dataSource input to determine the data to be rendered. The data can be provided either
* as a data array, an Observable stream that emits the data array to render, or a DataSource with a
* connect function that will return an Observable stream that emits the data array to render.
*/
export declare class CdkTable<T> implements AfterContentChecked, CollectionViewer, OnDestroy, OnInit {
protected readonly _differs: IterableDiffers;
protected readonly _changeDetectorRef: ChangeDetectorRef;
protected readonly _elementRef: ElementRef;
protected readonly _dir: Directionality;
private _platform;
private _document;
/** Latest data provided by the data source. */
protected _data: T[] | ReadonlyArray<T>;
/** Subject that emits when the component has been destroyed. */
private _onDestroy;
/** List of the rendered rows as identified by their `RenderRow` object. */
private _renderRows;
/** Subscription that listens for the data provided by the data source. */
private _renderChangeSubscription;
/**
* Map of all the user's defined columns (header, data, and footer cell template) identified by
* name. Collection populated by the column definitions gathered by `ContentChildren` as well as
* any custom column definitions added to `_customColumnDefs`.
*/
private _columnDefsByName;
/**
* Set of all row definitions that can be used by this table. Populated by the rows gathered by
* using `ContentChildren` as well as any custom row definitions added to `_customRowDefs`.
*/
private _rowDefs;
/**
* Set of all header row definitions that can be used by this table. Populated by the rows
* gathered by using `ContentChildren` as well as any custom row definitions added to
* `_customHeaderRowDefs`.
*/
private _headerRowDefs;
/**
* Set of all row definitions that can be used by this table. Populated by the rows gathered by
* using `ContentChildren` as well as any custom row definitions added to
* `_customFooterRowDefs`.
*/
private _footerRowDefs;
/** Differ used to find the changes in the data provided by the data source. */
private _dataDiffer;
/** Stores the row definition that does not have a when predicate. */
private _defaultRowDef;
/**
* Column definitions that were defined outside of the direct content children of the table.
* These will be defined when, e.g., creating a wrapper around the cdkTable that has
* column definitions as *it's* content child.
*/
private _customColumnDefs;
/**
* Data row definitions that were defined outside of the direct content children of the table.
* These will be defined when, e.g., creating a wrapper around the cdkTable that has
* built-in data rows as *it's* content child.
*/
private _customRowDefs;
/**
* Header row definitions that were defined outside of the direct content children of the table.
* These will be defined when, e.g., creating a wrapper around the cdkTable that has
* built-in header rows as *it's* content child.
*/
private _customHeaderRowDefs;
/**
* Footer row definitions that were defined outside of the direct content children of the table.
* These will be defined when, e.g., creating a wrapper around the cdkTable that has a
* built-in footer row as *it's* content child.
*/
private _customFooterRowDefs;
/**
* Whether the header row definition has been changed. Triggers an update to the header row after
* content is checked. Initialized as true so that the table renders the initial set of rows.
*/
private _headerRowDefChanged;
/**
* Whether the footer row definition has been changed. Triggers an update to the footer row after
* content is checked. Initialized as true so that the table renders the initial set of rows.
*/
private _footerRowDefChanged;
/**
* Cache of the latest rendered `RenderRow` objects as a map for easy retrieval when constructing
* a new list of `RenderRow` objects for rendering rows. Since the new list is constructed with
* the cached `RenderRow` objects when possible, the row identity is preserved when the data
* and row template matches, which allows the `IterableDiffer` to check rows by reference
* and understand which rows are added/moved/removed.
*
* Implemented as a map of maps where the first key is the `data: T` object and the second is the
* `CdkRowDef<T>` object. With the two keys, the cache points to a `RenderRow<T>` object that
* contains an array of created pairs. The array is necessary to handle cases where the data
* array contains multiple duplicate data objects and each instantiated `RenderRow` must be
* stored.
*/
private _cachedRenderRowsMap;
/** Whether the table is applied to a native `<table>`. */
private _isNativeHtmlTable;
/**
* Utility class that is responsible for applying the appropriate sticky positioning styles to
* the table's rows and cells.
*/
private _stickyStyler;
/**
* CSS class added to any row or cell that has sticky positioning applied. May be overriden by
* table subclasses.
*/
protected stickyCssClass: string;
/**
* Tracking function that will be used to check the differences in data changes. Used similarly
* to `ngFor` `trackBy` function. Optimize row operations by identifying a row based on its data
* relative to the function to know if a row should be added/removed/moved.
* Accepts a function that takes two parameters, `index` and `item`.
*/
trackBy: TrackByFunction<T>;
private _trackByFn;
/**
* The table's source of data, which can be provided in three ways (in order of complexity):
* - Simple data array (each object represents one table row)
* - Stream that emits a data array each time the array changes
* - `DataSource` object that implements the connect/disconnect interface.
*
* If a data array is provided, the table must be notified when the array's objects are
* added, removed, or moved. This can be done by calling the `renderRows()` function which will
* render the diff since the last table render. If the data array reference is changed, the table
* will automatically trigger an update to the rows.
*
* When providing an Observable stream, the table will trigger an update automatically when the
* stream emits a new array of data.
*
* Finally, when providing a `DataSource` object, the table will use the Observable stream
* provided by the connect function and trigger updates when that stream emits new data array
* values. During the table's ngOnDestroy or when the data source is removed from the table, the
* table will call the DataSource's `disconnect` function (may be useful for cleaning up any
* subscriptions registered during the connect process).
*/
dataSource: CdkTableDataSourceInput<T>;
private _dataSource;
/**
* Whether to allow multiple rows per data object by evaluating which rows evaluate their 'when'
* predicate to true. If `multiTemplateDataRows` is false, which is the default value, then each
* dataobject will render the first row that evaluates its when predicate to true, in the order
* defined in the table, or otherwise the default row which does not have a when predicate.
*/
multiTemplateDataRows: boolean;
_multiTemplateDataRows: boolean;
/**
* Stream containing the latest information on what rows are being displayed on screen.
* Can be used by the data source to as a heuristic of what data should be provided.
*
* @docs-private
*/
viewChange: BehaviorSubject<{
start: number;
end: number;
}>;
_rowOutlet: DataRowOutlet;
_headerRowOutlet: HeaderRowOutlet;
_footerRowOutlet: FooterRowOutlet;
/**
* The column definitions provided by the user that contain what the header, data, and footer
* cells should render for each column.
*/
_contentColumnDefs: QueryList<CdkColumnDef>;
/** Set of data row definitions that were provided to the table as content children. */
_contentRowDefs: QueryList<CdkRowDef<T>>;
/** Set of header row definitions that were provided to the table as content children. */
_contentHeaderRowDefs: QueryList<CdkHeaderRowDef>;
/** Set of footer row definitions that were provided to the table as content children. */
_contentFooterRowDefs: QueryList<CdkFooterRowDef>;
constructor(_differs: IterableDiffers, _changeDetectorRef: ChangeDetectorRef, _elementRef: ElementRef, role: string, _dir: Directionality, _document: any, _platform: Platform);
ngOnInit(): void;
ngAfterContentChecked(): void;
ngOnDestroy(): void;
/**
* Renders rows based on the table's latest set of data, which was either provided directly as an
* input or retrieved through an Observable stream (directly or from a DataSource).
* Checks for differences in the data since the last diff to perform only the necessary
* changes (add/remove/move rows).
*
* If the table's data source is a DataSource or Observable, this will be invoked automatically
* each time the provided Observable stream emits a new data array. Otherwise if your data is
* an array, this function will need to be called to render any changes.
*/
renderRows(): void;
/**
* Sets the header row definition to be used. Overrides the header row definition gathered by
* using `ContentChild`, if one exists. Sets a flag that will re-render the header row after the
* table's content is checked.
* @docs-private
* @deprecated Use `addHeaderRowDef` and `removeHeaderRowDef` instead
* @breaking-change 8.0.0
*/
setHeaderRowDef(headerRowDef: CdkHeaderRowDef): void;
/**
* Sets the footer row definition to be used. Overrides the footer row definition gathered by
* using `ContentChild`, if one exists. Sets a flag that will re-render the footer row after the
* table's content is checked.
* @docs-private
* @deprecated Use `addFooterRowDef` and `removeFooterRowDef` instead
* @breaking-change 8.0.0
*/
setFooterRowDef(footerRowDef: CdkFooterRowDef): void;
/** Adds a column definition that was not included as part of the content children. */
addColumnDef(columnDef: CdkColumnDef): void;
/** Removes a column definition that was not included as part of the content children. */
removeColumnDef(columnDef: CdkColumnDef): void;
/** Adds a row definition that was not included as part of the content children. */
addRowDef(rowDef: CdkRowDef<T>): void;
/** Removes a row definition that was not included as part of the content children. */
removeRowDef(rowDef: CdkRowDef<T>): void;
/** Adds a header row definition that was not included as part of the content children. */
addHeaderRowDef(headerRowDef: CdkHeaderRowDef): void;
/** Removes a header row definition that was not included as part of the content children. */
removeHeaderRowDef(headerRowDef: CdkHeaderRowDef): void;
/** Adds a footer row definition that was not included as part of the content children. */
addFooterRowDef(footerRowDef: CdkFooterRowDef): void;
/** Removes a footer row definition that was not included as part of the content children. */
removeFooterRowDef(footerRowDef: CdkFooterRowDef): void;
/**
* Updates the header sticky styles. First resets all applied styles with respect to the cells
* sticking to the top. Then, evaluating which cells need to be stuck to the top. This is
* automatically called when the header row changes its displayed set of columns, or if its
* sticky input changes. May be called manually for cases where the cell content changes outside
* of these events.
*/
updateStickyHeaderRowStyles(): void;
/**
* Updates the footer sticky styles. First resets all applied styles with respect to the cells
* sticking to the bottom. Then, evaluating which cells need to be stuck to the bottom. This is
* automatically called when the footer row changes its displayed set of columns, or if its
* sticky input changes. May be called manually for cases where the cell content changes outside
* of these events.
*/
updateStickyFooterRowStyles(): void;
/**
* Updates the column sticky styles. First resets all applied styles with respect to the cells
* sticking to the left and right. Then sticky styles are added for the left and right according
* to the column definitions for each cell in each row. This is automatically called when
* the data source provides a new set of data or when a column definition changes its sticky
* input. May be called manually for cases where the cell content changes outside of these events.
*/
updateStickyColumnStyles(): void;
/**
* Get the list of RenderRow objects to render according to the current list of data and defined
* row definitions. If the previous list already contained a particular pair, it should be reused
* so that the differ equates their references.
*/
private _getAllRenderRows;
/**
* Gets a list of `RenderRow<T>` for the provided data object and any `CdkRowDef` objects that
* should be rendered for this data. Reuses the cached RenderRow objects if they match the same
* `(T, CdkRowDef)` pair.
*/
private _getRenderRowsForData;
/** Update the map containing the content's column definitions. */
private _cacheColumnDefs;
/** Update the list of all available row definitions that can be used. */
private _cacheRowDefs;
/**
* Check if the header, data, or footer rows have changed what columns they want to display or
* whether the sticky states have changed for the header or footer. If there is a diff, then
* re-render that section.
*/
private _renderUpdatedColumns;
/**
* Switch to the provided data source by resetting the data and unsubscribing from the current
* render change subscription if one exists. If the data source is null, interpret this by
* clearing the row outlet. Otherwise start listening for new data.
*/
private _switchDataSource;
/** Set up a subscription for the data provided by the data source. */
private _observeRenderChanges;
/**
* Clears any existing content in the header row outlet and creates a new embedded view
* in the outlet using the header row definition.
*/
private _forceRenderHeaderRows;
/**
* Clears any existing content in the footer row outlet and creates a new embedded view
* in the outlet using the footer row definition.
*/
private _forceRenderFooterRows;
/** Adds the sticky column styles for the rows according to the columns' stick states. */
private _addStickyColumnStyles;
/** Gets the list of rows that have been rendered in the row outlet. */
_getRenderedRows(rowOutlet: RowOutlet): HTMLElement[];
/**
* Get the matching row definitions that should be used for this row data. If there is only
* one row definition, it is returned. Otherwise, find the row definitions that has a when
* predicate that returns true with the data. If none return true, return the default row
* definition.
*/
_getRowDefs(data: T, dataIndex: number): CdkRowDef<T>[];
/**
* Create the embedded view for the data row template and place it in the correct index location
* within the data row view container.
*/
private _insertRow;
/**
* Creates a new row template in the outlet and fills it with the set of cell templates.
* Optionally takes a context to provide to the row and cells, as well as an optional index
* of where to place the new row template in the outlet.
*/
private _renderRow;
/**
* Updates the index-related context for each row to reflect any changes in the index of the rows,
* e.g. first/last/even/odd.
*/
private _updateRowIndexContext;
/** Gets the column definitions for the provided row def. */
private _getCellTemplates;
/** Adds native table sections (e.g. tbody) and moves the row outlets into them. */
private _applyNativeTableSections;
/**
* Forces a re-render of the data rows. Should be called in cases where there has been an input
* change that affects the evaluation of which rows should be rendered, e.g. toggling
* `multiTemplateDataRows` or adding/removing row definitions.
*/
private _forceRenderDataRows;
/**
* Checks if there has been a change in sticky states since last check and applies the correct
* sticky styles. Since checking resets the "dirty" state, this should only be performed once
* during a change detection and after the inputs are settled (after content check).
*/
private _checkStickyStates;
/**
* Creates the sticky styler that will be used for sticky rows and columns. Listens
* for directionality changes and provides the latest direction to the styler. Re-applies column
* stickiness when directionality changes.
*/
private _setupStickyStyler;
}
export {};