Skip to content

Commit c537952

Browse files
100pah100pah
committed
(matrix): fix matrix doc.
1 parent 4f0e944 commit c537952

8 files changed

Lines changed: 526 additions & 141 deletions

File tree

‎en/option/component/matrix.md‎

Lines changed: 39 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,13 @@
22

33
# matrix(Object)
44

5+
{{ use: partial-version(version = "6.0.0") }}
6+
57
Matrix coordinate system component.
68

7-
Matrix coordinate system is similar to a table, mainly used to display the relationship and interaction of multi-dimensional data. It presents data in the form of a rectangular grid, where each grid unit (or "cell") represents the value of a specific data point. The entire layout is displayed in rows and columns to express the relationship of two-dimensional or higher-dimensional data.
9+
The `matrix` coordinate system, like a table, can serve as the layout system of data items in a series, mainly used to display the relationship and interaction of multi-dimensional data. It presents data in the form of a rectangular grid, where each grid unit (or "cell") represents the value of a specific data point in series like `series.heatmap`, `series.scatter`, `series.custom`, etc. The entire layout is displayed in rows and columns to express the relationship of two-dimensional or higher-dimensional data.
810

9-
Because it is a "coordinate system", it can be used in combination with multiple chart series, such as heat maps, scatter plots, custom series, etc.
11+
The `matrix` coordinate system can also serve as the layout system of the box of series like `series.pie`, `series.tree`, etc., or another coordinate systems like `grid` (i.e., Cartesian coordinate system), `geo`, `polar`, etc., or plain components like `legend`, `dataZoom`, etc. This character enables tiny charts to be laid out in a table, or enables the layout approach like [CSS grid layout](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_grid_layout). Currently all the series and components can be laid out within a matrix. `matrix` can also be used purely as table for data texts.
1012

1113
Correlation heat map using heat map in matrix coordinate system:
1214
~[800x400](${galleryViewPath}matrix-correlation-heatmap&edit=1&reset=1)
@@ -23,8 +25,15 @@ Correlation pie chart using pie chart in matrix coordinate system. The example b
2325
Confusion matrix using custom series in matrix coordinate system:
2426
~[800x400](${galleryViewPath}matrix-confusion&edit=1&reset=1)
2527

28+
Tiny line charts are laid out in a table:
29+
~[800x600](${galleryViewPath}matrix-cartesian-tiny&edit=1&reset=1)
30+
2631
By flexibly using the combination of chart series, coordinate systems, and APIs, richer effects can be achieved.
2732

33+
Reference:
34+
+ Cell locating and reference: see the description in [matrix.body.data](~matrix.body.data.coord)
35+
36+
2837
{{ use: partial-component-id(
2938
prefix = "#"
3039
) }}
@@ -37,6 +46,8 @@ By flexibly using the combination of chart series, coordinate systems, and APIs,
3746

3847
## x(Object)
3948

49+
{{ use: partial-version(version = "6.0.0") }}
50+
4051
X-axis header region.
4152

