docs: improve docs and update api

This commit is contained in:
Justineo 2021-11-24 12:05:27 +08:00
parent a790f0d8a9
commit 5226ec968c
No known key found for this signature in database
GPG Key ID: B73F0979CF18A0EA
19 changed files with 297 additions and 114 deletions

View File

@ -31,8 +31,8 @@
| ``items`` | `Array<{value, label, children}>` | `[]` | [^items] |
| ``sticky`` | `boolean=` | `false` | 是否有吸附效果。 |
| ``container`` | `string | HTMLElement | Window=` | - | `Anchor` 吸附与判断锚点激活所参考的容器。 |
| ``target-offset`` | `string | number=` | `0` | 当某个锚点处于到容器的 `target-offset` 位置,那么对应的锚点链接处于激活状态。 |
| ``sticky-offset`` | `string | number=` | `0` | 对于 sticky `Anchor` 而言,当容器滚动到 `sticky-offset` 位置,那么该 `Anchor` 开始吸附。 |
| ``target-offset`` | `string | number=` | `0` | 当某个锚点处于到容器的 `target-offset` 位置,那么对应的锚点链接处于激活状态。数值类型值为 `px` 值,也可以传入如 `'10%'` 的百分比字符串,将基于 `container` 对应容器的高度比例进行计算。 |
| ``sticky-offset`` | `string | number=` | `0` | 对于 sticky `Anchor` 而言,当容器滚动到 `sticky-offset` 位置,那么该 `Anchor` 开始吸附。不同值类型含义同 [`target-offset`](#props-target-offset) 属性。 |
^^^items
数据源数组,每个项目类型为 `{label, value, children, ...}`

View File

@ -32,17 +32,21 @@
| -- | -- | -- | -- |
| ``datasource`` | `Array<string | Object>=` | `[]` | [^datasource] |
| ``value`` | `*` | - | [^prop-value] |
| ``match`` | `(item, keyword, { ancestors }) => boolean | [number, number] | Array<[number, number]>` | - | 支持自定义高亮逻辑,默认进行大小写不敏感的子串匹配。 |
| ``filter`` | `(item, keyword, { ancestors, offsets }) => boolean` | - | 支持自定义搜索命中逻辑。 |
| ``strict`` | `boolean=` | `false` | 建议下拉面板关闭时,若输入值没有完全匹配建议值,那么会清空输入值。 |
| ``suggest-trigger`` | `string | Array<string>=` | `'input'` | 触发建议下拉面板的时机,可用值有:`'input'`、`'focus'`。 |
| ``placeholder`` | `string=` | | 输入占位符。 |
| ``select-on-focus`` | `boolean=` | `false` | 聚焦时是否自动选中输入框文本。 |
| ``composition`` | `boolean=` | `false` | 是否感知输入法输入过程的值。 |
| ``expanded`` | `boolean=` | `false` | [^expanded] |
| ``clearable`` | `boolean=` | `false` | 是否显示清除按钮。 |
| ``disabled`` | `boolean=` | `false` | 是否为禁用状态。 |
| ``readonly`` | `boolean=` | `false` | 是否为只读状态。 |
| ``match`` | `(item, keyword, { ancestors }) => boolean | [number, number] | Array<[number, number]>` | - | 支持自定义高亮逻辑,默认进行大小写不敏感的子串匹配。 |
| ``filter`` | `(item, keyword, { ancestors, offsets }) => boolean` | - | 支持自定义搜索命中逻辑。 |
| ``suggest-trigger`` | `string | Array<string>=` | `'input'` | 触发建议下拉面板的时机,可用值有:`'input'`、`'focus'`。 |
| ``expanded`` | `boolean=` | `false` | [^expanded] |
| ``placeholder`` | `string=` | - | 输入占位符。 |
| ``clearable`` | `boolean=` | `false` | 是否显示清除按钮。 |
| ``composition`` | `boolean=` | `false` | 是否感知输入法输入过程的值。 |
| ``select-on-focus`` | `boolean=` | `false` | 聚焦时是否自动选中输入框文本。 |
| ``maxlength`` | `number=` | - | 输入字符串的长度限制。 |
| ``strict`` | `boolean=` | `false` | 输入字符串到达长度限制以后是否禁止继续输入。 |
| ``get-length`` | `function(string): number=` | 自定义的字符长度计算函数。 |
| ``trim`` | `boolean | string=` | `false` | [^trim] |
| ``autofocus`` | `boolean=` | `false` | 是否自动获取焦点。 |
^^^datasource
数据源数组,项目为 `Object` 时字段为 `{label, value, children, ...}`
@ -72,6 +76,18 @@
建议面板是否展开(如果 `suggestions` 中没有待选项,则即使为 `true` 时面板也会关闭)。
^^^
^^^trim
是否移除前后空格。当为 `true` 时,会移除前后空格,当为 `false` 时,不移除前后空格。设置为字符串时,按指定方式进行移除。
+++枚举值
| 值 | 描述 |
| -- | -- |
| `both` | 移除两端空格。等同于 `true` 时的行为。 |
| `start` | 移除开始空格。 |
| `end` | 移除末尾空格。 |
+++
^^^
### 插槽
| 名称 | 描述 |
@ -109,7 +125,7 @@
| 名称 | 描述 |
| -- | -- |
| ``input`` | [^event-input] |
| ``suggest`` | 采纳建议时触发,参数是当前值。 |
| ``select`` | 采纳建议时触发,参数是当前值。 |
| ``toggle`` | 提示面板展开状态切换时触发,回调参数为 `(expanded: boolean)`。`expanded` 表示操作将触发提示面板展开还是收起。 |
| ``clear`` | 清除当前值时触发。 |

View File

@ -26,6 +26,7 @@
| ``filter-options`` | `Array<Object>` | - | 筛选选项列表,项目的类型为 `{label, value, options, disabled, ...}`,可参考 [`Select`](./select) 组件的 [`options`](./select#props-options) 属性。 |
| ``filter-title`` | `string=` | - | 筛选下拉的标题。 |
| ``allowed-orders`` | `Array` | `[false, 'desc', 'asc']` | [^allowed-orders] |
| ``tooltip`` | `boolean | ((item: Object) => string)` | - | 是否当内容溢出时自动显示悬浮提示。默认显示所属 `Table` 组件 [`data`](./table#props-data) 属性数据项中 [`field`](#props-field) 属性对应的字段值。传入函数时,`item` 参数为整个 data 数据项,返回的字符串将作为提示内容展示。 |
^^^sortable
本列是否支持排序。

View File

@ -6,13 +6,6 @@
[[ demo src="/demo/pagination/size.vue" ]]
### 跳转到指定页
使用 [`goto`](#props-goto) 属性开启跳转到指定页的功能。
[[ demo src="/demo/pagination/goto.vue" ]]
### 每页个数
使用 [`page-size`](#props-page-size) 属性来指定当前每页的个数。
@ -21,6 +14,12 @@
[[ demo src="/demo/pagination/pages.vue" ]]
### 可选部分
使用 [`show-total`](#props-show-total) / [`show-page-size`](#props-show-page-size) / [`show-goto`](#props-show-goto) 属性来分别控制是否显示项目总数/每页项目数选择器/跳转到指定页。
[[ demo src="/demo/pagination/parts.vue" ]]
## API
### 属性
@ -29,12 +28,14 @@
| -- | -- | -- | -- |
| ``ui`` | `string=` | - | [^ui] |
| ``page`` | `number` | `1` | 当前页码(从 `1` 开始)。 |
| ``total`` | `number` | - | 总数。 |
| ``total`` | `number` | - | 项目总数。 |
| ``to`` | `string | Object` | `''` | [^to] |
| ``native`` | `boolean` | `false` | 原生链接跳转。 |
| ``page-size`` | `number` | `pagination.pageSize` | [^page-size] |
| ``page-sizes`` | `Array` | `pagination.pageSizes` | 每页个数候选项。 |
| ``goto`` | `boolean` | `false` | 是否显示直接跳转到页码。 |
| ``page-sizes`` | `Array<number>` | `pagination.pageSizes` | 每页个数候选项。 |
| ``show-goto`` | `boolean=` | `false` | 是否显示直接跳转到页码。 |
| ``show-total`` | `boolean=` | `false` | 是否显示项目总数。 |
| ``show-page-size`` | `boolean=` | `false` | 是否显示每页项目数选择器。 |
^^^ui
预设样式。
@ -64,7 +65,7 @@
| 名称 | 描述 |
| -- | -- |
| ``pagesizechange`` | `page-size` 改变时触发,回调参数为 `(size: number)`。`size` 为新的 `page-size`。 |
| ``pagesizechange`` | 每页显示项目被切换时触发,回调参数为 `(size: number)`。`size` 为新的每页显示项目数。 |
| ``redirect`` | 链接跳转时触发,回调参数为 `(page: number, event: Object)`。`page` 为要跳转的目标页码。`event` 为原生的事件对象,在 `native``true` 时,调用 `event.preventDefault` 可阻止跳转。 |
### 全局配置

View File

@ -12,7 +12,7 @@
[[ demo src="/demo/table/basic.vue" ]]
### 高级
### 选择模式与排序
允许自定义唯一键、设定选择模式以及进行排序。
@ -24,7 +24,7 @@
[[ demo src="/demo/table/filter.vue" ]]
### 内部滚动模式
### 内部滚动
允许启用内部滚动模式,以达到固定表头表底的效果。
@ -44,7 +44,7 @@
### 表头描述
使用 [`desc`](./column#props-desc) 属性或 [`desc`](./column#slots-desc) 插槽来为表头增加描述信息。
使用 `Column` 组件的 [`desc`](./column#props-desc) 属性或 [`desc`](./column#slots-desc) 插槽来为表头增加描述信息。
[[ demo src="/demo/table/desc.vue" ]]
@ -64,6 +64,12 @@
[[ demo src="/demo/table/loading.vue" ]]
### 截断提示
使用 `Column` 组件的 [`tooltip`](./column#props-tooltip) 属性来指定在内容截断时显示悬浮提示。
[[ demo src="/demo/table/tooltip.vue" ]]
## API
### 属性

View File

@ -19,7 +19,6 @@
{{ item }}
</div>
</transition-group>
</section>
</article>
</template>
@ -67,3 +66,7 @@ export default {
transition: transform 200ms ease;
}
</style>
<docs>
可以通过 `v-drag.sort` `v-drag="{ type: 'sort', ... }"` 来实现拖拽排序
</docs>

View File

@ -0,0 +1,47 @@
<template>
<article>
<section>
<div
v-tooltip.overflow="loremIpsum"
class="item"
>
{{ loremIpsum }}
</div>
<div
v-tooltip.overflow="loremIpsum"
class="item"
>
Lorem upsum.
</div>
</section>
</article>
</template>
<script>
import { tooltip } from 'veui'
const loremIpsum = 'Lorem ipsum dolor sit amet consectetur adipisicing elit. Dignissimos consequatur ad hic aspernatur maiores adipisci velit nostrum nobis, cum earum, incidunt repellendus ex! Fuga, fugit! Placeat quam ex minima laudantium.'
export default {
directives: {
tooltip
},
data () {
return {
loremIpsum
}
}
}
</script>
<style lang="less" scoped>
.item {
display: inline-block;
margin-right: 12px;
width: 200px;
border: 1px solid #ccc;
white-space: nowrap;
overflow: hidden;
text-overflow: ellipsis;
}
</style>

View File

@ -1,37 +0,0 @@
<template>
<article>
<veui-pagination
:page="page"
:total="total"
:to="to"
goto
/>
</article>
</template>
<script>
import { Pagination } from 'veui'
export default {
components: {
'veui-pagination': Pagination
},
data () {
return {
to: './pagination?page=:page',
total: 10101
}
},
computed: {
page () {
return Number(this.$route.query.page) || 1
}
}
}
</script>
<style lang="less" scoped>
article {
text-align: right;
}
</style>

View File

@ -0,0 +1,60 @@
<template>
<article>
<section class="toggles">
<veui-checkbox v-model="showTotal">
Show total
</veui-checkbox>
<veui-checkbox v-model="showPageSize">
Show page size
</veui-checkbox>
<veui-checkbox v-model="showGoto">
Show goto
</veui-checkbox>
</section>
<section>
<veui-pagination
:page="page"
:total="total"
to="./pagination?page=:page"
:show-total="showTotal"
:show-goto="showGoto"
:show-page-size="showPageSize"
/>
</section>
</article>
</template>
<script>
import { Pagination, Checkbox } from 'veui'
export default {
components: {
'veui-pagination': Pagination,
'veui-checkbox': Checkbox
},
data () {
return {
to: '.',
total: 10101,
showTotal: true,
showGoto: true,
showPageSize: true
}
},
computed: {
page () {
return Number(this.$route.query.page) || 1
}
}
}
</script>
<style lang="less" scoped>
.toggles {
margin-bottom: 20px;
}
.veui-checkbox + .veui-checkbox {
margin-left: 16px;
}
</style>

View File

@ -1,34 +1,36 @@
<template>
<article>
<section>
<div>loading<veui-switch v-model="loading"/></div>
<veui-table
:data="data"
:loading="loading"
key-field="id"
>
<veui-table-column
field="id"
title="ID"
sortable
/>
<veui-table-column
field="name"
title="Name"
/>
<veui-table-column
field="bid"
title="Bid"
width="160"
align="right"
sortable
>
<template slot-scope="{ bid }">
{{ bid | currency }}
</template>
</veui-table-column>
</veui-table>
<veui-switch v-model="loading">
Loading
</veui-switch>
</section>
<veui-table
:data="data"
:loading="loading"
key-field="id"
>
<veui-table-column
field="id"
title="ID"
sortable
/>
<veui-table-column
field="name"
title="Name"
/>
<veui-table-column
field="bid"
title="Bid"
width="160"
align="right"
sortable
>
<template slot-scope="{ bid }">
{{ bid | currency }}
</template>
</veui-table-column>
</veui-table>
</article>
</template>

View File

@ -0,0 +1,64 @@
<template>
<article>
<veui-table
:data="data"
key-field="id"
>
<veui-table-column
field="id"
title="ID"
/>
<veui-table-column
field="name"
title="Name"
/>
<veui-table-column
field="desc"
title="Description"
tooltip
/>
</veui-table>
</article>
</template>
<script>
import { Table, Column } from 'veui'
const long = 'Lorem ipsum dolor sit amet, consectetur adipisicing elit. Quos, quibusdam! Pariatur, laboriosam? Voluptatibus, sunt.'
const short = 'Lorem ipsum.'
export default {
components: {
'veui-table': Table,
'veui-table-column': Column
},
data () {
return {
density: 'normal',
size: 'm',
data: [
{
id: '3154',
name: 'Steve Rogers',
desc: long
},
{
id: '3155',
name: 'Thor Odinson',
desc: short
},
{
id: '3156',
name: 'Tony Stark',
desc: short
},
{
id: '3157',
name: 'Stephen Strange',
desc: long
}
]
}
}
}
</script>

View File

@ -147,11 +147,6 @@
<div v-drag:box1,box2></div>
```
## 拖拽排序v-drag.sort
可以通过 `v-drag.sort``v-drag="{ type: 'sort', ... }"` 来实现拖拽排序。
## 扩展
可以通过继承 `BaseHandler` 扩展 `v-drag` 指令:

View File

@ -10,7 +10,13 @@ VEUI 对通过 `v-tooltip` 定义的全局浮层提示进行了统一的体验
## 示例
[[ demo src="/demo/directives/tooltip.vue" ]]
### 基本用法
[[ demo src="/demo/directives/tooltip/default.vue" ]]
### 溢出时显示
[[ demo src="/demo/directives/tooltip/overflow.vue" ]]
## API
@ -42,14 +48,15 @@ VEUI 对通过 `v-tooltip` 定义的全局浮层提示进行了统一的体验
| -- | -- | -- | -- |
| ``content`` | `string | VNode | Array<VNode>` | - | 提示信息字符串或通过渲染函数返回的虚拟节点(数组)。 |
| ``position`` | `string` | - | 浮层提示的展示位置。参考 [`Tooltip`](../components/tooltip) 组件的 [`position`](../components/tooltip#props-position) 属性。 |
| ``overflow`` | `boolean` | `false` | 是否仅在目标元素内容溢出容器时显示悬浮提示。 |
| ``disabled`` | `boolean` | `false` | 是否禁用浮层提示。 |
### 修饰符
对应 `Object` 类型绑定值中的 `position`。例如:
对应 `Object` 类型绑定值中的 `position` / `overflow`。例如:
```html
<button v-tooltip.bottom-end="添加">+</button>
<span v-tooltip.bottom-end.overflow="添加">A paragraph of very long text...</span>
```
### 全局配置

View File

@ -25,6 +25,8 @@ See [the demos of `Table`](./table#demos).
| ``filter-multiple`` | `boolean=` | `false` | Whether the built-in filter is multi-select or not. |
| ``filter-options`` | `Array<Object>` | - | The list of filter options, with items of type `{label, value, options, disabled, ...}`, see the [`options`](./select#options) prop of the [`Select`](./select) component. |
| ``filter-title`` | `string=` | - | The title of the filter dropdown. |
| ``allowed-orders`` | `Array` | `[false, 'desc', 'asc']` | [^allowed-orders] |
| ``tooltip`` | `boolean | ((item: Object) => string)` | - | Whether to automatically show tooltips when content overflows. The tooltip displays the field corresponding to the [`field`](#props-field) prop of the [`data`](. /table#props-data) prop of `Table` component the current column belongs to. When being a function, the `item` argument is the entire data item and the returned string will be displayed as tooltip content. |
^^^sortable
Whether current column is sortable.

View File

@ -6,11 +6,19 @@
[[ demo src="/demo/pagination/size.vue" ]]
### Go to a specific page
### Page size
Use the [`goto`](#props-goto) prop to enable the go to page section.
Use the [`page-size`](#props-page-size) prop to specify the current page size.
[[ demo src="/demo/pagination/goto.vue" ]]
Use the [`page-sizes`](#props-page-sizes) prop to specify the page size options.
[[ demo src="/demo/pagination/pages.vue" ]]
### Optional parts
Use the [`show-total`](#props-show-total) / [`show-page-size`](#props-show-page-size) / [`show-goto`](#props-show-goto) props to control the visibility of the total items / page size selector / goto page parts.
[[ demo src="/demo/pagination/parts.vue" ]]
## API
@ -20,12 +28,14 @@ Use the [`goto`](#props-goto) prop to enable the go to page section.
| -- | -- | -- | -- |
| ``ui`` | `string=` | - | [^ui] |
| ``page`` | `number` | `1` | Current page index (starts from `1`). |
| ``total`` | `number` | - | Total page count. |
| ``total`` | `number` | - | Total items count. |
| ``to`` | `string | Object` | `''` | [^to] |
| ``native`` | `boolean` | `false` | Use native links for navigation. |
| ``page-size`` | `number` | `pagination.pageSize` | [^page-size] |
| ``page-sizes`` | `Array` | `pagination.pageSizes` | The predefined available page sizes for users to select. |
| ``goto`` | `boolean` | `false` | Whether to show “goto page number” section. |
| ``show-goto`` | `boolean=` | `false` | Whether to show the go to page section. |
| ``show-total`` | `boolean=` | `false` | Whether to show the total page count. |
| ``show-page-size`` | `boolean=` | `false` | Whether to show the page size selection section. |
^^^ui
Style variants.
@ -55,7 +65,7 @@ The count of item in each page.
| Name | Description |
| -- | -- |
| ``pagesizechange`` | Triggered when `page-size` is changed. The callback parameter list is `(size: number)`, with `size` being the new `page-size` value. |
| ``pagesizechange`` | Triggered when page size is changed. The callback parameter list is `(size: number)`, with `size` being the new page size value. |
| ``redirect`` | Triggered when page links are activated. The callback parameter list is `(page: number, event: Object)`. `page` is the number of the targe page. `event` is the native event object, calling `event.preventDefault` will stop navigation when `native` is `true`. |
### Configs

View File

@ -12,7 +12,7 @@ Available density variants for the [`ui`](#props-ui) prop: `compact` / `loose`.
[[ demo src="/demo/table/basic.vue" ]]
### Advanced
### Selection and sorting
Supports specifying row keys, mode of selection, and sorting by values of specific column.
@ -48,6 +48,12 @@ Use the [`desc`](./column#props-desc) prop or the [`desc`](./column#slots-desc)
[[ demo src="/demo/table/desc.vue" ]]
### Truncation tooltips
Use the [`tooltip`](./column#props-tooltip) attribute of the `Column` component to specify that a hover tooltip is displayed when the content is truncated.
[[ demo src="/demo/table/tooltip.vue" ]]]
## API
### Props

14
package-lock.json generated
View File

@ -79,7 +79,7 @@
"veui-theme-dls-icons": "^2.3.0",
"vue-awesome": "^4.1.0",
"vue-i18n": "^8.16.0",
"vue-live": "^1.17.1",
"vue-live": "^1.17.2",
"vue-windows": "^0.2.4"
}
},
@ -24393,9 +24393,9 @@
}
},
"node_modules/vue-live": {
"version": "1.17.1",
"resolved": "https://registry.npmjs.org/vue-live/-/vue-live-1.17.1.tgz",
"integrity": "sha512-UVymml4t84NCESH3o3ZtYfpGztj9+S1sZQ0camXI9m+WC5swzZViMpMcVteGcEz/y3Oo1uA8fZo05oDPB8LTjA==",
"version": "1.17.2",
"resolved": "https://registry.npmjs.org/vue-live/-/vue-live-1.17.2.tgz",
"integrity": "sha512-sy3fxQy57UQ5/p8bDGuGA82zHFO8UOJDESYBggWsjVwW9Yt1gixOO2KJrhJ0E0B4OznsXCY4P180Vm+o04mX1Q==",
"dev": true,
"dependencies": {
"@babel/runtime": "^7.11.2",
@ -45313,9 +45313,9 @@
}
},
"vue-live": {
"version": "1.17.1",
"resolved": "https://registry.npmjs.org/vue-live/-/vue-live-1.17.1.tgz",
"integrity": "sha512-UVymml4t84NCESH3o3ZtYfpGztj9+S1sZQ0camXI9m+WC5swzZViMpMcVteGcEz/y3Oo1uA8fZo05oDPB8LTjA==",
"version": "1.17.2",
"resolved": "https://registry.npmjs.org/vue-live/-/vue-live-1.17.2.tgz",
"integrity": "sha512-sy3fxQy57UQ5/p8bDGuGA82zHFO8UOJDESYBggWsjVwW9Yt1gixOO2KJrhJ0E0B4OznsXCY4P180Vm+o04mX1Q==",
"dev": true,
"requires": {
"@babel/runtime": "^7.11.2",

View File

@ -87,7 +87,7 @@
"veui-theme-dls-icons": "^2.3.0",
"vue-awesome": "^4.1.0",
"vue-i18n": "^8.16.0",
"vue-live": "^1.17.1",
"vue-live": "^1.17.2",
"vue-windows": "^0.2.4"
},
"dependencies": {