This page covers a non-latest version of Handsontable.
# AutoColumnSize
# Description
This plugin allows to set column widths based on their widest cells.
By default, the plugin is declared as undefined
, which makes it enabled (same as if it was declared as true
).
Enabling this plugin may decrease the overall table performance, as it needs to calculate the widths of all cells to
resize the columns accordingly.
If you experience problems with the performance, try turning this feature off and declaring the column widths manually.
Column width calculations are divided into sync and async part. Each of this parts has their own advantages and disadvantages. Synchronous calculations are faster but they block the browser UI, while the slower asynchronous operations don't block the browser UI.
To configure the sync/async distribution, you can pass an absolute value (number of columns) or a percentage value to a config object:
// as a number (300 columns in sync, rest async)
autoColumnSize: {syncLimit: 300},.
// as a string (percent)
autoColumnSize: {syncLimit: '40%'},
The plugin uses GhostTable and SamplesGenerator for calculations. First, SamplesGenerator prepares samples of data with its coordinates. Next GhostTable uses coordinates to get cells' renderers and append all to the DOM through DocumentFragment.
Sampling accepts additional options:
- samplingRatio - Defines how many samples for the same length will be used to calculate. Default is
3
.
autoColumnSize: {
samplingRatio: 10,
}
- allowSampleDuplicates - Defines if duplicated values might be used in sampling. Default is
false
.
autoColumnSize: {
allowSampleDuplicates: true,
}
To configure this plugin see Options#autoColumnSize.
Example
const hot = new Handsontable(document.getElementById('example'), {
data: getData(),
autoColumnSize: true
});
// Access to plugin instance:
const plugin = hot.getPlugin('autoColumnSize');
plugin.getColumnWidth(4);
if (plugin.isEnabled()) {
// code...
}
# Options
# autoColumnSize
Source code (opens new window)autoColumnSize.autoColumnSize : object | boolean
Enables or disables the AutoColumnSize plugin. Default value undefined
is an equivalent of true
, sets syncLimit
to 50.
Disabling this plugin can increase performance, as no size-related calculations would be done.
To disable plugin it's necessary to set false
.
Column width calculations are divided into sync and async part. Each of those parts has their own advantages and disadvantages. Synchronous calculations are faster but they block the browser UI, while the slower asynchronous operations don't block the browser UI.
To configure the sync/async distribution, you can pass an absolute value (number of columns) or a percentage value.
You can also use the useHeaders
option to take the column headers width into calculation.
Note: Using Core#colWidths option will forcibly disable AutoColumnSize.
Default: undefined
Example
// as a number (300 columns in sync, rest async)
autoColumnSize: { syncLimit: 300 },
// as a string (percent)
autoColumnSize: { syncLimit: '40%' },
// use headers width while calculating the column width
autoColumnSize: { useHeaders: true },
// defines how many samples for the same length will be caught to calculations
autoColumnSize: { samplingRatio: 10 },
// defines if duplicated samples are allowed in calculations
autoColumnSize: { allowSampleDuplicates: true },
# Members
# inProgress
Source code (opens new window)autoColumnSize.inProgress : boolean
true
if the size calculation is in progress.
# measuredColumns
Source code (opens new window)autoColumnSize.measuredColumns : number
Number of already measured columns (we already know their sizes).
# Methods
# calculateAllColumnsWidth
Source code (opens new window)autoColumnSize.calculateAllColumnsWidth(rowRange)
Calculates all columns width. The calculated column will be cached in the AutoColumnSize#widths property. To retrieve width for specified column use AutoColumnSize#getColumnWidth method.
Param | Type | Description |
---|---|---|
rowRange | object number | Row index or an object with from and to properties which define row range. |
# calculateColumnsWidth
Source code (opens new window)autoColumnSize.calculateColumnsWidth(colRange, rowRange, [force])
Calculates a columns width.
Param | Type | Default | Description |
---|---|---|---|
colRange | number object | Visual column index or an object with from and to visual indexes as a range. | |
rowRange | number object | Visual row index or an object with from and to visual indexes as a range. | |
[force] | boolean | false | optional If true the calculation will be processed regardless of whether the width exists in the cache. |
# calculateVisibleColumnsWidth
Source code (opens new window)autoColumnSize.calculateVisibleColumnsWidth()
Calculates visible columns width.
# clearCache
Source code (opens new window)autoColumnSize.clearCache([columns])
Clears cache of calculated column widths. If you want to clear only selected columns pass an array with their indexes. Otherwise whole cache will be cleared.
Param | Type | Description |
---|---|---|
[columns] | Array<number> | optional List of physical column indexes to clear. |
# destroy
Source code (opens new window)autoColumnSize.destroy()
Destroys the plugin instance.
# disablePlugin
Source code (opens new window)autoColumnSize.disablePlugin()
Disables the plugin functionality for this Handsontable instance.
# enablePlugin
Source code (opens new window)autoColumnSize.enablePlugin()
Enables the plugin functionality for this Handsontable instance.
# getColumnWidth
Source code (opens new window)autoColumnSize.getColumnWidth(column, [defaultWidth], [keepMinimum]) ⇒ number
Gets the calculated column width.
Param | Type | Default | Description |
---|---|---|---|
column | number | Visual column index. | |
[defaultWidth] | number | optional Default column width. It will be picked up if no calculated width found. | |
[keepMinimum] | boolean | true | optional If true then returned value won't be smaller then 50 (default column width). |
# getFirstVisibleColumn
Source code (opens new window)autoColumnSize.getFirstVisibleColumn() ⇒ number
Gets the first visible column.
Returns: number
- Returns visual column index, -1 if table is not rendered or if there are no columns to base the the calculations on.
# getLastVisibleColumn
Source code (opens new window)autoColumnSize.getLastVisibleColumn() ⇒ number
Gets the last visible column.
Returns: number
- Returns visual column index or -1 if table is not rendered.
# getSyncCalculationLimit
Source code (opens new window)autoColumnSize.getSyncCalculationLimit() ⇒ number
Gets value which tells how many columns should be calculated synchronously (rest of the columns will be calculated
asynchronously). The limit is calculated based on syncLimit
set to autoColumnSize
option (see Options#autoColumnSize).
# isEnabled
Source code (opens new window)autoColumnSize.isEnabled() ⇒ boolean
Checks if the plugin is enabled in the handsontable settings. This method is executed in Hooks#beforeInit
hook and if it returns true
than the #enablePlugin method is called.
# isNeedRecalculate
Source code (opens new window)autoColumnSize.isNeedRecalculate() ⇒ boolean
Checks if all widths were calculated. If not then return true
(need recalculate).
# recalculateAllColumnsWidth
Source code (opens new window)autoColumnSize.recalculateAllColumnsWidth()
Recalculates all columns width (overwrite cache values).
# updatePlugin
Source code (opens new window)autoColumnSize.updatePlugin()
Updates the plugin state. This method is executed when Core#updateSettings is invoked.
← Options AutoRowSize →