4253
{{ use: partial-matrix-header(
@@ -46,6 +57,8 @@ X-axis header region.
4657

4758
## y(Object)
4859

60+
{{ use: partial-version(version = "6.0.0") }}
61+
4962
Y-axis header region.
5063

5164
{{ use: partial-matrix-header(
@@ -55,24 +68,30 @@ Y-axis header region.
5568

5669
## body(Object)
5770

71+
{{ use: partial-version(version = "6.0.0") }}
72+
5873
Body cells, which are the ones except header cells.
5974

60-
{{ use: partial-matrix-region(
75+
{{ use: partial-matrix-body-corner-option(
6176
prefix = '##',
6277
name: 'Body cells'
6378
) }}
6479

6580
## corner(Object)
6681

82+
{{ use: partial-version(version = "6.0.0") }}
83+
6784
Corner cells, which are the one at the intersection of x and y-axis.
6885

69-
{{ use: partial-matrix-region(
86+
{{ use: partial-matrix-body-corner-option(
7087
prefix = '##',
7188
name: 'Corner cells'
7289
) }}
7390

7491
## backgroundStyle(Object)
7592

93+
{{ use: partial-version(version = "6.0.0") }}
94+
7695
The style of the entire matrix area.
7796

7897
{{ use: partial-item-style(
@@ -82,3 +101,19 @@ The style of the entire matrix area.
82101
defaultBorderColor = "'#ccc'",
83102
defaultBorderWidth = 1
84103
) }}
104+
105+
## borderZ2(number)
106+
107+
The secondary z-index of the outer border and the divider line.
108+
109+
## tooltip(Object)
110+
The tooltip for cells, follow the same option as [tooltip](~tooltip). Disabled by default. We can enable tooltip if the text is overflow a cell boundary and truncated.
111+
112+
```ts
113+
matrix: {
114+
tooltip: {
115+
show: true
116+
},
117+
// ...
118+
}
119+
```

‎en/option/partial/matrix-body-corner.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
{{ target: partial-matrix-body-corner-option }}
2+
3+
#${prefix|default('##')} data(Array)
4+
5+
{{ use: partial-version(version = "6.0.0") }}
6+
7+
Only specify some special cell definitions for ${name}.
8+
9+
```js
10+
data: [
11+
{
12+
coord: [[3, 5], [1, 2]], // Required to locate the cell.
13+
// See the rule below.
14+
value: 'some_text', // Optional. The text to display.
15+
mergeCells: true, // Optional. `false` by default.
16+
},
17+
{
18+
// ...
19+
},
20+
// ...
21+
]
22+
```
23+
24+
Cell locating and reference: see the description in [matrix.body.data](~matrix.body.data.coord)
25+
26+
27+
##${prefix|default('##')} coord(Array)
28+
29+
**Body/Corner Cell Locating**
30+
31+
The rule is uniformly applied, such as, in `matrix.dataToPoint` and `matrix.dataToLayout` and `xxxComponent.coord`.
32+
33+
Suppose the matrix.x/y dimensions (header) are defined as:
34+
```js
35+
matrix: {
36+
x: [{ value: 'Xa0', children: ['Xb0', 'Xb1'] }, 'Xa1'],
37+
y: [{ value: 'Ya0', children: ['Yb0', 'Yb1'] }],
38+
}
39+
```
40+
41+
```
42+
-----------------------------------------
43+
| | | Xa0 | |
44+
|-------+-------+---------------| Xa1 |
45+
|cornerQ|cornerP| Xb0 | Xb1 | |
46+
|-------+-------+-------+-------+--------
47+
| | Yb0 | bodyR | bodyS | |
48+
| Ya0 |-------+-------+---------------|
49+
| | Yb1 | | bodyT |
50+
|---------------|------------------------
51+
```
52+
+ `Locator number`:
53+
+ The term `locator` refers to a integer number to locate cells on x or y direction.
54+
+ Use the top-left cell of the body as the origin point `(0, 0)`,
55+
+ the non-negative locator indicates the right/bottom of the origin point;
56+
+ the negative locator indicates the left/top of the origin point.
57+
+ `Ordinal number` (`OrdinalNumber`):
58+
+ This term follows the same meaning as that in category axis of cartesian. They are non-negative integer, designating each string `matrix.x.data[i].value`/`matrix.y.data[i].value`. `'Xb0'`, `'Xb2'`, `'Xa1'`, `'Xa0'` are assigned with the ordinal numbers `0`, `1`, `2`, `3`. For every leaf dimension cell, `OrdinalNumber` and `MatrixXYLocator` is the same.
59+
+ A single cell or multiple cells can be determined/located by an array of `locator number` or `ordinal number` or the original `value` string as follows:
60+
- e.g., the body cell `bodyS` above can be located by:
61+
- `coord: [1, 0]` (Use non-negative integer)
62+
- `coord: ['Xb1', 'Yb0']` (Use the `value` properties in `matrix.x/y.data`)
63+
- `coord: ['Xb1', 0]` (mix them)
64+
- e.g., the corner cell `cornerQ` above can be located by:
65+
- `coord: [-2, -1]` (negative `MatrixXYLocator`)
66+
- But it is NOT supported to use `coord: ['Y1_0', 'X1_0']` (XY transposed form) here.
67+
- The dimension (header) cell can be located by negative integers. For example:
68+
- The center of the node `'Ya0'` can be located by `[-2, 'Ya0']`.
69+
- Cross cells: multiple cells can be located. e.g., if using `[['Xb0', 'Xb1'], ['Yb0']]`, or using a non-leaf dimension cell to locate, such as `['Xa0', 'Yb0']`, it returns only according to the center of the dimension cells, regardless of the body span. (therefore, the result can be on the boundary of two body cells.) And the ordinal number assigned to 'Xa0' is 3, thus input `[3, 'Yb0']` get the some result.
70+
- In a nutshell, **The formatter of `matrix.data.coord`** is as follows:
71+
- `[2, 8]` indicates a cell.
72+
- `[2, null/undefined/NaN]` means y is the entire column.
73+
- `[null/undefined/NaN, 8]` is the opposite.
74+
- `[[2, 5], 8]` indicates a rect of cells in x range of `2~5` and y `8`.
75+
- `[[2, 5], null/undefined/NaN]` indicates a x range of `2~5` and y is the entire column.
76+
- `[[2, 5], [7, 8]]` indicates a rect of cells in x range of `2~5` and y range of `7~8`.
77+
- `['aNonLeaf', 8]` indicates a rect of cells in x range of `aNonLeaf` and y `8`.
78+
- **NOTICE**
79+
- `bodyR` above is `[0, 0]`**.
80+
- The formatter of `matrix.data.coord` is `MatrixCoordRangeOption[]` as follows.
81+
82+
- The API `dataToPoint` and `dataToLayout` also uses this locating rule:
83+
- Input `['Xa1', 'Yb1']` to `dataToPoint` will get a point in the center of "bodyT".
84+
- Input `['Xa1', 'Yb1']` to `dataToLayout` will get a rect of the "bodyT".
85+
86+
87+
##${prefix|default('##')} mergeCells(boolean)
88+
89+
Body cells or corner cells can be merged.
90+
91+
##${prefix|default('##')} value(string|number)
92+
93+
Text to display in the cell.
94+
95+
96+
97+
{{ use: partial-matrix-cell-style-option(
98+
prefix='##',
99+
name=${name}
100+
) }}

‎en/option/partial/matrix-header.md‎

Lines changed: 68 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -2,56 +2,96 @@
22

33
### show(boolean) = true
44

5-
Determines whether to display the title row of the ${name}.
5+
{{ use: partial-version(version = "6.0.0") }}
66

7-
{{ use: partial-matrix-region(
8-
prefix = '##',
9-
name: ${name}
10-
) }}
11-
12-
### levelSize(number|string)
7+
Determines whether to display the header row(in `matrix.x`)/column(in `matrix.y`).
138

14-
The size of all cells in the title row/column. For the x title row, it refers to the cell height; for the y title column, it refers to the cell width.
159

16-
The value type can be:
10+
### data(Array)
1711

18-
+ `number`: Represents pixel value.
19-
+ `string`: Percentage value (e.g., `'33%'`), representing the percentage relative to the width or height of the matrix.
20-
+ Unspecified: The width or height is evenly distributed.
12+
{{ use: partial-version(version = "6.0.0") }}
2113

22-
For example:
14+
Specifies the data for the ${name}. i.e., defined the column/row.
2315

2416
```js
25-
{
26-
x: {
27-
levelSize: undefined,
28-
levels: [undefined, {levelSize: '10%'}]
29-
}
30-
}
17+
// Data for a single row
18+
data: ['A', 'B', 'C', 'D', 'E']
19+
20+
// Or if column/row names is not of concern, simply
21+
data: Array(5).fill(null) // Five columns or rows
22+
23+
// Data in a tree structure
24+
data: [{
25+
value: 'A',
26+
children: [
27+
{
28+
value: 'A1',
29+
children: [
30+
{value: 'A1-1'},
31+
{value: 'A1-2'}
32+
]
33+
},
34+
{value: 'A2'}
35+
]
36+
}, {
37+
value: 'B',
38+
children: [
39+
{value: 'B1'},
40+
{value: 'B2'}
41+
]
42+
}]
3143
```
3244

33-
In the above example, the width of the second column title is 10% of the entire chart width, and other title columns use the maximum value of each column title content as the width.
45+
{{ use: partial-matrix-cell-style-option(
46+
prefix='##',
47+
name=${name}
48+
) }}
49+
50+
{{ use: partial-matrix-dimension-level-option(
51+
prefix='##',
52+
name=${name}
53+
) }}
54+
3455

3556
### levels(Array)
3657

37-
Settings for each row/column of the title row/column. The first element represents the first row/column, and so on. If an item in the array is empty, it means using the default value.
58+
{{ use: partial-version(version = "6.0.0") }}
59+
60+
Settings for each column(in `matrix.x`) or row(in `matrix.y`). The first element represents the first column/row, and so on.
3861

39-
#### levelSize(number|string)
62+
- If any item in the array is `null`/`undefined`, it means using the default value.
63+
- Otherwise any item in the array should be an object, such as `{levelSize: number}`.
4064

41-
The size of cells in a specific row/column of the title row. For the x title row, it refers to the cell height; for the y title column, it refers to the cell width.
65+
For example
66+
```js
67+
matrix: {
68+
x: {
69+
level: [null, {levelSize: '20%'}]
70+
// The second column width should be 20% of
71+
// the matrix width.
72+
// The first column has no specific setting.
73+
},
74+
// ...
75+
},
76+
```
4277

43-
The value type can be:
78+
{{ use: partial-matrix-dimension-level-option(
79+
prefix = '###',
80+
name = ${name}
81+
) }}
4482

45-
+ `number`: Represents pixel value.
46-
+ `string`: Percentage value (e.g., `'33%'`), representing the percentage relative to the width or height of the entire chart container.
47-
+ Unspecified: Represents the minimum value that adapts to the content.
4883

4984
### dividerLineStyle(Object)
5085

86+
{{ use: partial-version(version = "6.0.0") }}
87+
88+
Header divider line style.
89+
5190
{{ use: partial-line-style(
5291
prefix = '###',
5392
defaultColor = "'#aaa'",
5493
defaultWidth = 1,
5594
defaultType = "'solid'",
56-
name = "title column divider line"
95+
name = "header divider"
5796
) }}
97+

0 commit comments

Comments
 (0)