Skip to content

Commit 31e69f0

Browse files
PeachScriptPeachScript
committed
docs: add en and zh api page
1 parent 65010dd commit 31e69f0

File tree

2 files changed

+226
-0
lines changed

2 files changed

+226
-0
lines changed

‎docs/api/README.md

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
---
2+
sidebar: auto
3+
---
4+
5+
# API
6+
7+
## Props
8+
9+
The default value for these properties can be overridden through the Plugin API.
10+
11+
### distance
12+
13+
- Type: `Number`
14+
- Default: `100`
15+
- Details:
16+
17+
The `infinite` event will be fired if the scroll distance is less than this value. If `direction` is set to `top`, it will calculate the distance between the scroll bar and the top, if `direction` is set to `bottom`, it will calculate the distance between the scroll bar and the bottom.
18+
19+
### spinner
20+
21+
- Type: `String`
22+
- Default: `default`
23+
- Available: `default` | `spiral` | `circles` | `bubbles` | `waveDots`
24+
- Details:
25+
26+
This property is used to set the loading animation, you can choose one from the internal spinners that you like, you can also customize it with a [named slot](https://vuejs.org/v2/guide/components.html#Named-Slots) that called `spinner`.
27+
28+
### direction
29+
30+
- Type: `String`
31+
- Default: `bottom`
32+
- Available: `top` | `bottom`
33+
- Details:
34+
35+
This property is used to set the load direction.
36+
37+
### forceUseInfiniteWrapper
38+
39+
- Type: `Boolean` | `String`
40+
- Default: `false`
41+
- Details:
42+
43+
By default, the component will search for the closest parent element which has `overflow-y: auto | scroll` CSS style as the scroll container, this property is used to force to specify the scroll container, usually used when the case has complex layout or 3rd-party scroll plugin (eg: [`perfect-scrollbar`](https://github.com/noraesae/perfect-scrollbar)).
44+
45+
If this value set be `true`, the component will search the closest parent element which has `infinite-wrapper` attribute as the scroll container, if this value is a string, the component will use it as a CSS selector, and search the element as the scroll container via the `querySelector` API, if all failed, the component will use `window` as the scroll container.
46+
47+
### identifier
48+
49+
- Type: `any`
50+
- Default: `+new Date()`
51+
- Details:
52+
53+
The comopnent will be reset if this property has changed, just like recreating a new comopnent, usually used when the case has filter or tabs.
54+
55+
## Slots
56+
57+
The contents for these slots can be configured via the [`slot` special attribute](https://vuejs.org/v2/api/index.html#slot), also can be configure via the plugin API.
58+
59+
### no-results
60+
61+
- Default: `No results :(`
62+
- Details:
63+
64+
This message will be displayed if there is no data, it means we did not call the `$state.loaded` method before calling the `$stat.complete` method.
65+
66+
### no-more
67+
68+
- Default: `No more data :)`
69+
- Details:
70+
71+
This message will be displayed if there is no more data, it means we called the `$state.loaded` method before calling the `$state.complete` method.
72+
73+
### error
74+
75+
- Default: `Opps, something went wrong :(`
76+
- Details:
77+
78+
This message will be displayed if loading failed, it means we called the `$state.error` method.
79+
80+
Unlike other slots, the default value for this slot will provide a retry button for users to load data again. If you want to impletement a retry button for users when you customize this slot, you can use the [`slot-scope`](https://vuejs.org/v2/api/index.html#slot-scope) feature, like this:
81+
82+
``` html
83+
<infinite-loading @infinite="infiniteHandler">
84+
<div slot="error" slot-scope="{ trigger }">
85+
Network error, click <a href="javascript:;" @click="trigger">here</a> to retry
86+
</div>
87+
</infinite-loading>
88+
```
89+
90+
## Events
91+
92+
### infinite
93+
94+
- Argument: `event`
95+
- Details:
96+
97+
This event will be fired if the scroll distance is less than the `distance` property, the component will pass a special event argument for the event handler to change loading status, usually we name it `$state`, include these methods:
98+
99+
#### $state.loaded
100+
101+
Inform the component that this loading has been successful, and the `infinite` event will be fired again if the first screen was not be filled up, otherwise, the component will hide the loading animation and continue to listen scroll event.
102+
103+
#### $state.complete
104+
105+
Inform the component that all the data has been loaded successfully, if the `$state.loaded` method has not been called before this, the content of `no-results` slot will be displayed, otherwise, the content of `no-more` slot will be displayed.
106+
107+
#### $state.error
108+
109+
Inform the comopnent that this loading failed, the content of `error` slot will be diplayed.
110+
111+
#### $state.reset
112+
113+
Reset the component, same as changing the `identifier` property.

‎docs/zh/api/README.md

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
---
2+
sidebar: auto
3+
---
4+
5+
# API
6+
7+
## 属性
8+
9+
所有属性都可以通过插件 API 改写全局默认值。
10+
11+
### distance
12+
13+
- 类型：`Number`
14+
- 默认值：`100`
15+
- 详细：
16+
17+
当滚动条的距离小于此值时，`infinite` 事件将会被触发。如果 `direction` 的值是 `top`，则计算滚动条距离顶部的距离；如果 `direction` 的值是 `bottom`，则计算滚动条距离底部的距离。
18+
19+
### spinner
20+
21+
- 类型：`String`
22+
- 默认值：`default`
23+
- 有效值：`default` | `spiral` | `circles` | `bubbles` | `waveDots`
24+
- 详细：
25+
26+
此选项用于设置加载动画，你可以从内置选项中选择一个你喜欢的，你也可以通过名为 `spinner` 的[具名插槽](https://vuejs.org/v2/guide/components.html#Named-Slots)来进行自定义。
27+
28+
### direction
29+
30+
- 类型：`String`
31+
- 默认值：`bottom`
32+
- 有效值：`top` | `bottom`
33+
- 详细：
34+
35+
此选项用于设置滚动加载的方向。
36+
37+
### forceUseInfiniteWrapper
38+
39+
- 类型：`Boolean` | `String`
40+
- 默认值：`false`
41+
- 详细：
42+
43+
默认情况下，该组件会寻找最近的具备 `overflow-y: auto | scroll` CSS 样式的父元素，作为监听滚动事件的目标元素，此选项用于强制指定滚动元素，通常用于有复杂布局或第三方滚动组件（例如 [`perfect-scrollbar`](https://github.com/noraesae/perfect-scrollbar)）的场景。
44+
45+
如果该值为 `true`，则会向上查找最近的具备 `infinite-wrapper` 属性的父元素作为滚动容器；如果该值为一个字符串，则会将该值当作 CSS 选择器并使用 `querySelector` 查找该元素，将其作为滚动容器；如果以上两种情况都找不到目标元素，则会使用 `window` 作为滚动容器。
46+
47+
### identifier
48+
49+
- 类型：`any`
50+
- 默认值：`+new Date()`
51+
- 详细：
52+
53+
该组件会在此值改变时对组件进行重设，就像重新创建了一个新的组件一样，通常用于过滤器或者选项卡的场景。
54+
55+
## 插槽
56+
57+
插槽的内容可以通过 `Vue.js` 官方提供的 [`slot` 特殊属性](https://vuejs.org/v2/api/index.html#slot)进行设置，也可以通过插件 API 进行全局设置。
58+
59+
### no-results
60+
61+
- 默认值：`No results :(`
62+
- 详细：
63+
64+
该信息将会在没有加载到任何数据时呈现给用户，即没有调用过 `$state.loaded` 方法就调用了 `$state.complete` 方法。
65+
66+
### no-more
67+
68+
- 默认值：`No more data :)`
69+
- 详细：
70+
71+
该信息将会在所有数据都已经加载完时呈现给用户，即调用过 `$state.loaded` 方法之后调用了 `$state.complete` 方法。
72+
73+
### error
74+
75+
- 默认值：`Opps, something went wrong :(`
76+
- 详细：
77+
78+
该信息将会在加载出现错误时呈现给用户，即调用 `$state.error` 方法时。
79+
80+
与其他插槽不同的是，该插槽的默认值除了会提供文字信息之外，还会提供一个重试按钮供用户重新尝试加载；在自定义该插槽时，如果你也希望提供一个重试按钮给用户，可以使用 [`slot-scope`](https://vuejs.org/v2/api/index.html#slot-scope) 功能实现，就像下面这样：
81+
82+
``` html
83+
<infinite-loading @infinite="infiniteHandler">
84+
<div slot="error" slot-scope="{ trigger }">
85+
Network error, click <a href="javascript:;" @click="trigger">here</a> to retry
86+
</div>
87+
</infinite-loading>
88+
```
89+
90+
## 事件
91+
92+
### infinite
93+
94+
- 参数：`event`
95+
- 详细：
96+
97+
该事件将会在滚动距离小于 `distance` 属性时被触发，组件会传递一个特殊的事件参数给事件监听器，用于改变组件的加载状态，通常我们将其命名为 `$state`，它包含以下几个方法：
98+
99+
#### $state.loaded
100+
101+
通知组件此次加载已经顺利完成，如果此时数据仍然没有填满首屏，`infinite` 事件将会被再次触发；反之，组件将会关闭加载动画并继续监听滚动事件。
102+
103+
#### $state.complete
104+
105+
通知组件所有的数据已经加载完成，如果调用此方法前没有调用过 `$state.loaded`，那么插槽 `no-results` 的内容将会被展示；如果调用此方法前调用过 `$state.loaded`，那么插槽 `no-more` 的内容将会被展示。
106+
107+
#### $state.error
108+
109+
通知组件此次加载失败了，插槽 `error` 的内容将会被展示。
110+
111+
#### $state.reset
112+
113+
重设组件状态，等同于改变 `identifier` 属性。

0 commit comments

Comments
 (0)