Skip to content

Commit b05dede

Browse files
eidng8eidng8
committed
update documentation
1 parent 863c044 commit b05dede

File tree

3 files changed

+73
-48
lines changed

3 files changed

+73
-48
lines changed

‎README.md

+69-45
Original file line numberDiff line numberDiff line change
@@ -13,79 +13,103 @@ The DOM structure of this component doesn't change once rendered. Comparing to o
1313

1414
There is an [issue](https://github.com/eidng8/vue-tree/issues/24) for this. Check out more detail there.
1515

16-
## Theming
16+
## Props
1717

18-
The bundled style sheet can be imported from `'g8-vue-tree/dist/g8-vue-tree.css'`. This component provides a dark theme out of box. To use it, just add the `g8-tree__dark` class to the element.
18+
| Prop name | Description | Type | Default |
19+
| --- | --- | :-: | :-: |
20+
| item-id | Key of the field in `item` to be used as element's `id` attribute. | string | 'id' |
21+
| item-label | Key of the field in `item` that holds node label. | string | 'name' |
22+
| tags-key | Key of the field in `item` that holds tags array. | string | 'tags' |
23+
| children-key | Key of the field in `item` that holds child nodes array. | string | 'children' |
24+
| tag-id | Key of the field in tags list of `item` to be used as tag element's `id` attribute. | string | 'id' |
25+
| tag-label | Key of the field in tags list of `item` that holds tag label. | string | 'label' |
26+
| tag-hint | Key of the field in tags list of `item` that holds tag tooltip. | string | 'hint' |
27+
| checker | Whether to add a checkbox before each item,<br>allowing multiple nodes tobe checked. | boolean | false |
28+
| item | The tree data to be rendered.<br>Please note that data passed **_may_** be mutated by this<br>component to reflect various states of tree nodes.<br>Mutated fields include:<br>- checked<br>- intermediate<br>- rendered | [G8TreeItem](#g8treeitem) | |
1929

20-
```html
21-
<ul class="g8-tree-view g8-tree__dark">
22-
<g8-tree-view></g8-tree-view>
23-
</ul>
24-
```
30+
## Scoped slots
2531

26-
If you want to change the color of the component, just define two variables before importing the scss file.
32+
#### Default slot
2733

28-
```scss
29-
/* index.scss */
34+
```vue
35+
<span class="g8-tree__node_entry_label">
36+
<slot :item="item">{{ item[itemLabel] }}</slot>
37+
</span>
38+
```
3039

31-
/* define these two variables before importing the scss file */
32-
$g8-tree-bg: #ccc;
33-
$g8-tree-fg: #333;
40+
This is the entry's main content slot. Defaults to `{{ item[itemLabel] }}`. The current item entry is exposed as scoped variable `item`.
3441

35-
@import '~vue-tree/src/components/tree-view.scss';
36-
```
42+
#### Tag slot
3743

38-
## Props
44+
```vue
45+
<label
46+
class="g8-tree__node_entry_tags_tag"
47+
v-for="(tag, idx) in item[tagsKey]"
48+
:key="idx"
49+
:id="tag[tagId]"
50+
:title="tag[tagHint]"
51+
>
52+
<slot name="tag" :tag="tag" :item="item">{{ tag[tagLabel] }}</slot>
53+
</label>
54+
```
3955

40-
| Prop name | Description | Type | Default |
41-
| --- | --- | :-: | :-: |
42-
| itemLabel | Key of the field in `item` that holds node label. | string | 'name' |
43-
| tagsKey | Key of the field in `item` that holds tags array. | string | 'tags' |
44-
| childrenKey | Key of the field in `item` that holds child nodes array. | string | 'children' |
45-
| tagLabel | Key of the field in tags list of `item` that holds tag label. | string | 'label' |
46-
| tagHint | Key of the field in tags list of `item` that holds tag tooltip. | string | 'hint' |
47-
| handleRightClick <a id="handleRightClick"></a> | Whether to intercept right mouse click. | boolean | false |
48-
| checker | Whether to add a checkbox before each item,<br>allowing multiple nodes tobe checked. | boolean | false |
49-
| item | The tree data to be rendered.<br>Please note that data passed **_may_** be mutated by this<br>component to reflect various states of tree nodes.<br>Mutated fields include:<br>- checked<br>- intermediate<br>- rendered | [G8TreeItem](#G8TreeItem) | |
56+
This is the entry's tag content slot. Defaults to `{{ tag[tagLabel] }}`. The current item entry is exposed as scoped variable `item`. The current tag is exposed as scoped variable `tag`.
5057

5158
## Events
5259

5360
| Event name | Type | Description |
5461
| --- | :-: | --- |
55-
| click | [G8TreeItem](#G8TreeItem) | A tree node has been clicked. |
56-
| middle-click | [G8TreeItem](#G8TreeItem) | A tree node has been clicked with middle mouse button. |
57-
| right-click | [G8TreeItem](#G8TreeItem) | A tree node has been clicked with right mouse button.<br>Only available if [handleRightClick](#handleRightClick) is `true` |
58-
| dblclick | [G8TreeItem](#G8TreeItem) | A tree node has been double clicked. |
59-
| tag-click | [G8TagClickEvent](#G8TagClickEvent) | A tree node tag has been clicked. |
60-
| tag-middle-click | [G8TagClickEvent](#G8TagClickEvent) | A tree node tag has been clicked. |
61-
| tag-right-click | [G8TagClickEvent](#G8TagClickEvent) | A tree node has been clicked with right mouse button.<br>Only available if [handleRightClick](#handleRightClick) is `true` |
62-
| tag-dblclick | [G8TagClickEvent](#G8TagClickEvent) | A tree node tag has been double clicked. |
63-
| state-changed | [G8TreeItem](#G8TreeItem) | Checkbox state of the node has changed. |
62+
| click | [G8TreeItem](#g8treeitem) | A tree node has been clicked. |
63+
| state-changed | [G8TreeItem](#g8treeitem) | Checkbox state of the node has changed. |
6464

6565
## Types
6666

6767
#### G8TreeItem
6868

69+
Below is a list of presumable fields, all of them are optional. You can place whatever data you want to a tree item, then use the [props](#props) mentioned above to specify content you want to display.
70+
6971
| Field name | Type | Description |
7072
| --- | :-: | --- |
7173
| name | string | Item name, serves as label, will be rendered as node label. |
72-
| checked | boolean | Whether current node is checked. |
73-
| intermediate | boolean | Intermediate check box state. Active while some of the children were checked, but not all. |
74+
| checked | boolean | Whether the node is checked. |
75+
| intermediate | boolean | Intermediate check box state. Active while some children were checked. |
7476
| rendered | boolean | Whether the sub-tree of this node has been rendered. |
75-
| tags | [G8TreeItemTag](#G8TreeItemTag)\[] | List of tags. |
76-
| children | [G8TreeItem](#G8TreeItem)\[] | List of child nodes. |
77+
| tags | [G8TreeItemTag](#g8treeitemtag)\[] | List of tags. |
78+
| children | [G8TreeItem](#g8treeitem)\[] | List of child nodes. |
7779

7880
#### G8TreeItemTag
7981

82+
Below is a list of presumable fields, all of them are optional. You can place whatever data you want to tags, then use the [props](#props) mentioned above to specify content you want to display.
83+
8084
| Field name | Type | Description |
8185
| ---------- | :----: | -------------------------------------------------- |
8286
| label | string | Tag label. |
8387
| hint | string | Tag tooltip. Visible when mouse hovers on the tag. |
8488

85-
#### G8TagClickEvent
89+
#### G8ClickEvent extends `MouseEvent`
8690

87-
| Field name | Type | Description |
88-
| --- | :-: | --- |
89-
| node | [G8TreeItem](#G8TreeItem) | Key of the node that triggered the event. |
90-
| tag | [G8TreeItemTag](#G8TreeItemTag) | The tag that triggered the event. |
91-
| index | number | Numeric index of the entry in the tag list. |
91+
| Field name | Type | Description |
92+
| ---------- | :-----------------------: | ----------------------------- |
93+
| data | [G8TreeItem](#g8treeitem) | The item triggered the event. |
94+
95+
## Theming
96+
97+
The bundled style sheet can be imported from `'g8-vue-tree/dist/g8-vue-tree.css'`. This component provides a dark theme out of box. To use it, just add the `g8-tree__dark` class to the element.
98+
99+
```html
100+
<ul class="g8-tree-view g8-tree__dark">
101+
<g8-tree-view></g8-tree-view>
102+
</ul>
103+
```
104+
105+
If you want to change the color of the component, just define two variables before importing the scss file.
106+
107+
```scss
108+
/* index.scss */
109+
110+
/* define these two variables before importing the scss file */
111+
$g8-tree-bg: #ccc;
112+
$g8-tree-fg: #333;
113+
114+
@import '~vue-tree/src/components/tree-view.scss';
115+
```

‎src/components/G8TreeView.vue

+3-2
Original file line numberDiff line numberDiff line change
@@ -84,7 +84,7 @@ import { G8ClickEvent, G8TreeItem } from './types';
8484
@Component({ name: 'g8-tree-view' })
8585
export default class G8TreeView extends Vue {
8686
/**
87-
* Key of the field in `item` that holds node label.
87+
* Key of the field in `item` to be used as element's `id` attribute.
8888
*/
8989
@Prop({ default: 'id' }) itemId!: string;
9090

@@ -104,7 +104,8 @@ export default class G8TreeView extends Vue {
104104
@Prop({ default: 'children' }) childrenKey!: string;
105105

106106
/**
107-
* Key of the field in tags list of `item` that holds tag label.
107+
* Key of the field in tags list of `item` to be used as tag element's `id`
108+
* attribute.
108109
*/
109110
@Prop({ default: 'id' }) tagId!: string;
110111

‎src/components/types.ts

+1-1
Original file line numberDiff line numberDiff line change
@@ -66,5 +66,5 @@ export interface G8TreeItemTag {
6666
}
6767

6868
export class G8ClickEvent extends MouseEvent {
69-
data?: unknown;
69+
data?: G8TreeItem;
7070
}

0 commit comments

Comments
 (0)