400 lines
10 KiB
Markdown
400 lines
10 KiB
Markdown
# Tables
|
|
|
|
!> Paragraphs requires an understanding of [Sections](usage/sections.md).
|
|
|
|
## Intro
|
|
|
|
- `Tables` contain a list of `Rows`
|
|
- `Rows` contain a list of `TableCells`
|
|
- `TableCells` contain a list of `Parahraphs` and/or `Tables`. You can add `Tables` as tables can be nested inside each other
|
|
|
|
Create a simple table like so:
|
|
|
|
```ts
|
|
const table = new Table({
|
|
rows: [Array of `TableRow`s]
|
|
});
|
|
```
|
|
|
|
Then add the table in the `section`
|
|
|
|
```ts
|
|
const doc = new Document({
|
|
sections: [{
|
|
children: [table],
|
|
}];
|
|
});
|
|
```
|
|
|
|
## Table
|
|
|
|
### Set Width
|
|
|
|
```ts
|
|
const table = new Table({
|
|
...,
|
|
width: {
|
|
size: [TABLE_WIDTH],
|
|
type: WidthType,
|
|
}
|
|
});
|
|
```
|
|
|
|
For example:
|
|
|
|
```ts
|
|
|
|
const table = new Table({
|
|
...,
|
|
width: {
|
|
size: 4535,
|
|
type: WidthType.DXA,
|
|
}
|
|
});
|
|
```
|
|
|
|
## 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 | `{ height: number, rule: HeightRule }` | Optional |
|
|
|
|
### Repeat row
|
|
|
|
If a table is paginated on multiple pages, it is possible to repeat a row at the top of each new page by setting `tableHeader` to `true`:
|
|
|
|
```ts
|
|
const row = new TableRow({
|
|
...,
|
|
tableHeader: true,
|
|
});
|
|
```
|
|
|
|
### Pagination
|
|
|
|
#### Prevent row pagination
|
|
|
|
To prevent breaking contents of a row across multiple pages, call `cantSplit`:
|
|
|
|
```ts
|
|
const row = new Row({
|
|
...,
|
|
cantSplit: true,
|
|
});
|
|
```
|
|
|
|
## Table 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")],
|
|
}),
|
|
],
|
|
});
|
|
```
|
|
|
|
### Options
|
|
|
|
| Property | Type | Notes |
|
|
| ------------- | ----------------------------------- | ----------------------------------------------------------- |
|
|
| children | `Array<Paragraph or Table>` | Required. You can nest tables by adding a table into a cell |
|
|
| shading | `ITableShadingAttributesProperties` | Optional |
|
|
| margins | `ITableCellMarginOptions` | Optional |
|
|
| verticalAlign | `VerticalAlign` | Optional |
|
|
| columnSpan | `number` | Optional |
|
|
| rowSpan | `number` | Optional |
|
|
| borders | `BorderOptions` | Optional |
|
|
| width | `{ size: number type: WidthType }` | Optional |
|
|
|
|
#### Border Options
|
|
|
|
| Property | Type | Notes |
|
|
| -------- | ----------------------------------------------------- | -------- |
|
|
| top | `{ style: BorderStyle, size: number, color: string }` | Optional |
|
|
| bottom | `{ style: BorderStyle, size: number, color: string }` | Optional |
|
|
| left | `{ style: BorderStyle, size: number, color: string }` | Optional |
|
|
| right | `{ style: BorderStyle, size: number, color: string }` | Optional |
|
|
|
|
##### Example
|
|
|
|
```ts
|
|
const cell = new TableCell({
|
|
...,
|
|
borders: {
|
|
top: {
|
|
style: BorderStyle.DASH_DOT_STROKED,
|
|
size: 1,
|
|
color: "red",
|
|
},
|
|
bottom: {
|
|
style: BorderStyle.THICK_THIN_MEDIUM_GAP,
|
|
size: 5,
|
|
color: "889900",
|
|
},
|
|
},
|
|
});
|
|
```
|
|
|
|
##### 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
|
|
const cell = new TableCell({
|
|
...,
|
|
borders: {
|
|
top: {
|
|
style: BorderStyle.DOT_DOT_DASH,
|
|
size: 3,
|
|
color: "green",
|
|
},
|
|
bottom: {
|
|
style: BorderStyle.DOT_DOT_DASH,
|
|
size: 3,
|
|
color: "ff8000",
|
|
},
|
|
},
|
|
});
|
|
```
|
|
|
|
### Add paragraph to a cell
|
|
|
|
Once you have got the cell, you can add data to it:
|
|
|
|
```ts
|
|
const cell = new TableCell({
|
|
children: [new Paragraph("Hello")],
|
|
});
|
|
```
|
|
|
|
### Set width of a cell
|
|
|
|
You can specify the width of a cell using:
|
|
|
|
```ts
|
|
const cell = new TableCell({
|
|
...,
|
|
width: {
|
|
size: number,
|
|
type: WidthType,
|
|
},
|
|
});
|
|
```
|
|
|
|
`WidthType` values can be:
|
|
|
|
| Property | Notes |
|
|
| -------- | --------------------------------- |
|
|
| AUTO | |
|
|
| DXA | value is in twentieths of a point |
|
|
| NIL | is considered as zero |
|
|
| PCT | percent of table width |
|
|
|
|
#### Example
|
|
|
|
```ts
|
|
cell.Properties.setWidth(100, WidthType.DXA);
|
|
```
|
|
|
|
### Nested Tables
|
|
|
|
To have a table within a table, simply add it in the `children` block of a `table cell`:
|
|
|
|
```ts
|
|
const cell = new TableCell({
|
|
children: [new Table(...)],
|
|
});
|
|
```
|
|
|
|
### Vertical Align
|
|
|
|
Sets the vertical alignment of the contents of the cell
|
|
|
|
```ts
|
|
const cell = new TableCell({
|
|
...,
|
|
verticalAlign: VerticalAlign,
|
|
});
|
|
```
|
|
|
|
`VerticalAlign` values can be:
|
|
|
|
| Property | Notes |
|
|
| -------- | ------------------------------------------ |
|
|
| BOTTOM | Align the contents on the bottom |
|
|
| CENTER | Align the contents on the center |
|
|
| TOP | Align the contents on the top. The default |
|
|
|
|
For example, to center align a cell:
|
|
|
|
```ts
|
|
const cell = new TableCell({
|
|
verticalAlign: VerticalAlign.CENTER,
|
|
});
|
|
```
|
|
|
|
## Merging cells together
|
|
|
|
### Row Merge
|
|
|
|
When cell rows are merged, it counts as multiple rows, so be sure to remove excess cells. It is similar to how HTML's `rowspan` works.
|
|
https://www.w3schools.com/tags/att_td_rowspan.asp
|
|
|
|
```ts
|
|
const cell = new TableCell({
|
|
...,
|
|
rowSpan: [NUMBER_OF_CELLS_TO_MERGE],
|
|
});
|
|
```
|
|
|
|
#### Example
|
|
|
|
The example will merge three rows together.
|
|
|
|
```ts
|
|
const cell = new TableCell({
|
|
...,
|
|
rowSpan: 3,
|
|
});
|
|
```
|
|
|
|
### Column Merge
|
|
|
|
When cell columns are merged, it counts as multiple columns, so be sure to remove excess cells. It is similar to how HTML's `colspan` works.
|
|
https://www.w3schools.com/tags/att_td_colspan.asp
|
|
|
|
```ts
|
|
const cell = new TableCell({
|
|
...,
|
|
columnSpan: [NUMBER_OF_CELLS_TO_MERGE],
|
|
});
|
|
```
|
|
|
|
#### Example
|
|
|
|
The example will merge three columns together.
|
|
|
|
```ts
|
|
const cell = new TableCell({
|
|
...,
|
|
columnSpan: 3,
|
|
});
|
|
```
|
|
|
|
### Visual Right to Left Table
|
|
|
|
It is possible to reverse how the cells of the table are displayed. The table direction. More info here: https://superuser.com/questions/996912/how-to-change-a-table-direction-in-microsoft-word
|
|
|
|
```ts
|
|
const table = new Table({
|
|
visuallyRightToLeft: true,
|
|
});
|
|
```
|
|
|
|
## 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_
|
|
|
|
### Shading
|
|
|
|
Example showing merging of columns and rows and shading
|
|
|
|
[Example](https://raw.githubusercontent.com/dolanmiu/docx/master/demo/32-merge-and-shade-table-cells.ts ':include')
|
|
|
|
_Source: https://github.com/dolanmiu/docx/blob/master/demo/32-merge-and-shade-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 and rows
|
|
|
|
[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_
|