⚠️ This plugin is in active development and its API might change without notice. As long as it is unstable, it will be released with 0.X version scheme, as per the semver standard.
@native-html/heuristic-table-plugin
npm add --save @native-html/heuristic-table-pluginyarn add @native-html/heuristic-table-pluginCompat Table
| react-native-render-html | @native-html/heuristic-table-plugin |
|---|---|
| < 6.0.0 | - |
| ≥ 6.0.0 | 6.x (documentation) |
Minimal working example
import React from 'react';
import { ScrollView } from 'react-native';
import HTML from 'react-native-render-html';
import tableRenderers from '@native-html/heuristic-table-plugin';
const html = `
<table>
<tr>
<th>Entry Header 1</th>
<th>Entry Header 2</th>
</tr>
<tr>
<td>Entry First Line 1</td>
<td>Entry First Line 2</td>
</tr>
</table>
`;
const htmlProps = {
WebView,
renderers: {
...tableRenderers
},
renderersProps: {
table: {
// Put the table config here
}
}
};
export const Example = () => (
<ScrollView>
<HTML source={{ html }} {...htmlProps} />
</ScrollView>
);Configuration
To change the layout of cells and other options, you can pass a config object
to the renderersProps.table prop of RenderHTML component.
See the documentation for this object here: HeuristicTablePluginConfig
Custom Renderers
Customizing Root renderer
You can customize the renderer logic thanks to useHtmlTableProps hook and HTMLTable exports:
import React from 'react';
import tableRenderers, {useHtmlTableProps, HTMLTable} from '@native-html/heuristic-table-plugin';
function TableRenderer(props) {
const tableProps = useHtmlTableProps(props, /* config */);
// Do customize the props here; wrap with your own container...
return <HTMLTable {..tableProps} />;
};
const renderers = {
...tableRenderers,
table: TableRenderer
}
// use "renderers" prop in your RenderHTML instanceCustomizing Th and Td renderers
You can customize cell rendering via useHtmlTableCellProps, thModel and
tdModel exports. This renderer will receive a special propsFromParent of
type
TableCellPropsFromParent.
You can take advantage of this information to customize depending on the
position of the cell in the grid system coordinate, as shown below:
import React from 'react';
import {
TableRenderer,
ThRenderer,
useHtmlTableCellProps,
tdModel
} from '@native-html/heuristic-table-plugin';
function TdRenderer(props) {
const cellProps = useHtmlTableCellProps(props);
// The cell parent prop contains information about this cell,
// especially its position (x, y) and lengths (lenX, lenY).
// In this example, we customize the background depending on the
// y coordinate (row index).
const { cell } = cellProps.propsFromParent;
const style = [
cellProps.style,
backgroundColor: cell.x % 2 === 0 ? 'lightgray' : 'white'
]
return React.createElement(cellProps.TDefaultRenderer, { ...cellProps, style });
}
const renderers = {
table: TableRenderer,
td: TdRenderer,
th: ThRenderer
}
// use "renderers" prop in your RenderHTML instanceThe heuristic layout algorithm
Finding the cell sizes which result in the table of the least height given a fixed width is a NP complete problem.
To resolve this problem, this library uses a dumb and cheap algorithm, which won't find the best solution but instead a visually acceptable layout.
1. Cell constraints extraction
In the first step, each cell of the table is parsed to extract two metrics:
minWidth and contentDensity. minWidth is an estimation of the width taken
by the longest word in the cell, or the explicit width or min-width of any
block in the cell, or the greatest of the two. contentDensity is the width
taken by all the text displayed in one line.
2. Column constraints reduction
In the second step, cell constraints are reduced per column. Three metrics come out:
-
minWidth, the maximum of each cellminWidth; -
contentDensity, the sum of each cellcontentDensity; -
spread, the maximum of each cellcontentDensity.
3. Column widths calculation
Let minTableWidth be the sum of all column minWidth. If minTableWidth > contentWidth, assign to each column a width corresponding to its minWidth
constraint.
Otherwise, let spaceToAllocate = contentWidth - minTableWidth. Allocate to each column a width equal to its minWidth constraint + spaceToAllocate * gamma, with gamma = (normalContentDensity) / sum(normalContentDensities). The normalContentDensity is contentDensity - min(contentDensities).
Finally, clamp the assign width to the spread constraint for this column, unless forceStretch parameter is set to true.