340 lines
8.2 KiB
Markdown
340 lines
8.2 KiB
Markdown
# Tables
|
|
|
|
!> Paragraphs requires an understanding of [Sections](usage/sections.md).
|
|
|
|
## Intro
|
|
|
|
Create a simple table like so:
|
|
|
|
```ts
|
|
const table = new Table({
|
|
rows: [Array of `TableRow`s]
|
|
});
|
|
```
|
|
|
|
Then add the table in the `section`
|
|
|
|
```ts
|
|
doc.addSection({
|
|
children: [table],
|
|
});
|
|
```
|
|
|
|
## Table Row
|
|
|
|
A table consists of multiple `table rows`. Table rows have a list of `children` which accepts a list of `table cells` explained below. You can create a simple `table row` like so:
|
|
|
|
```ts
|
|
const tableRow = new TableRow({
|
|
children: [
|
|
new TableCell({
|
|
children: [new Paragraph("hello")],
|
|
}),
|
|
],
|
|
});
|
|
```
|
|
|
|
Or preferably, add the tableRow directly into the `table` without declaring a variable:
|
|
|
|
```ts
|
|
const table = new Table({
|
|
rows: [
|
|
new TableRow({
|
|
children: [
|
|
new TableCell({
|
|
children: [new Paragraph("hello")],
|
|
}),
|
|
],
|
|
}),
|
|
],
|
|
});
|
|
```
|
|
|
|
### Options
|
|
|
|
Here is a list of options you can add to the `table row`:
|
|
|
|
| Property | Type | Notes |
|
|
| ----------- | ------------------------------------- | -------- |
|
|
| children | `Array<TableCell>` | Required |
|
|
| cantSplit | `boolean` | Optional |
|
|
| tableHeader | `boolean` | Optional |
|
|
| height | `{ value: number, rule: HeightRule }` | Optional |
|
|
|
|
## Cells
|
|
|
|
Cells need to be added in the `table row`, you can create a table cell like:
|
|
|
|
```ts
|
|
const tableCell = new TableCell({
|
|
children: [new Paragraph("hello")],
|
|
});
|
|
```
|
|
|
|
Or preferably, add the tableRow directly into the `table row` without declaring a variable:
|
|
|
|
```ts
|
|
const tableRow = new TableRow({
|
|
children: [
|
|
new TableCell({
|
|
children: [new Paragraph("hello")],
|
|
}),
|
|
],
|
|
});
|
|
```
|
|
|
|
| Property | Type | Notes |
|
|
| ----------- | ------------------------------------- | -------- |
|
|
| children | `Array<TableCell>` | Required |
|
|
| cantSplit | `boolean` | Optional |
|
|
| tableHeader | `boolean` | Optional |
|
|
| height | `{ value: number, rule: HeightRule }` | Optional |
|
|
|
|
### Options
|
|
|
|
readonly shading?: ITableShadingAttributesProperties;
|
|
readonly margins?: ITableCellMarginOptions;
|
|
readonly verticalAlign?: VerticalAlign;
|
|
readonly verticalMerge?: VMergeType;
|
|
readonly columnSpan?: number;
|
|
readonly borders?: {
|
|
readonly top?: {
|
|
readonly style: BorderStyle;
|
|
readonly size: number;
|
|
readonly color: string;
|
|
};
|
|
readonly bottom?: {
|
|
readonly style: BorderStyle;
|
|
readonly size: number;
|
|
readonly color: string;
|
|
};
|
|
readonly left?: {
|
|
readonly style: BorderStyle;
|
|
readonly size: number;
|
|
readonly color: string;
|
|
};
|
|
readonly right?: {
|
|
readonly style: BorderStyle;
|
|
readonly size: number;
|
|
readonly color: string;
|
|
};
|
|
};
|
|
readonly children: Array<Paragraph | Table>;
|
|
|
|
|
|
|
|
### Add paragraph to a cell
|
|
|
|
Once you have got the cell, you can add data to it with the `add()` method.
|
|
|
|
```ts
|
|
cell.add(new Paragraph("Hello"));
|
|
```
|
|
|
|
### Set width of a cell
|
|
|
|
You can specify the width of a cell using:
|
|
|
|
`cell.Properties.setWidth(width, format)`
|
|
|
|
format can be:
|
|
|
|
- WidthType.AUTO
|
|
- WidthType.DXA: value is in twentieths of a point
|
|
- WidthType.NIL: is considered as zero
|
|
- WidthType.PCT: percent of table width
|
|
|
|
### Example
|
|
|
|
```ts
|
|
cell.Properties.setWidth(100, WidthType.DXA);
|
|
```
|
|
|
|
```ts
|
|
cell.Properties.setWidth("50%", WidthType.PCT);
|
|
```
|
|
|
|
## Borders
|
|
|
|
BorderStyle can be imported from `docx`. Size determines the thickness. HTML color can be a hex code or alias such as `red`.
|
|
|
|
```ts
|
|
cell.Borders.addTopBorder([BorderStyle], [SIZE], [HTML COLOR]);
|
|
```
|
|
|
|
```ts
|
|
cell.Borders.addBottomBorder([BorderStyle], [SIZE], [HTML COLOR]);
|
|
```
|
|
|
|
```ts
|
|
cell.Borders.addStartBorder([[BorderStyle]], [SIZE], [HTML COLOR]);
|
|
```
|
|
|
|
```ts
|
|
cell.Borders.addEndBorder([BorderStyle], [SIZE], [HTML COLOR]);
|
|
```
|
|
|
|
### Example
|
|
|
|
```ts
|
|
import { BorderStyle } from "docx";
|
|
|
|
cell.Borders.addStartBorder(BorderStyle.DOT_DOT_DASH, 3, "green");
|
|
cell.Borders.addEndBorder(BorderStyle.DOT_DOT_DASH, 3, "#ff8000");
|
|
```
|
|
|
|
### Google DOCS
|
|
|
|
Google DOCS does not support start and end borders, instead they use left and right borders. So to set left and right borders for Google DOCS you should use:
|
|
|
|
```ts
|
|
import { BorderStyle } from "docx";
|
|
|
|
cell.Borders.addLeftBorder(BorderStyle.DOT_DOT_DASH, 3, "green");
|
|
cell.Borders.addRightBorder(BorderStyle.DOT_DOT_DASH, 3, "#ff8000");
|
|
```
|
|
|
|
## Set Width
|
|
|
|
```ts
|
|
import { WidthType } from "docx";
|
|
|
|
table.setWidth([WIDTH], [OPTIONAL WidthType. Defaults to DXA]);
|
|
```
|
|
|
|
For example:
|
|
|
|
```ts
|
|
table.setWidth(4535, WidthType.DXA);
|
|
```
|
|
|
|
## Vertical Align
|
|
|
|
Sets the vertical alignment of the contents of the cell
|
|
|
|
```ts
|
|
import { VerticalAlign } from "docx";
|
|
|
|
cell.setVerticalAlign([VerticalAlign TYPE]);
|
|
```
|
|
|
|
For example, to center align a cell:
|
|
|
|
```ts
|
|
cell.setVerticalAlign(VerticalAlign.CENTER);
|
|
```
|
|
|
|
## Rows
|
|
|
|
To get a row, use the `getRow` method on a `table`. There are a handful of methods which you can apply to a row which will be explained below.
|
|
|
|
```ts
|
|
table.getRow([ROW INDEX]);
|
|
```
|
|
|
|
## Merge cells together
|
|
|
|
### Merging on a row
|
|
|
|
First obtain the row, and call `mergeCells()`. The first argument is where the merge should start. The second argument is where the merge should end.
|
|
|
|
```ts
|
|
table.getRow(0).mergeCells([FROM INDEX], [TO INDEX]);
|
|
```
|
|
|
|
#### Example
|
|
|
|
This will merge 3 cells together starting from index `0`:
|
|
|
|
```ts
|
|
table.getRow(0).mergeCells(0, 2);
|
|
```
|
|
|
|
### Merging on a column
|
|
|
|
It has not been implemented yet, but it will follow a similar structure as merging a row.
|
|
|
|
## Nested Tables
|
|
|
|
To have a table within a table
|
|
|
|
```ts
|
|
cell.add(new Table(1, 1));
|
|
```
|
|
|
|
## Pagination
|
|
|
|
###Prevent row pagination
|
|
To prevent breaking contents of a row across multiple pages, call `cantSplit()`:
|
|
|
|
```ts
|
|
table.getRow(0).setCantSplit();
|
|
```
|
|
|
|
###Repeat row
|
|
If a table is paginated on multiple pages, it is possible to repeat a row at the top of each new page calling `setTableHeader()`:
|
|
|
|
```ts
|
|
table.getRow(0).setTableHeader();
|
|
```
|
|
|
|
## Examples
|
|
|
|
[Example](https://raw.githubusercontent.com/dolanmiu/docx/master/demo/4-basic-table.ts ':include')
|
|
|
|
_Source: https://github.com/dolanmiu/docx/blob/master/demo/4-basic-table.ts_
|
|
|
|
### Custom borders
|
|
|
|
Example showing how to add colourful borders to tables
|
|
|
|
[Example](https://raw.githubusercontent.com/dolanmiu/docx/master/demo/20-table-cell-borders.ts ':include')
|
|
|
|
_Source: https://github.com/dolanmiu/docx/blob/master/demo/20-table-cell-borders.ts_
|
|
|
|
### Adding images
|
|
|
|
Example showing how to add images to tables
|
|
|
|
[Example](https://raw.githubusercontent.com/dolanmiu/docx/master/demo/24-images-to-table-cell.ts ':include')
|
|
|
|
_Source: https://github.com/dolanmiu/docx/blob/master/demo/24-images-to-table-cell.ts_
|
|
|
|
[Example](https://raw.githubusercontent.com/dolanmiu/docx/master/demo/36-image-to-table-cell.ts ':include')
|
|
|
|
_Source: https://github.com/dolanmiu/docx/blob/master/demo/36-image-to-table-cell.ts_
|
|
|
|
### Alignment of text in a cell
|
|
|
|
Example showing how align text in a table cell
|
|
|
|
[Example](https://raw.githubusercontent.com/dolanmiu/docx/master/demo/31-tables.ts ':include')
|
|
|
|
_Source: https://github.com/dolanmiu/docx/blob/master/demo/31-tables.ts_
|
|
|
|
### Merging rows
|
|
|
|
Example showing merging of `rows`
|
|
|
|
[Example](https://raw.githubusercontent.com/dolanmiu/docx/master/demo/32-merge-table-cells.ts ':include')
|
|
|
|
_Source: https://github.com/dolanmiu/docx/blob/master/demo/32-merge-table-cells.ts_
|
|
|
|
[Example](https://raw.githubusercontent.com/dolanmiu/docx/master/demo/41-merge-table-cells-2.ts ':include')
|
|
|
|
_Source: https://github.com/dolanmiu/docx/blob/master/demo/41-merge-table-cells-2.ts_
|
|
|
|
### Merging columns
|
|
|
|
Example showing merging of `columns`
|
|
|
|
[Example](https://raw.githubusercontent.com/dolanmiu/docx/master/demo/43-images-to-table-cell-2.ts ':include')
|
|
|
|
_Source: https://github.com/dolanmiu/docx/blob/master/demo/43-images-to-table-cell-2.ts_
|
|
|
|
### Floating tables
|
|
|
|
[Example](https://raw.githubusercontent.com/dolanmiu/docx/master/demo/34-floating-tables.ts ':include')
|
|
|
|
_Source: https://github.com/dolanmiu/docx/blob/master/demo/34-floating-tables.ts_
|