taolin/docs_vue2
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

feat: publicize doc implemetation

Browse Source
This commit is contained in:
Justineo 2020-08-13 11:47:56 +08:00
parent 55b9b044f2
commit 1e5fcff6ad
372 changed files with 50636 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
.editorconfig Normal file
View File

@ -0,0 +1,9 @@
root = true
[*]
charset = utf-8
indent_style = space
indent_size = 2
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true

69
.eslintrc.js Normal file
View File

@ -0,0 +1,69 @@
// http://eslint.org/docs/user-guide/configuring
module.exports = {
root: true,
parserOptions: {
parser: 'babel-eslint',
sourceType: 'module'
},
extends: [
// https://github.com/vuejs/eslint-plugin-vue#bulb-rules
'plugin:vue/essential',
'plugin:vue/recommended',
'plugin:vue/strongly-recommended',
// https://github.com/standard/standard/blob/master/docs/RULES-en.md
'standard',
'prettier/standard'
],
// required to lint *.vue files
plugins: ['vue'],
// add your custom rules here
rules: {
// allow paren-less arrow functions
'arrow-parens': 0,
// allow async-await
'generator-star-spacing': 0,
// allow debugger during development
'no-debugger': process.env.NODE_ENV === 'production' ? 2 : 0,
'no-multi-spaces': ['error', { ignoreEOLComments: true }],
'no-template-curly-in-string': 0,
// to many false positives
'vue/no-side-effects-in-computed-properties': 0,
// fix unused var error for JSX custom tags
'vue/jsx-uses-vars': 2,
'vue/require-default-prop': 0,
'vue/name-property-casing': ['error', 'kebab-case'],
'vue/component-name-in-template-casing': ['error', 'kebab-case'],
'vue/html-indent': [
'error',
2,
{
attribute: 1,
baseIndent: 0,
closeBracket: 0,
alignAttributesVertically: true
}
],
'vue/html-self-closing': [
'error',
{
html: {
void: 'never',
normal: 'always',
component: 'always'
},
svg: 'always',
math: 'always'
}
],
'vue/html-closing-bracket-spacing': [
'error',
{
startTag: 'never',
endTag: 'never',
selfClosingTag: 'never'
}
],
'vue/no-v-html': 0
}
}

12
.gitignore vendored Normal file
View File

@ -0,0 +1,12 @@
node_modules
npm-debug.log
one/build/deps.json
.DS_Store
.nuxt
.vscode
pages
components/demos
dist
logs
assets/data
static/images/mermaid

124
README.md Normal file
View File

@ -0,0 +1,124 @@
# veui/docs
> VEUI 文档。
## 本地安装
`git clone` 到本地后，在项目根目录下运行：
```shell
npm i
npm run dev
```
后在浏览访问 `http://localhost:3000` 即可。
## 文档编写
开发相关文档位于 `one/docs/development` 下。文档目录结构与网站的目录结构一致，新建 `.md` 文件后需要在 `one/docs/nav.json` 中新建相应的条目，作为目录配置。添加 `sub: true` 将缩进一个层级。
### 组件文档结构
每个组件的文档请按如下顺序编写：
1. 示例
2. API
1. 属性
2. 插槽
3. 作用域插槽
4. 事件
5. 方法
3. 全局配置
1. `veui` 中的默认
2. `veui-theme-dls` 中的默认配置
4. 图标名称
另外，如有关联组件请在最开始进行说明。比如：
```md
:::tip
`Select` 组件可以内联 [`Option`](./option) 或 [`OptionGroup`](./option-group) 组件使用。
:::
```
### 在文档中插入示例
使用 Markdown 的 shortcode 语法，如下：
```md
[[ demo src="../demo/button.vue"]]
```
路径为 demo 文件相对于当前文档文件的路径。Demo 文件是一个 Vue 单文件组件，最后会将代码展示到文档中。可以编写多个 `<style>` 块，如果带上自定义的 `docs` 属性，则会从文档的源码中去除，用来写一些不想输出到文档里的样式（建议文档里只展示和演示的用法相关的样式代码）。
可以为 demo 书写内嵌的说明，方法为在 demo 文件中增加 `<docs>` 自定义块，比如：
```html
<docs>
具体内容请参考项目 [repo](https://github.com/ecomfe/veui)。
</docs>
```
### 扩展 Markdown 语法
#### 自定义块
因为 Markdown 原生不支持对特定区块设定自定义的 `class`，直接书写 HTML 标签的话内部的内容就无法直接写 Markdown 了。故扩展了如下自定义块的语法：
```md
:::tip
这是一条小贴士。
:::
```
将会渲染为：
```html
<div class="tip custom-block">这是一条小贴士。</div>
```
目前支持的状态类型有 `tip`/`warning`/`alert`。
标注 `v-model` 及 `.sync` 的属性/事件请使用如下格式：
```md
:::badges
`v-model`
:::
```
#### 内联引用
Markdown 中书写表格比较麻烦，如果想在里面嵌入格式比较复杂的内容，原生语法 + GFM 扩展都是不够用的。这里提供了一个定义可被引用内容+将对应内容块内联到文档内任意位置的语法。
定义可被引用的内容：
```md
^^^ui
内容
^^^
```
引用方式和脚注的引用方式相同，只是会将内容直接嵌入当前位置：
```md
[^ui]
```
#### 可折叠区块
有时内容过长不利于阅读全文，故扩展了如下语法支持默认收起的区块，可点击展开。
```md
+++摘要内容
详细内容
+++
```
## 文案规范
参见[《中文文案排版指北》](https://github.com/sparanoid/chinese-copywriting-guidelines)。

9
app.html Normal file
View File

@ -0,0 +1,9 @@
<!DOCTYPE html>
<html {{ HTML_ATTRS }}>
<head>
{{ HEAD }}
</head>
<body {{ BODY_ATTRS }}>
{{ APP }}
</body>
</html>

43
app.js Normal file
View File

@ -0,0 +1,43 @@
const express = require('express')
const nuxt = require('nuxt')
const { Nuxt, Builder } = nuxt
const app = express()
const host = process.env.HOST || '127.0.0.1'
const port = process.env.PORT || 8080
// uncaughtException 避免程序崩溃
process.on('uncaughtException', function (err) {
console.error(err)
try {
let killTimer = setTimeout(function () {
process.exit(1)
}, 10000)
killTimer.unref()
server.close()
} catch (e) {
console.error('Fail to close server safely. ', e.stack)
}
})
app.set('port', port)
// Import and Set Nuxt.js options
const config = require('./nuxt.config.js')
config.dev = !(process.env.NODE_ENV === 'production')
// Init Nuxt.js
const server = new Nuxt(config)
// Build only in dev mode
if (config.dev) {
const builder = new Builder(server)
builder.build()
}
// Give nuxt middleware to express
app.use(server.render)
// Listen the server
app.listen(port, host)
console.log('Server listening on ' + host + ':' + port) // eslint-disable-line no-console

23
app/router.scrollBehavior.js Normal file
View File

@ -0,0 +1,23 @@
export default function scrollBehavior (to) {
// if the returned position is falsy or an empty object,
// will retain current scroll position.
let position = false
// if no children detected
if (to.matched.length < 2) {
// scroll to the top of the page
position = { x: 0, y: 0 }
} else if (
to.matched.some(r => r.components.default.options.scrollToTop)
) {
// if one of the children has scrollToTop option set to true
position = { x: 0, y: 0 }
} else if (
to.hash &&
document.querySelector(decodeURIComponent(to.hash))
) {
// scroll to anchor by returning the selector
position = { selector: to.hash }
}
return position
}

8
assets/README.md Normal file
View File

@ -0,0 +1,8 @@
# ASSETS
This directory contains your un-compiled assets such as LESS, SASS, or JavaScript.
More information about the usage of this directory in the documentation:
https://nuxtjs.org/guide/assets#webpacked
**This directory is not required, you can delete it if you don't want to use it.**

103
assets/styles/global.styl Normal file
View File

@ -0,0 +1,103 @@
// only enable on Retina displays
@media screen and (min-resolution 2dppx)
html
-webkit-font-smoothing antialiased
-moz-osx-font-smoothing grayscale
*
*::before
*::after
box-sizing border-box
html
font-weight 400
color #333
scroll-behavior smooth
html
body
#__nuxt
#__layout
height 100%
body
margin-left 240px
button
input
font inherit
color inherit
a:focus
outline none
main
line-height 1.5
menu
margin 0
padding 0
.menu-item
list-style none
line-height 1
.menu-link
display block
position relative
text-decoration none
cursor default
a&
cursor pointer
&::after
content ""
position absolute
bottom 2px
left 50%
width 0
height 2px
transition width 0.2s, left 0.2s
a&:focus::after
a&:hover::after
width 100%
left 0
.algolia-autocomplete
.algolia-docsearch-suggestion--title:last-child
margin-bottom 0
.ds-dropdown-menu
&
& [class^=ds-dataset-]
border-radius 3px
&::before
width 10px
height 10px
top -4px
.ds-suggestion.ds-cursor .algolia-docsearch-suggestion
&.suggestion-layout-simple
&:not(.suggestion-layout-simple) .algolia-docsearch-suggestion--content
background-color #f8f8f8
.algolia-docsearch-suggestion--category-header
font-size 14px
.algolia-docsearch-suggestion--subcategory-column
font-size 12px
overflow hidden
white-space nowrap
text-overflow ellipsis
.algolia-docsearch-suggestion--highlight
color #fff
background-color #111
.algolia-docsearch-suggestion--text .algolia-docsearch-suggestion--highlight
box-shadow inset 0 -2px 0 0 #111

50
assets/styles/mermaid-cli.css Normal file
View File

@ -0,0 +1,50 @@
svg {
font-family: "Helvetica Neue", Arial, PingFang SC, "Microsoft YaHei", sans-serif;
font-size: 13px;
}
svg .label {
color: #333;
}
svg .node rect,
svg .node circle,
svg .node ellipse,
svg .node polygon {
fill: #eee;
stroke: #999;
stroke-width: 1px;
}
svg .node.clickable {
cursor: pointer;
}
svg .arrowheadPath {
fill: #333;
}
svg .edgePath .path {
stroke: #666;
stroke-width: 1.5px;
}
svg .edgeLabel {
background-color: #fff;
}
svg .cluster rect {
fill: #eaf2fb !important;
stroke: #26a !important;
stroke-width: 1px !important;
}
svg .cluster text {
fill: #333;
}
svg div.mermaidTooltip {
position: absolute;
text-align: center;
max-width: 200px;
padding: 2px;
font-family: "Helvetica Neue", Arial, PingFang SC, "Microsoft YaHei", sans-serif;
font-size: 12px;
background: #eaf2fb;
border: 1px solid #26a;
border-radius: 2px;
pointer-events: none;
z-index: 100;
}

50
assets/styles/mermaid.css Normal file
View File

@ -0,0 +1,50 @@
.mermaid {
font-family: "Helvetica Neue", Arial, PingFang SC, "Microsoft YaHei", sans-serif;
font-size: 13px;
}
.mermaid .label {
color: #333;
}
.mermaid .node rect,
.mermaid .node circle,
.mermaid .node ellipse,
.mermaid .node polygon {
fill: #eee;
stroke: #999;
stroke-width: 1px;
}
.mermaid .node.clickable {
cursor: pointer;
}
.mermaid .arrowheadPath {
fill: #333;
}
.mermaid .edgePath .path {
stroke: #666;
stroke-width: 1.5px;
}
.mermaid .edgeLabel {
background-color: #fff;
}
.mermaid .cluster rect {
fill: #eaf2fb !important;
stroke: #26a !important;
stroke-width: 1px !important;
}
.mermaid .cluster text {
fill: #333;
}
.mermaid div.mermaidTooltip {
position: absolute;
text-align: center;
max-width: 200px;
padding: 2px;
font-family: "Helvetica Neue", Arial, PingFang SC, "Microsoft YaHei", sans-serif;
font-size: 12px;
background: #eaf2fb;
border: 1px solid #26a;
border-radius: 2px;
pointer-events: none;
z-index: 100;
}

306
assets/styles/post.styl Normal file
View File

@ -0,0 +1,306 @@
@import "~highlight.js/styles/atom-one-dark.css"
@import "./mermaid.css"
margin-y($top, $bottom = $top)
margin-top $top
margin-bottom $bottom
.post
padding 30px 60px
font-size 14px
line-height 1.8
color #666
font-weight 400
hyphens auto
.post-layout &
min-height 100%
margin-bottom -192px
&::after
content ""
display block
height 192px
.post-layout.no-links &
margin-bottom -58px
.no-links &::after
height 58px
h1
margin-y(0, 1.25em)
font-size 36px
small
vertical-align 0.1em
color #999
h2
margin-y(1.3em, 1.2em)
font-size 30px
&::before
content "#"
margin-right 5px
color #ccc
& + h3
margin-top 2em
h3
margin-y(1.25em, 1.15em)
font-size 24px
h4
margin-y(1.15em, 1.1em)
font-size 18px
h5
margin-y(1.05em)
font-size 14px
h6
margin-y(1em)
font-size 12px
h1
h2
h3
font-weight 500
clear both
h1
h2
h3
h4
h5
h6
color #333
line-height 1
br
clear both
p
margin-y(0.5em)
ul
ol
padding-left 1.5em
blockquote
margin 1em 0
padding-left 1em
border-left 5px solid #f1f1f1
color #999
table
width 100%
border-collapse collapse
border 1px solid #f1f1f1
border-style none solid
margin-y(1.5em)
pre
table
max-width 480px
th
td
min-width 90px
padding 7px 14px
border 1px solid #f1f1f1
border-style solid none
text-align left
& > :first-child
margin-top 5px
& > :last-child
margin-bottom 5px
pre
padding 10px 15px
table
margin-y(0.2em, 0.5em)
td:first-child
white-space nowrap
a:link
a:visited
&:not([class^="veui-"])
text-decoration none
color #3998fc
transition color 0.2s
&:hover
color #3389e3
&:active
color #2e7aca
code
padding 2px 4px
background-color rgba(0, 0, 0, 0.024)
font-size 90%
overflow visible
hyphens none
font-family Menlo, consolas, monospace
hr
height 1px
margin 2em 0
padding 0
background-color #eff0f1
border 0
clear both
figure
float right
width 60%
margin 0 0 30px 20px
& + h1
& + h2
& + h3
& + h4
& + h5
& + h6
margin-top 0
img
display block
margin auto
.preview
padding 20px
overflow hidden
border 1px solid #e5e5e5
transition box-shadow 0.2s
cursor pointer
text-align center
&:hover
box-shadow 0 0 5px rgba(0, 0, 0, 0.2)
&.hero
width 100%
float none
figcaption
margin-top 10px
font-size 12px
p
margin 0
line-height 20px
.caption
font-weight 500
.desc
color #999
.comparison
float right
width 60%
margin 0 0 30px 20px
figure
width calc(50% - 5px)
margin 0
.good
float left
.bad
float right
.caption
color #ff5b5b
img
max-width 100%
max-height 100%
pre
border 1px solid #eee
padding 30px
background-color #f9f9f9
white-space pre
overflow auto
code
background-color transparent
padding 0
var
font-family "PT Serif", Georgia, serif
kbd
display inline-block
padding 3px 5px 6px
font-size 90%
line-height 10px
color #444d56
vertical-align 1px
background-color #fafbfc
border solid 1px #c6cbd1
border-bottom-color #959da5
border-radius 3px
box-shadow inset 0 -1px 0 #959da5
.custom-block
border 1px solid
margin 1em 0
padding 0.75em 1em
& > :first-child
margin-top 0
& > :last-child
margin-bottom 0
.alert
.warning
.tip
font-size 13px
.alert
border-color #fee
background-color tint(#fee, 50%)
.warning
border-color #fef4e6
background-color tint(#fef4e6, 50%)
.tip
border-color #d8ebff
background-color tint(#d8ebff, 50%)
.badges
border none
padding 0
code
padding 2px 3px
background #333
border-radius 3px
color #fff
font-size 80%
.oss-badges
border none
padding 0
a
margin-right 10px
.one-demo
margin 1em 0 1.25em
.one-details
margin-bottom 5px

1
build.sh Normal file
View File

@ -0,0 +1 @@
echo "DONE."

99
common/i18n.js Normal file
View File

@ -0,0 +1,99 @@
import { compact, find } from 'lodash'
import nav from '../assets/data/nav.json'
export const LOCALES = [
{
code: 'zh-Hans',
label: '简体中文'
},
{
code: 'en-US',
label: 'English (US)'
}
]
export const DEFAULT_LOCALE = LOCALES[0].code
export const LOCALE_CODES = LOCALES.map(l => l.code)
export const RE_LOCALE = new RegExp(`^\\/(${LOCALE_CODES.join('|')})(?=\\/|$)`)
export function getLocale (path) {
if (path != null) {
let [, locale] = path.match(RE_LOCALE) || []
if (locale) {
return locale
}
}
return DEFAULT_LOCALE
}
export function getCanonicalPath (path) {
if (path === '') {
return '/'
}
let locale = getLocale(path)
path = path.replace(new RegExp(`^\\/${locale}(?=\\/|$)`), '')
return path.charAt(0) === '/' ? path : `/${path}`
}
export function getLocalePath (path, locale) {
if (locale === DEFAULT_LOCALE) {
return path
}
return `/${locale}${path}`.replace(/\/$/, '')
}
export const htmlAttrs = {
head () {
return {
htmlAttrs: {
lang: getLocale(this.$route.path)
}
}
}
}
export default {
computed: {
canonicalPath () {
if (this.$route.path === '') {
return '/'
}
let path = this.$route.path.replace(new RegExp(`^\\/${this.locale}(?=\\/|$)`), '')
return path.charAt(0) === '/' ? path : `/${path}`
},
locale () {
if (this.$route) {
let [, locale] = this.$route.path.match(RE_LOCALE) || []
if (locale) {
return locale
}
}
return DEFAULT_LOCALE
},
locales () {
return LOCALES
}
},
methods: {
getLocalePath (path, locale) {
let loc = locale || this.locale
if (loc === DEFAULT_LOCALE) {
return path
}
return `/${loc}${path}`.replace(/\/$/, '')
},
isPathDisabled (path, locale) {
let segments = compact(path.split('/'))
let navItem = segments.reduce((node, seg) => {
if (!node) {
return null
}
return find(node.children, ({ slug }) => slug === seg)
}, { children: nav[locale] || [] })
if (!navItem) {
return null
}
return navItem.disabled
}
}
}

2070
common/region.js Normal file
View File

File diff suppressed because it is too large Load Diff

38
common/util.js Normal file
View File

@ -0,0 +1,38 @@
export function walk (list, base, callback) {
if (!Array.isArray(list)) {
return
}
let stopped = list.some(item => {
let newBase = `${base}/${item.slug}`
if (typeof callback === 'function') {
if (callback(item, newBase) === false) {
return true
}
}
if (item.children) {
if (walk(item.children, newBase, callback) === false) {
return true
}
}
return false
})
return !stopped
}
export function getLink ({ slug, link, children }) {
if (link === false) {
let actual = null
walk(children, slug, (item, base) => {
// leaf
if (!item.children || !item.children.length) {
actual = base
return false
}
})
if (actual !== null) {
return `/${actual}`
}
}
return `/${slug}`
}

84
components/OneBackToTop.vue Normal file
View File

@ -0,0 +1,84 @@
<template>
<button
class="one-back-to-top"
:class="{
scrolled: !top
}"
aria-hidden="true"
@click="scrollToTop"
>
<veui-icon
class="icon"
name="arrow-up"
:label="t('toTop')"
/>
</button>
</template>
<script>
import { Icon } from 'veui'
import i18n from 'veui/mixins/i18n'
import 'veui-theme-dls-icons/arrow-up'
import { debounce } from 'lodash'
export default {
name: 'one-back-to-top',
components: {
'veui-icon': Icon
},
mixins: [i18n],
data () {
return {
top: true
}
},
mounted () {
this.check = debounce(() => {
this.top = window.scrollY === 0
}, 300)
window.addEventListener('scroll', this.check)
this.check()
},
beforeDestroy () {
this.check.cancel()
window.removeEventListener('scroll', this.check)
},
methods: {
scrollToTop () {
window.scrollTo(0, 0)
}
}
}
</script>
<style lang="stylus" scoped>
.one-back-to-top
position fixed
right 35px
bottom 35px
width 43px
height 43px
border 1px solid #dbdbdb
border-radius 50%
opacity 0
outline none
box-shadow 0 0 2px #dbdbdb
cursor pointer
transition background-color 0.3s, opacity 0.3s
&:hover
&.focus-visible
background-color #f7f7f7
&:active
background-color #ececec
.icon
position absolute
top 50%
left 50%
transform translate(-50%, -50%)
.scrolled
opacity 1
</style>

137
components/OneDemo.vue Normal file
View File

@ -0,0 +1,137 @@
<template>
<article
class="one-demo"
:class="{ expanded: localExpanded }"
>
<section class="demo">
<browser-window
v-if="browser"
:url="browser"
width="80%"
height="400px"
>
<slot/>
</browser-window>
<slot v-else/>
</section>
<section
v-if="$slots.desc"
class="desc"
>
<slot name="desc"/>
</section>
<section
v-if="$slots.source"
ref="source"
class="source"
:style="{ height: localExpanded ? `${sourceHeight || 0}px` : '0' }"
>
<slot name="source"/>
</section>
<button
class="toggle"
@click="localExpanded = !localExpanded"
>
<veui-icon
class="arrow"
name="chevron-down"
/> {{ t(localExpanded ? 'hideCode' : 'showCode') }}
</button>
</article>
</template>
<script>
import { Icon } from 'veui'
import i18n from 'veui/mixins/i18n'
import { BrowserWindow } from 'vue-windows'
import 'veui-theme-dls-icons/chevron-down'
export default {
name: 'one-demo',
components: {
'veui-icon': Icon,
BrowserWindow
},
mixins: [i18n],
props: {
expanded: Boolean,
browser: String
},
data () {
return {
sourceHeight: 0,
localExpanded: this.expanded
}
},
watch: {
expanded (val) {
this.localExpanded = val
},
localExpanded (val) {
this.$emit('update:expanded', val)
}
},
mounted () {
let source = this.$refs.source
let style = source.style
style.height = ''
style.height = source.offsetHeight
this.sourceHeight = source.offsetHeight
style.height = '0'
}
}
</script>
<style src="vue-windows/dist/vue-windows.css"></style>
<style lang="stylus" scoped>
.one-demo
overflow hidden
.arrow
transition transform 0.3s
height 1.2em
margin-right 4px
.one-demo.expanded &
transform rotateZ(180deg)
.demo
border 1px solid #eee
padding 30px
.desc
border 1px solid #eee
padding 18px 20px
background-color #fcfcfc
.source
transition height 0.3s
& >>> pre
margin-top 0
margin-bottom 0
.desc
.source >>> pre
.toggle
margin-top -1px
.toggle
position relative
display flex
justify-content center
align-items center
line-height 2
width 100%
height 40px
border 1px solid #eee
background-color #fff
transition background-color 0.3s
outline none
cursor pointer
&:hover
&.focus-visible
background-color #fafafa
</style>

115
components/OneDetails.vue Normal file
View File

@ -0,0 +1,115 @@
<template>
<div
:class="{
'one-details': true,
expanded
}"
>
<button
class="summary"
@click="toggle"
>
<veui-icon
class="arrow"
name="chevron-right"
/> {{ summary }}
</button>
<div
ref="content"
class="content"
:style="style"
@transitionend="stable = true"
>
<slot/>
</div>
</div>
</template>
<script>
import { Icon } from 'veui'
import 'veui-theme-dls-icons/chevron-right'
export default {
name: 'one-details',
components: {
'veui-icon': Icon
},
props: {
summary: {
type: String,
required: true,
default: '详细信息'
}
},
data () {
return {
expanded: false,
intrinsicHeight: 0,
height: 0,
stable: true
}
},
computed: {
style () {
return this.stable
? this.expanded
? null
: 'height: 0'
: `height: ${this.height}px`
}
},
mounted () {
this.updateHeight()
},
methods: {
toggle () {
this.expanded = !this.expanded
this.stable = false
this.height = this.intrinsicHeight
if (!this.expanded) {
requestAnimationFrame(() => {
requestAnimationFrame(() => {
this.height = 0
})
})
}
},
updateHeight () {
let { content } = this.$refs
this.intrinsicHeight = content.scrollHeight
}
}
}
</script>
<style lang="stylus" scoped>
.one-details
overflow hidden
.summary
border none
background none
padding-left 0
cursor help
outline none
display flex
align-items center
line-height 1em
&:hover
color #333
.content
overflow hidden
transition height 0.3s
.arrow
transition transform 0.3s
margin-right 8px
width 1.2em
height 1.2em
.expanded > .summary > &
transform rotateZ(90deg)
</style>

203
components/OneFooter.vue Normal file
View File

@ -0,0 +1,203 @@
<template>
<footer class="one-footer">
<nav
class="links"
:class="{ empty: single }"
>
<nuxt-link
v-if="prev && level > 0"
key="prev"
class="prev"
:to="prev.to"
>
{{ prev.title }}
</nuxt-link>
<nuxt-link
v-if="next && level > 0"
key="next"
class="next"
:to="next.to"
>
{{ next.title }}
</nuxt-link>
</nav>
<p class="copyright">
© Baidu, Inc. {{ year }}
</p>
</footer>
</template>
<script>
import { compact, find, findIndex } from 'lodash'
import i18n from '../common/i18n'
export default {
name: 'one-footer',
mixins: [i18n],
props: {
nav: {
type: Array,
default () {
return []
}
}
},
data () {
return {
year: new Date().getFullYear()
}
},
computed: {
links () {
let segments = compact(this.canonicalPath.split('/'))
return getLinks(this.nav, segments)
},
level () {
return this.links ? this.links.level : 0
},
base () {
return this.links ? this.links.base : null
},
prev () {
return this.resolve(this.links ? this.links.prev : null)
},
next () {
return this.resolve(this.links ? this.links.next : null)
},
single () {
return (!this.prev && !this.next) || this.level < 1
}
},
watch: {
single: {
handler (val) {
this.$emit('update', {
hasLinks: !val
})
},
immediate: true
}
},
methods: {
resolve (link) {
let { slug, title, link: lk } = link || {}
if (typeof slug !== 'string' || lk === false) {
return null
}
let base = this.base
return {
title,
to: this.getLocalePath(slug ? `${base}/${slug}` : base)
}
}
}
}
function findSibling (items, start, forward) {
if ((start === 0 && !forward) || (start === items.length - 1 && forward)) {
return null
}
let candidates = forward
? items.slice(start + 1)
: items.slice(0, start).reverse()
return find(candidates, ({ disabled }) => !disabled)
}
function getLinks (nav, remaining, level = 0, base = '') {
let [segment = '', ...segments] = [...remaining]
let i = findIndex(nav, ({ slug }) => slug === segment)
if (i === -1) {
return null
}
let links = {
prev: findSibling(nav, i, false),
next: findSibling(nav, i, true),
level,
base
}
let sub = nav[i].children
if (!sub) {
if (segments.length) {
return null
}
return links
}
return (
getLinks(sub, segments, level + 1, segment ? `${base}/${segment}` : base) ||
links
)
}
</script>
<style lang="stylus" scoped>
arrow()
content ""
display block
width 23px
height 33px
background #333 url("/icons/angle.svg") no-repeat 50% 50% / auto 21.5px
transition background-color 0.3s
.one-footer
clear both
padding 0 60px
.links
border-top 1px solid #eee
padding 20px 0 80px
overflow hidden
.empty
display none
overflow hidden
.prev
.next
display block
line-height 33px
color #333
text-decoration none
&:hover
&.focus-visible
&::before
&::after
background-color #5b5b5b
&:active
&::before
&::after
background-color #818181
.prev::before
.next::after
arrow()
.prev
float left
&::before
float left
margin-right 15px
transform rotate(180deg)
.next
float right
&::after
float right
margin-left 15px
.copyright
margin 0
padding 25px 0 20px
border-top 1px solid #eee
line-height 1
font-size 12px
text-align center
</style>

89
components/OneHeader.vue Normal file
View File

@ -0,0 +1,89 @@
<template>
<header class="one-header">
<h1>Baidu DLS</h1>
<a
href="http://dls.baidu.com/"
target="_blank"
>返回 DLS</a>
<veui-dropdown
label="Vue"
:options="options"
@click="redirect"
/>
</header>
</template>
<script>
import { Dropdown } from 'veui'
export default {
name: 'one-header',
components: {
'veui-dropdown': Dropdown
},
data () {
return {
options: [
{
label: 'Vue',
value: '/'
},
{
label: 'React',
value: 'http://one-ui.baidu-int.com/'
},
{
label: 'Angular',
value: 'http://cp01-wangfengjiao01.epc.baidu.com:8404/'
}
]
}
},
methods: {
redirect (url) {
location.href = url
}
}
}
</script>
<style lang="stylus" scoped>
.one-header
position fixed
top 0
left 0
right 0
z-index 20
display flex
align-items center
height 60px
background-color #070628
color #ffffff
padding 0 51px 0 17px
h1
display inline-block
font-size 18px
a
margin-left auto
color #ffffff
font-size 16px
&:hover
color #ffffff
.veui-dropdown
margin-left 40px
& >>> .veui-dropdown-button
color #ffffff
background-color transparent
border-radius 6px
height 28px
display inline-flex
align-items center
.veui-dropdown-label
line-height 1
</style>

313
components/OneMenu.vue Normal file
View File

@ -0,0 +1,313 @@
<template>
<aside class="one-nav">
<nav class="secondary">
<h2><span>VEUI<small>beta</small></span></h2>
<section class="desc">
<a href="https://github.com/ecomfe/veui">
<img
alt="VEUI on GitHub"
src="https://badgen.net/badge/-/GitHub?icon=github&label"
width="69.2"
height="20"
>
</a>
<nuxt-link
:class="{
'locale-swith': true,
disabled: altLocale.disabled
}"
:to="altLocale.disabled ? '' : altLocale.to"
>
{{ altLocale.label }}
</nuxt-link>
</section>
<section class="filter">
<input
type="text"
placeholder="Search…"
class="search"
>
</section>
<menu class="menu">
<template v-for="(item, i) in nav">
<li
:key="`menu-${i}`"
class="menu-item"
>
<nuxt-link
v-if="item.link !== false"
class="menu-link"
:exact="item.exact"
:to="getLocalePath(`/${item.slug}`)"
>
{{ item.title }}
</nuxt-link>
<span
v-else
class="menu-link"
>{{ item.title }}</span>
<menu
v-if="item.children && item.children.length"
class="menu"
>
<template
v-for="(subItem, j) in item.children"
>
<li
v-if="!subItem.hidden"
:key="`sub-${j}`"
class="menu-item"
>
<nuxt-link
:class="{
'menu-link': true,
'menu-link-disabled': subItem.disabled,
'menu-link-sub': subItem.sub,
'menu-link-active': isActive(`/${item.slug}/${subItem.slug}`)
}"
:exact="subItem.exact"
:to="subItem.disabled ? '/' : getLocalePath(`/${item.slug}/${subItem.slug}`)"
v-html="getTitleHTML(subItem.title)"
/>
</li>
</template>
</menu>
</li>
</template>
</menu>
</nav>
</aside>
</template>
<script>
import { escape } from 'lodash'
import i18n from '../common/i18n'
export default {
name: 'one-menu',
mixins: [i18n],
props: {
nav: {
type: Array,
default () {
return []
}
}
},
computed: {
altLocale () {
let { canonicalPath, locale, getLocalePath, isPathDisabled } = this
let altLocale = locale === 'zh-Hans' ? 'en-US' : 'zh-Hans'
let label = locale === 'zh-Hans' ? 'English' : '中文'
let disabled = isPathDisabled(canonicalPath, altLocale)
return {
to: disabled ? '' : getLocalePath(canonicalPath, altLocale),
disabled,
label
}
}
},
watch: {
$route: 'scrollActiveIntoView'
},
mounted () {
this.scrollActiveIntoView()
},
beforeDestroy () {
clearTimeout(this.timer)
},
methods: {
getTitleHTML (title) {
let [main, sub] = title.split(' - ')
return escape(main) + (sub ? `<small>${escape(sub)}</small>` : '')
},
isActive (path) {
let { route = {} } = this.$router.resolve(path) || {}
return route.name === this.$route.name
},
scrollActiveIntoView () {
this.timer = setTimeout(() => {
if (!this.$el) {
return
}
let active =
this.$el.querySelector('.nuxt-link-exact-active') ||
this.$el.querySelector('.menu-link-active')
if (!active) {
return
}
let menu = active.offsetParent
if (!menu) {
return
}
if (
active.offsetTop < menu.scrollTop ||
active.offsetTop + active.offsetHeight > menu.scrollTop
) {
active.scrollIntoView({
behavior: 'smooth',
block: 'nearest'
})
}
})
}
}
}
</script>
<style lang="stylus" scoped>
.one-nav
position fixed
top 60px
bottom 0
left 0
z-index 1
padding-top 30px
border-right 1px solid #e5e5e5
.primary
margin-left -250px
.secondary
height 100%
position relative
display flex
justify-content stretch
flex-direction column
float left
width 240px
h2
display flex
align-items center
margin 0 0 0 20px
font-size 20px
font-weight 500
span
position relative
small
position absolute
font-size 16px
font-weight 400
transform scale(0.75) translateY(-3px)
margin-left 3px
opacity 0.7
a
display block
& + .desc
display flex
align-items center
margin-top 15px
margin-left 20px
img
display block
.locale-swith
display block
margin-left 12px
padding 0 6px
border 1px solid #dbdbdb
border-radius 3px
line-height 18px
font-size 12px
text-align center
text-decoration none
transition all 0.2s
&:hover
border-color #999
.filter
margin-top 20px
margin-left 20px
.search
display block
width 180px
height 32px
padding 0 7px
border 1px solid #dbdbdb
border-radius 4px
outline none
font-size 13px
transition all 0.2s
&.focus-visible
border-color #999
box-shadow 0 0 0 2px rgba(0, 0, 0, 0.15)
& > .menu
position relative
width 100%
flex 1 1 auto
margin-top 25px
padding-left 20px
overflow auto
.menu
.menu-item
.menu-link
float left
clear left
.menu .menu
margin 3.5px 0
.menu-item
margin 3.5px 0
font-size 16px
.menu-item
font-size 13px
.menu-link
color #333
font-weight 400
& >>> small
color #999
font-size 13px
margin-left 10px
white-space nowrap
&::after
display block
.menu-link
float left
clear left
color #333
font-weight 500
padding 9px 0
text-decoration none
&-disabled
opacity 0.3
pointer-events none
// &-sub
// margin-left 10px
&::after
background-color #999
.nuxt-link-exact-active::after
.menu-link-active::after
width 100%
left 0
background-color #333
.toggle
margin-right 15px
font-size 13px
vertical-align middle
.disabled
opacity 0.3
pointer-events none
</style>

96
layouts/default.vue Normal file
View File

@ -0,0 +1,96 @@
<template>
<main
:class="{
'post-layout': true,
'no-links': !hasFooterLinks
}"
>
<one-header/>
<one-menu :nav="nav"/>
<nuxt/>
<one-footer
class="footer"
:nav="nav"
@update="updateLayout"
/>
<one-back-to-top/>
</main>
</template>
<script>
import 'focus-visible'
import OneHeader from '../components/OneHeader'
import OneMenu from '../components/OneMenu'
import OneFooter from '../components/OneFooter'
import OneBackToTop from '../components/OneBackToTop'
import nav from '../assets/data/nav.json'
import i18n from '../common/i18n'
import i18nMgr from 'veui/managers/i18n'
export default {
name: 'main-doc',
components: {
OneHeader,
OneMenu,
OneFooter,
OneBackToTop
},
mixins: [i18n],
data () {
return {
hasFooterLinks: true
}
},
computed: {
nav () {
return nav[this.locale]
}
},
watch: {
locale: {
handler (val) {
if (i18nMgr.locale !== val) {
i18nMgr.locale = val
}
if (this.$i18n.locale !== val) {
this.$i18n.locale = val
}
if (process.env.VUE_ENV !== 'server') {
document.documentElement.setAttribute('lang', val)
const { docsearchInstance } = window
if (docsearchInstance) {
docsearchInstance.autocomplete
.eq(0)
.data('aaAutocomplete')
.dropdown.datasets[0].clearCachedSuggestions()
docsearchInstance.client.clearCache()
docsearchInstance.algoliaOptions.facetFilters = [`lang:${val}`]
}
}
},
immediate: true
}
},
methods: {
updateLayout ({ hasLinks }) {
this.hasFooterLinks = hasLinks
}
}
}
</script>
<style lang="stylus" scoped>
$sidebar-width = 240px
main
height 100%
.content
margin-top 60px
.content, .footer
max-width 1180px - $sidebar-width
min-width 560px
transition margin-left 0.5s cubic-bezier(0.785, 0.135, 0.15, 0.86)
</style>

9
middleware/README.md Normal file
View File

@ -0,0 +1,9 @@
# MIDDLEWARE
This directory contains your Application Middleware.
The middleware lets you define custom function to be ran before rendering a page or a group of pages (layouts).
More information about the usage of this directory in the documentation:
https://nuxtjs.org/guide/routing#middleware
**This directory is not required, you can delete it if you don't want to use it.**

125
nuxt.config.js Normal file
View File

@ -0,0 +1,125 @@
const path = require('path')
function resolve (p) {
return path.resolve(__dirname, p)
}
function appendLoader (config, loader) {
config.module.rules.push(loader)
}
module.exports = {
target: 'static',
/**
* Headers of the page
*/
head: {
title: 'VEUI',
meta: [
{ charset: 'utf-8' },
{ name: 'viewport', content: 'width=device-width, initial-scale=1' },
{
hid: 'description',
name: 'description',
content: 'Website for VEUI: an enterprise component library for Vue.js.'
}
],
link: [
{ rel: 'shortcut icon', href: 'https://www.baidu.com/favicon.ico' },
{
rel: 'stylesheet',
href:
'https://code.bdstatic.com/npm/docsearch.js@2.6.3/dist/cdn/docsearch.min.css'
}
],
script: [
{
src:
'https://code.bdstatic.com/npm/docsearch.js@2.6.3/dist/cdn/docsearch.min.js',
body: true
}
]
},
/**
* Customize the progress bar color
*/
loading: { color: '#1e1f24' },
pageTransition: {
css: false
},
css: ['veui-theme-dls/common.less', '@/assets/styles/global.styl'],
plugins: [
{ src: '~plugins/i18n.js' },
{ src: '~plugins/l10n.js' },
{ src: '~plugins/hm.js', ssr: false },
{ src: '~plugins/algolia.js', ssr: false }
],
generate: {
subFolders: false
},
/**
* Build configuration
*/
build: {
transpile: ['veui', 'vue-awesome', 'resize-detector', 'less-plugin-dls'],
babel: {
plugins: ['veui', 'lodash']
},
loaders: {
vue: {
compilerOptions: {
whitespace: 'condense'
}
},
stylus: {
'include css': true
},
less: {
javascriptEnabled: true
}
},
extend (config) {
/**
* veui-loader
*/
appendLoader(config, {
enforce: 'pre',
test: /\.vue$/,
loader: 'veui-loader',
options: {
locale: ['zh-Hans', 'en-US'],
modules: [
{
package: 'veui-theme-dls',
fileName: '{module}.less'
},
{
package: 'veui-theme-dls',
fileName: '{module}.js',
transform: false
}
]
},
include: [resolve('pages'), resolve('node_modules/veui')]
})
appendLoader(config, {
test: /\.js$/,
include: [resolve('node_modules/focus-visible')],
loader: 'short-circuit-loader',
options: {
expr: "process.env.VUE_ENV === 'server'"
}
})
}
}
}

226
one/build/customBlock.js Normal file
View File

@ -0,0 +1,226 @@
'use strict'
var trim = require('trim-trailing-lines')
module.exports = customBlock
var C_NEWLINE = '\n'
var C_TAB = '\t'
var C_SPACE = ' '
var C_COLON = ':'
var MIN_FENCE_COUNT = 3
var CODE_INDENT_COUNT = 4
function customBlock (eat, value, silent) {
var self = this
var length = value.length + 1
var index = 0
var subvalue = ''
var fenceCount
var marker
var character
var flag
var queue
var content
var exdentedContent
var closing
var exdentedClosing
var indent
var now
/* Eat initial spacing. */
while (index < length) {
character = value.charAt(index)
if (character !== C_SPACE && character !== C_TAB) {
break
}
subvalue += character
index++
}
indent = index
/* Eat the fence. */
character = value.charAt(index)
if (character !== C_COLON) {
return
}
index++
marker = character
fenceCount = 1
subvalue += character
while (index < length) {
character = value.charAt(index)
if (character !== marker) {
break
}
subvalue += character
fenceCount++
index++
}
if (fenceCount < MIN_FENCE_COUNT) {
return
}
/* Eat spacing before flag. */
while (index < length) {
character = value.charAt(index)
if (character !== C_SPACE && character !== C_TAB) {
break
}
subvalue += character
index++
}
/* Eat flag. */
flag = ''
queue = ''
while (index < length) {
character = value.charAt(index)
if (character === C_NEWLINE || character === C_COLON) {
break
}
if (character === C_SPACE || character === C_TAB) {
queue += character
} else {
flag += queue + character
queue = ''
}
index++
}
character = value.charAt(index)
if (character && character !== C_NEWLINE) {
return
}
if (silent) {
return true
}
now = eat.now()
now.column += subvalue.length
now.offset += subvalue.length
subvalue += flag
flag = self.decode.raw(self.unescape(flag), now)
if (queue) {
subvalue += queue
}
queue = ''
closing = ''
exdentedClosing = ''
content = ''
exdentedContent = ''
/* Eat content. */
while (index < length) {
character = value.charAt(index)
content += closing
exdentedContent += exdentedClosing
closing = ''
exdentedClosing = ''
if (character !== C_NEWLINE) {
content += character
exdentedClosing += character
index++
continue
}
/* Add the newline to `subvalue` if its the first
* character. Otherwise, add it to the `closing`
* queue. */
if (content) {
closing += character
exdentedClosing += character
} else {
subvalue += character
}
queue = ''
index++
while (index < length) {
character = value.charAt(index)
if (character !== C_SPACE) {
break
}
queue += character
index++
}
closing += queue
exdentedClosing += queue.slice(indent)
if (queue.length >= CODE_INDENT_COUNT) {
continue
}
queue = ''
while (index < length) {
character = value.charAt(index)
if (character !== marker) {
break
}
queue += character
index++
}
closing += queue
exdentedClosing += queue
if (queue.length < fenceCount) {
continue
}
queue = ''
while (index < length) {
character = value.charAt(index)
if (character !== C_SPACE && character !== C_TAB) {
break
}
closing += character
exdentedClosing += character
index++
}
if (!character || character === C_NEWLINE) {
break
}
}
subvalue += content + closing
return eat(subvalue)({
type: 'customblock',
className: (flag || '').trim().replace(/\s+/g, ' '),
value: trim(exdentedContent)
})
}

48
one/build/deps.js Normal file
View File

@ -0,0 +1,48 @@
import path from 'path'
import { readFileSync, writeFileSync } from './util'
import { merge } from 'lodash'
function load () {
try {
return JSON.parse(readFileSync(resolve('./deps.json')))
} catch (e) {
return {}
}
}
function save (deps) {
writeFileSync(resolve('./deps.json'), JSON.stringify(deps, null, ' '))
}
function resolve (file) {
return path.resolve(__dirname, file)
}
export function get (file) {
let deps = load()
return deps[file]
}
export function add (data) {
let deps = load()
save(merge(deps, data))
}
export function remove (data) {
let deps = load()
Object.keys(data).forEach(key => {
if (deps[key]) {
delete deps[key][data[key]]
}
})
save(deps)
}
export function removeFile (file) {
let deps = load()
delete deps[file]
Object.keys(deps).forEach(key => {
delete deps[key][file]
})
}

226
one/build/details.js Normal file
View File

@ -0,0 +1,226 @@
'use strict'
var trim = require('trim-trailing-lines')
module.exports = details
var C_NEWLINE = '\n'
var C_TAB = '\t'
var C_SPACE = ' '
var C_PLUS = '+'
var MIN_FENCE_COUNT = 3
var CODE_INDENT_COUNT = 4
function details (eat, value, silent) {
var self = this
var length = value.length + 1
var index = 0
var subvalue = ''
var fenceCount
var marker
var character
var flag
var queue
var content
var exdentedContent
var closing
var exdentedClosing
var indent
var now
/* Eat initial spacing. */
while (index < length) {
character = value.charAt(index)
if (character !== C_SPACE && character !== C_TAB) {
break
}
subvalue += character
index++
}
indent = index
/* Eat the fence. */
character = value.charAt(index)
if (character !== C_PLUS) {
return
}
index++
marker = character
fenceCount = 1
subvalue += character
while (index < length) {
character = value.charAt(index)
if (character !== marker) {
break
}
subvalue += character
fenceCount++
index++
}
if (fenceCount < MIN_FENCE_COUNT) {
return
}
/* Eat spacing before flag. */
while (index < length) {
character = value.charAt(index)
if (character !== C_SPACE && character !== C_TAB) {
break
}
subvalue += character
index++
}
/* Eat flag. */
flag = ''
queue = ''
while (index < length) {
character = value.charAt(index)
if (character === C_NEWLINE || character === C_PLUS) {
break
}
if (character === C_SPACE || character === C_TAB) {
queue += character
} else {
flag += queue + character
queue = ''
}
index++
}
character = value.charAt(index)
if (character && character !== C_NEWLINE) {
return
}
if (silent) {
return true
}
now = eat.now()
now.column += subvalue.length
now.offset += subvalue.length
subvalue += flag
flag = self.decode.raw(self.unescape(flag), now)
if (queue) {
subvalue += queue
}
queue = ''
closing = ''
exdentedClosing = ''
content = ''
exdentedContent = ''
/* Eat content. */
while (index < length) {
character = value.charAt(index)
content += closing
exdentedContent += exdentedClosing
closing = ''
exdentedClosing = ''
if (character !== C_NEWLINE) {
content += character
exdentedClosing += character
index++
continue
}
/* Add the newline to `subvalue` if its the first
* character. Otherwise, add it to the `closing`
* queue. */
if (content) {
closing += character
exdentedClosing += character
} else {
subvalue += character
}
queue = ''
index++
while (index < length) {
character = value.charAt(index)
if (character !== C_SPACE) {
break
}
queue += character
index++
}
closing += queue
exdentedClosing += queue.slice(indent)
if (queue.length >= CODE_INDENT_COUNT) {
continue
}
queue = ''
while (index < length) {
character = value.charAt(index)
if (character !== marker) {
break
}
queue += character
index++
}
closing += queue
exdentedClosing += queue
if (queue.length < fenceCount) {
continue
}
queue = ''
while (index < length) {
character = value.charAt(index)
if (character !== C_SPACE && character !== C_TAB) {
break
}
closing += character
exdentedClosing += character
index++
}
if (!character || character === C_NEWLINE) {
break
}
}
subvalue += content + closing
return eat(subvalue)({
type: 'details',
summary: flag || null,
value: trim(exdentedContent)
})
}

3
one/build/generate.js Normal file
View File

@ -0,0 +1,3 @@
import { generatePages } from './generator'
generatePages()

105
one/build/generator.js Normal file
View File

@ -0,0 +1,105 @@
import { statSync } from 'fs'
import { resolve, relative, extname, basename, sep } from 'path'
import readdirpSync from 'recursive-readdir-sync'
import rimraf from 'rimraf'
import { copyFileSync, replaceExtSync } from './util'
import { renderDocToPage } from './page'
import { get, removeFile } from './deps'
const DOCS_DIR = resolve(__dirname, '../docs')
const PAGES_DIR = resolve(__dirname, '../../pages')
const DEMOS_DIR = resolve(__dirname, '../../components/demos')
const MERMAID_DIR = resolve(__dirname, '../../static/images/mermaid')
const ASSETS_DIR = resolve(__dirname, '../../assets')
export function generatePages (file, stats) {
if (!file) {
rimraf.sync(PAGES_DIR)
rimraf.sync(DEMOS_DIR)
rimraf.sync(MERMAID_DIR)
rimraf.sync(resolve(__dirname, './deps.json'))
console.log('Regenerating all files...')
handleFile(DOCS_DIR)
console.log('...done.')
} else {
handleFile(file, stats)
}
}
function handleFile (file, stats) {
let segments = relative(DOCS_DIR, file).split(sep)
if (segments.some(segment => {
return segment.startsWith('_') || segment.startsWith('.')
})) {
return
}
let remove = stats ? stats.remove : false
let dir = stats ? stats.dir : statSync(file).isDirectory()
if (dir) {
if (remove) {
rimraf.sync(file)
return
}
let children = readdirpSync(file)
children.forEach(child => {
handleFile(child, remove)
})
return
}
let ext = extname(file).toLowerCase()
/* eslint-disable indent */
/* There seems to be something wrong with FECS here */
switch (ext) {
case '.md': {
if (remove) {
let relDest = replaceExtSync(relative(DOCS_DIR, file), 'vue')
rimraf.sync(resolve(PAGES_DIR, relDest))
console.log(`[${relDest}] removed.`)
} else {
let dest = relative(DOCS_DIR, file)
renderDocToPage(dest)
console.log(`[${dest}] synced.`)
}
break
}
case '.json': {
if (basename(file) === 'nav.json') {
copyFileSync(file, resolve(ASSETS_DIR, 'data', 'nav.json'))
console.log('[nav.json] synced.')
}
break
}
default: {
let relDest = relative(DOCS_DIR, file)
let dest = relDest.split(sep).indexOf('demo') === -1
? resolve(PAGES_DIR, relDest)
: resolve(DEMOS_DIR, relDest)
if (remove) {
rimraf.sync(dest)
console.log(`[${relDest}] removed.`)
} else {
copyFileSync(file, dest)
console.log(`[${relDest}] synced.`)
}
break
}
}
/* eslint-enable indent */
if (remove) {
removeFile(file)
return
}
let deps = get(file)
if (deps) {
Object.keys(deps).forEach(dep => {
handleFile(dep)
})
}
}

13
one/build/i18n.js Normal file
View File

@ -0,0 +1,13 @@
export const DEFAULT_LOCALE = 'zh-Hans'
export const LOCALES = [
{
code: DEFAULT_LOCALE,
label: '简体中文'
},
{
code: 'en-US',
label: 'English (US)'
}
]
export const LOCALE_CODES = LOCALES.map(l => l.code)
export const RE_LOCALE = new RegExp(`^\\/(${LOCALE_CODES.join('|')})\\/`)

99
one/build/language.js Normal file
View File

@ -0,0 +1,99 @@
/* eslint-disable fecs-camelcase */
/* eslint-disable babel/new-cap */
export function vue (hljs) {
const XML_IDENT_RE = '[A-Za-z0-9\\._:-]+'
const TAG_INTERNALS = {
endsWithParent: true,
illegal: /</,
relevance: 0,
contains: [
{
className: 'attr',
begin: XML_IDENT_RE,
relevance: 0
},
{
begin: /=\s*/,
relevance: 0,
contains: [
{
className: 'string',
endsParent: true,
variants: [
{begin: /"/, end: /"/},
{begin: /'/, end: /'/},
{begin: /[^\s"'=<>`]+/}
]
}
]
}
]
}
return {
case_insensitive: true,
contains: [
hljs.COMMENT(
'<!--',
'-->',
{
relevance: 10
}
),
{
className: 'tag',
/*
The lookahead pattern (?=...) ensures that 'begin' only matches
'<style' as a single word, followed by a whitespace or an
ending braket. The '$' is needed for the lexeme to be recognized
by hljs.subMode() that tests lexemes outside the stream.
*/
begin: '<style(?=\\s|>|$)',
end: '>',
keywords: {name: 'style'},
contains: [TAG_INTERNALS],
starts: {
end: '</style>',
returnEnd: true,
subLanguage: ['css', 'less', 'scss', 'stylus']
}
},
{
className: 'tag',
// See the comment in the <style tag about the lookahead pattern
begin: '<script(?=\\s|>|$)',
end: '>',
keywords: {name: 'script'},
contains: [TAG_INTERNALS],
starts: {
end: '</script>',
returnEnd: true,
subLanguage: ['javascript']
}
},
{
className: 'tag',
// See the comment in the <style tag about the lookahead pattern
begin: '<template(?=\\s|>|$)',
end: '>',
keywords: {name: 'template'},
contains: [TAG_INTERNALS],
starts: {
end: '</template>',
returnEnd: true,
subLanguage: ['html']
}
},
{
className: 'tag',
begin: '</?',
end: '/?>',
contains: [
{
className: 'name', begin: /[^/><\s]+/, relevance: 0
},
TAG_INTERNALS
]
}
]
}
}

94
one/build/page.js Normal file
View File

@ -0,0 +1,94 @@
import { resolve, relative, join } from 'path'
import vfile from 'vfile'
import remark from 'remark'
import slug from 'remark-slug'
import frontmatter from 'remark-frontmatter'
import highlight from 'remark-highlight.js'
import shortcodes from 'remark-shortcodes'
import mermaid from 'one-remark-mermaid'
import remarkToRehype from 'remark-rehype'
import raw from 'rehype-raw'
import html from 'rehype-stringify'
import etpl from 'etpl'
import { readFileSync, writeFileSync, replaceExtSync } from './util'
import demo from './remark-demo'
import ref from './remark-ref'
import details from './remark-details'
import custom from './remark-custom'
import extractFrontmatter from './remark-extract-frontmatter'
import rehypePreviewImg from './rehype-preview-img'
import rehypeLink from './rehype-link'
import rehypeDemo from './rehype-demo'
import { add } from './deps'
import lowlight from 'lowlight'
import { vue } from './language'
const DOCS_DIR = resolve(__dirname, '../docs')
const PAGES_DIR = resolve(__dirname, '../../pages')
const STYLES_DIR = resolve(__dirname, '../../assets/styles')
const MERMAID_DIR = resolve(__dirname, '../../static/images/mermaid')
const PAGE_TPL = readFileSync(resolve(__dirname, '../templates/page.etpl'))
const renderPage = etpl.compile(PAGE_TPL)
lowlight.registerLanguage('vue', vue)
const md = remark()
.use(custom)
.use(details)
.use(ref)
.use(frontmatter)
.use(shortcodes)
.use(mermaid, {
cssFile: join(`${STYLES_DIR}`, 'mermaid-cli.css'),
theme: 'none'
})
.use(demo)
.use(extractFrontmatter)
.use(highlight)
.use(slug)
.use(remarkToRehype, { allowDangerousHTML: true })
.use(raw)
.use(rehypePreviewImg)
.use(rehypeLink)
.use(rehypeDemo)
.use(html, { allowDangerousHTML: true })
export function render (contents, path, data = {}) {
data.destinationDir = MERMAID_DIR
return md.processSync(vfile({ contents, path, data }))
}
function renderFile (file) {
return render(readFileSync(file), file)
}
export function renderDocToPage (file) {
let src = resolve(DOCS_DIR, file)
let dest = resolve(PAGES_DIR, replaceExtSync(file, 'vue'))
let { contents, data } = renderFile(src, dest)
let { demos = {}, components = {}, meta = {}, deps = {} } = data
Object.keys(deps || {}).forEach(dep => {
add({ [dep]: { [src]: true } })
})
let { layout, style } = meta
let componentList = Object.keys(components)
let demoList = Object.keys(demos)
let result = renderPage({
content: (contents || '').replace(/\n{3,}/g, '\n\n'),
demos: demoList.map(name => {
return {
name,
src: join('@/components/demos', relative(DOCS_DIR, demos[name].path))
}
}),
components: componentList,
boilerplate: demoList.length || componentList.length,
layout,
style: style || 'post'
})
writeFileSync(dest, result)
}

226
one/build/refBlock.js Normal file
View File

@ -0,0 +1,226 @@
'use strict'
var trim = require('trim-trailing-lines')
module.exports = refBlock
var C_NEWLINE = '\n'
var C_TAB = '\t'
var C_SPACE = ' '
var C_CARET = '^'
var MIN_FENCE_COUNT = 3
var CODE_INDENT_COUNT = 4
function refBlock (eat, value, silent) {
var self = this
var length = value.length + 1
var index = 0
var subvalue = ''
var fenceCount
var marker
var character
var flag
var queue
var content
var exdentedContent
var closing
var exdentedClosing
var indent
var now
/* Eat initial spacing. */
while (index < length) {
character = value.charAt(index)
if (character !== C_SPACE && character !== C_TAB) {
break
}
subvalue += character
index++
}
indent = index
/* Eat the fence. */
character = value.charAt(index)
if (character !== C_CARET) {
return
}
index++
marker = character
fenceCount = 1
subvalue += character
while (index < length) {
character = value.charAt(index)
if (character !== marker) {
break
}
subvalue += character
fenceCount++
index++
}
if (fenceCount < MIN_FENCE_COUNT) {
return
}
/* Eat spacing before flag. */
while (index < length) {
character = value.charAt(index)
if (character !== C_SPACE && character !== C_TAB) {
break
}
subvalue += character
index++
}
/* Eat flag. */
flag = ''
queue = ''
while (index < length) {
character = value.charAt(index)
if (character === C_NEWLINE || character === C_CARET) {
break
}
if (character === C_SPACE || character === C_TAB) {
queue += character
} else {
flag += queue + character
queue = ''
}
index++
}
character = value.charAt(index)
if (character && character !== C_NEWLINE) {
return
}
if (silent) {
return true
}
now = eat.now()
now.column += subvalue.length
now.offset += subvalue.length
subvalue += flag
flag = self.decode.raw(self.unescape(flag), now)
if (queue) {
subvalue += queue
}
queue = ''
closing = ''
exdentedClosing = ''
content = ''
exdentedContent = ''
/* Eat content. */
while (index < length) {
character = value.charAt(index)
content += closing
exdentedContent += exdentedClosing
closing = ''
exdentedClosing = ''
if (character !== C_NEWLINE) {
content += character
exdentedClosing += character
index++
continue
}
/* Add the newline to `subvalue` if its the first
* character. Otherwise, add it to the `closing`
* queue. */
if (content) {
closing += character
exdentedClosing += character
} else {
subvalue += character
}
queue = ''
index++
while (index < length) {
character = value.charAt(index)
if (character !== C_SPACE) {
break
}
queue += character
index++
}
closing += queue
exdentedClosing += queue.slice(indent)
if (queue.length >= CODE_INDENT_COUNT) {
continue
}
queue = ''
while (index < length) {
character = value.charAt(index)
if (character !== marker) {
break
}
queue += character
index++
}
closing += queue
exdentedClosing += queue
if (queue.length < fenceCount) {
continue
}
queue = ''
while (index < length) {
character = value.charAt(index)
if (character !== C_SPACE && character !== C_TAB) {
break
}
closing += character
exdentedClosing += character
index++
}
if (!character || character === C_NEWLINE) {
break
}
}
subvalue += content + closing
return eat(subvalue)({
type: 'refblock',
id: flag || null,
value: trim(exdentedContent)
})
}

54
one/build/rehype-demo.js Normal file
View File

@ -0,0 +1,54 @@
import visit from 'unist-util-visit'
import h from 'hastscript'
const RE_DEMO = /^one-demo-[a-f0-9]+/i
export default function attacher () {
return (tree, { data }) => {
visit(tree, 'element', (node, index, parent) => {
let { tagName } = node
let [name] = tagName.match(RE_DEMO) || []
if (name) {
let { code, desc, browser } = data.demos[name] || {}
if (!code) {
return
}
let demo = h('one-demo',
{
browser
},
[
node,
h(
'template',
{
slot: 'source'
},
h(
'div',
{
'v-pre': true
},
{
type: 'raw',
value: code
}
)
),
h(
'template',
{
slot: 'desc'
},
{
type: 'raw',
value: desc
}
)
])
parent.children.splice(index, 1, demo)
}
})
}
}

26
one/build/rehype-link.js Normal file
View File

@ -0,0 +1,26 @@
import { resolve, relative } from 'path'
import visit from 'unist-util-visit'
import { RE_LOCALE } from './i18n'
const DOCS_DIR = resolve(__dirname, '../docs')
export default function attacher () {
return (tree, { path }) => {
let localPath = `/${relative(DOCS_DIR, path)}`
let [, locale] = localPath.match(RE_LOCALE) || []
if (!locale) {
return
}
visit(tree, 'element', node => {
let { tagName, properties, properties: { href } } = node
if (tagName !== 'a' || href.match(/^\w+:\/\//)) {
return
}
if (locale && href.indexOf('/') === 0) {
properties.href = `/${locale}${href}`
}
})
}
}

98
one/build/rehype-preview-img.js Normal file
View File

@ -0,0 +1,98 @@
import { resolve, join } from 'path'
import visit from 'unist-util-visit'
import h from 'hastscript'
import { removeClass, addClass, hasClass } from './rehype-util-class'
import { readFileSync } from './util'
const RE_SPACE = /[\w\r\n]*/
const MERMAID_DIR = resolve(__dirname, '../../static/images/mermaid')
export default function attacher () {
return tree => {
visit(tree, 'element', (node, index, { children }) => {
let { tagName, properties, properties: { src, alt, title, className } } = node
if (tagName !== 'img' || src.match(/^\w+:\/\//)) {
return
}
if (title && title.indexOf('mermaid') !== -1) {
let fig = h(
'figure.hero.mermaid',
{
'v-once': true
},
{
type: 'raw',
value: readFileSync(join(MERMAID_DIR, src))
}
)
children.splice(index, 1, fig)
return
}
src = src.replace(/(\.\.)?\/assets\//g, '/images/content/')
if (hasClass(node, 'preview')) {
removeClass(node, 'preview')
let fig = h(`figure${hasClass(node, 'hero') ? '.hero' : ''}`, [
h('div.preview', [
h('img', {
src,
alt,
title,
className,
srcset: `${src} 2x`
})
]),
...(title || alt) ? [
h('figcaption', [
...title ? [
h('p.caption', title)
] : [],
...alt ? [
h('p.desc', alt)
] : []
])
] : []
])
children.splice(index, 1, fig)
if (hasClass(node, 'bad')) {
removeClass(node, 'bad')
addClass(fig, 'bad')
let prev
let prevIndex = index - 1
while (true) {
prev = children[prevIndex]
if (!prev) {
break
}
// skip whitespace-only text nodes
if (prev.type === 'text' && RE_SPACE.test(prev.value)) {
prevIndex--
continue
}
break
}
if (prev) {
let prevPreview = (prev.children || [])[0]
if (prevPreview && hasClass(prevPreview, 'preview')) {
let prevImg = (prevPreview.children || [])[0]
if (hasClass(prevImg, 'good')) {
removeClass(prevImg, 'good')
addClass(prev, 'good')
children.splice(index - 1, 2, h('div.comparison', [prev, fig]))
}
}
}
}
} else {
properties.src = src
properties.srcset = `${src} 2x`
if (className && !className.length) {
delete properties.className
}
}
})
}
}

36
one/build/rehype-util-class.js Normal file
View File

@ -0,0 +1,36 @@
import { remove, get, set } from 'lodash'
const CLASSNAME_PATH = 'properties.className'
export function toggleClass (node, name, add) {
let className = get(node, CLASSNAME_PATH)
if (!className) {
set(node, CLASSNAME_PATH, [])
className = node.properties.className
}
if (typeof add === 'boolean') {
if (add && !className.includes(name)) {
className.push(name)
} else if (!add) {
remove(className, c => c === name)
}
} else if (className.includes(name)) {
remove(className, c => c === name)
} else {
className.push(name)
}
}
export function addClass (node, name) {
toggleClass(node, name, true)
}
export function removeClass (node, name) {
toggleClass(node, name, false)
}
export function hasClass (node, name) {
let className = get(node, CLASSNAME_PATH, [])
return className.includes(name)
}

30
one/build/remark-custom.js Normal file
View File

@ -0,0 +1,30 @@
import tokenizer from './customBlock'
import visit from 'unist-util-visit'
import { render } from './page'
const NAME = 'customblock'
export default function attacher () {
let proto = this.Parser.prototype
proto.blockTokenizers[NAME] = tokenizer
proto.interruptParagraph.push([NAME])
proto.interruptList.push([NAME])
proto.interruptBlockquote.push([NAME])
let methods = proto.blockMethods
methods.unshift(NAME)
return (tree, file) => {
let { path } = file
visit(tree, NAME, ({ className, value }, index, parent) => {
let { contents } = render(value, path, {})
className = className ? `${className} custom-block` : 'custom-block'
parent.children.splice(index, 1, {
type: 'html',
value: `<div class="${className}">${contents}</div>`
})
})
}
}

125
one/build/remark-demo.js Normal file
View File

@ -0,0 +1,125 @@
import { resolve, relative, dirname } from 'path'
import { existsSync } from 'fs'
import visit from 'unist-util-visit'
import { readFileSync, hash } from './util'
import { render } from './page'
import { parseComponent } from 'vue-template-compiler'
import { escape } from 'lodash'
import { RE_LOCALE } from './i18n'
const DOCS_DIR = resolve(__dirname, '../docs')
export default function attacher () {
return (tree, file) => {
let { path, data: fileData } = file
visit(tree, 'shortcode', node => {
let {
identifier,
data: nodeData,
attributes: { src, browser } = {}
} = node
if (identifier !== 'demo' || !src) {
return
}
if (!nodeData) {
node.data = nodeData = {}
}
if (!fileData) {
file.data = fileData = {}
}
if (!fileData.demos) {
fileData.demos = {}
}
if (!fileData.deps) {
fileData.deps = {}
}
let demoPath =
src.indexOf('/') === 0
? resolve(DOCS_DIR, src.slice(1))
: resolve(dirname(path), src)
if (!existsSync(demoPath)) {
console.warn(`Demo not found at '${demoPath}'`)
return
}
fileData.deps[demoPath] = true
let name = getComponentName(demoPath)
nodeData.hName = name
let localPath = `/${relative(DOCS_DIR, path)}`
let [, locale] = localPath.match(RE_LOCALE) || []
let { content, doc } = extractDoc(demoPath, { locale })
fileData.demos[name] = {
path: demoPath,
browser,
code: render('```vue\n' + content + '\n```', demoPath).contents,
desc: render(doc, demoPath).contents
}
})
}
}
function getComponentName (path) {
return `one-demo-${hash(path)}`
}
function extractDoc (file, { locale }) {
let content = readFileSync(file)
let vueComponent = parseComponent(content)
let { customBlocks } = vueComponent
let i = customBlocks.findIndex(({ type, attrs }) => {
return ((locale && locale === attrs.locale) || !locale) && type === 'docs'
})
let doc = null
if (i !== -1) {
doc = customBlocks[i].content
}
return {
content: stringifyVueComponent(vueComponent),
doc
}
}
function stringifyVueComponent (component) {
let content = []
let { template, script, styles } = component
if (template) {
content.push(
`<template${stringifyAttrs(template.attrs)}>${
template.content
}</template>`
)
}
if (script) {
content.push(
`<script${stringifyAttrs(script.attrs)}>${script.content}</script>`
)
}
styles.filter(({ attrs }) => !attrs.docs).forEach(style => {
content.push(
`<style${stringifyAttrs(style.attrs)}>${style.content}</style>`
)
})
return content.join('\n\n')
}
function stringifyAttrs (attrs) {
let result = Object.keys(attrs)
.map(key => {
let val = attrs[key]
if (typeof val !== 'boolean') {
return `${escape(key)}="${escape(val)}"`
}
return val ? `${escape(key)}` : ''
})
.join(' ')
return result ? ` ${result}` : ''
}

39
one/build/remark-details.js Normal file
View File

@ -0,0 +1,39 @@
import tokenizer from './details'
import visit from 'unist-util-visit'
import { escape } from 'lodash'
import { render } from './page'
const NAME = 'details'
export default function attacher () {
let proto = this.Parser.prototype
proto.blockTokenizers[NAME] = tokenizer
proto.interruptParagraph.push([NAME])
proto.interruptList.push([NAME])
proto.interruptBlockquote.push([NAME])
let methods = proto.blockMethods
methods.unshift(NAME)
return (tree, file) => {
let { path, data } = file
if (!data) {
file.data = data = {}
}
if (!data.components) {
data.components = {}
}
visit(tree, NAME, ({ summary, value }, index, parent) => {
data.components['OneDetails'] = true
let { contents } = render(value, path, data)
parent.children.splice(index, 1, {
type: 'html',
value: `<one-details summary="${escape(summary)}">${contents}</one-details>`
})
})
}
}

16
one/build/remark-extract-frontmatter.js Normal file
View File

@ -0,0 +1,16 @@
import visit from 'unist-util-visit'
import remove from 'unist-util-remove'
import yaml from 'js-yaml'
export default function attacher () {
return (tree, file) => {
let { data } = file
visit(tree, 'yaml', node => {
data.meta = yaml.safeLoad(node.value)
return visit.EXIT
})
remove(tree, ['yaml', 'toml'])
}
}

49
one/build/remark-ref.js Normal file
View File

@ -0,0 +1,49 @@
import tokenizer from './refBlock'
import visit from 'unist-util-visit'
import remove from 'unist-util-remove'
import { render } from './page'
const NAME = 'refblock'
const RE_REF = /^\^([-_a-z0-9]+)/i
export default function attacher () {
let proto = this.Parser.prototype
proto.blockTokenizers[NAME] = tokenizer
proto.interruptParagraph.push([NAME])
proto.interruptList.push([NAME])
proto.interruptBlockquote.push([NAME])
let methods = proto.blockMethods
methods.unshift(NAME)
return (tree, file) => {
let { path, data } = file
if (!data) {
file.data = data = {}
}
if (!data.refs) {
data.refs = {}
}
visit(tree, NAME, ({ id, value }) => {
let { contents } = render(value, path, data)
data.refs[id] = contents
})
remove(tree, NAME)
visit(tree, 'linkReference', (node, index, parent) => {
let { identifier } = node
let [match, id] = identifier.match(RE_REF)
if (!match || !id || !data.refs[id]) {
return
}
parent.children.splice(index, 1, {
type: 'html',
value: data.refs[id]
})
})
}
}

29
one/build/util.js Normal file
View File

@ -0,0 +1,29 @@
import { readFileSync as fsReadFileSync, writeFileSync as fsWriteFileSync } from 'fs'
import { dirname } from 'path'
import mkdirp from 'mkdirp'
import crypto from 'crypto'
export function readFileSync (file) {
return fsReadFileSync(file, 'utf8')
}
export function writeFileSync (file, content) {
mkdirp.sync(dirname(file))
fsWriteFileSync(file, content, 'utf8')
}
export function copyFileSync (src, dest) {
mkdirp.sync(dirname(dest))
writeFileSync(dest, readFileSync(src))
}
const RE_EXT = /\.([^.]+)$/
export function replaceExtSync (file, ext) {
return file.replace(RE_EXT, `.${ext}`)
}
export function hash (path) {
let hash = crypto.createHash('sha1')
hash.update(path)
return hash.digest('hex').substring(0, 7)
}

33
one/build/watch.js Normal file
View File

@ -0,0 +1,33 @@
import { resolve } from 'path'
import { debounce } from 'lodash'
import chokidar from 'chokidar'
import { generatePages } from './generator'
let watcher = chokidar.watch(resolve(__dirname, '../docs'), {
ignoreInitial: true
})
watcher
.on('all', debounce(generate, 1000))
function generate (type, path) {
switch (type) {
case 'add':
generatePages(path, { dir: false, remove: false })
break
case 'addDir':
generatePages(path, { dir: true, remove: false })
break
case 'change':
generatePages(path)
break
case 'unlink':
generatePages(path, { dir: false, remove: true })
break
case 'unlinkDir':
generatePages(path, { dir: true, remove: true })
break
default:
break
}
}

89
one/docs/advanced/custom-rules.md Normal file
View File

@ -0,0 +1,89 @@
# 自定义校验规则
对于多值校验，[表单 › validators 属性](../components/form#属性)提供了比较完善的功能来实现自定义校验。对于单值校验，`Field` 组件内置了 7 种常见规则，具体参考[表单项 › rule 属性](../components/field#属性)。如果无法覆盖需求，`VEUI` 校验规则模块允许你添加自定义规则。
## 示例
```js
import ruleManager from 'veui/manager/rule'
ruleManager.addRule('range', {
validate (value, ruleValue) {
// 仅实现大小校验部分
let range = value.split('-')
return +range[0] >= ruleValue.floor && +range[1] <= ruleValue.ceil
},
message: '范围值必须在限定区间内',
priority: 100
})
```
```html
<veui-field
:rules=[{
triggers: 'change'
name: 'range',
value: {
ceil: 100,
floor: 50
}
}]
...
>...</veui-field>
```
## API
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `validate` | `function(value: *, ruleValue: ?*=)` | 校验逻辑，`value` 为 `Field` 需要校验的值，`ruleValue` 可选，根据规则需要添加，表示规则的限定值。 |
| `message` | `function|string` | [^message] |
| `priority` | `number` | [^priority] |
^^^message
默认出错信息。
若类型为 `string`，可以通过 `{ruleValue}` 引用 `ruleValue`、`{value}` 引用 `value`。例如：
```js
let minLengthRule = {
validate (value, ruleValue) {
return !isEmpty(value) ? val.length >= ruleValue : true
},
message: '字符长度不能短于 {ruleValue}，当前长度 {value}',
priority: 100
}
```
若类型为 `function`，参数为 `(ruleValue: ?*=, value: *)`。例如：
```js
let minLengthRule = {
validate (value, ruleValue) {
return !isEmpty(value) ? val.length >= ruleValue : true
},
message (ruleValue, value) {
return `字符长度不能短于${ruleValue}，当前长度${value}`
},
priority: 100
}
```
:::tip
如果需要支持运行时切换语言，`message` 必须使用 `function` 类型。
:::
^^^
^^^priority
规则优先级。数值低优先级高。
+++目前内置的优先级
| 名称 | 优先级 |
| -- | -- | -- |
| `required` | `0` |
| `numeric` | `10` |
| `pattern` | `50` |
| `maxLength` | `100` |
| `minLength` | `100` |
| `max` | `200` |
| `min` | `200` |
+++

61
one/docs/advanced/global-config.md Normal file
View File

@ -0,0 +1,61 @@
# 全局配置
VEUI 中很多组件都定义了全局配置项，允许开发者在使用时全局配置某个组件的行为细节。
例如，`Uploader` 组件可以统一配置上传模式，用户可以根据项目前后端接口、需要支持浏览器版本的具体情况选择使用 iframe 回调方式还是 XHR2 方式传递数据，也可以统一配置远端数据格式的转换函数。
VEUI 全局配置项可以通过 `veui/managers/config` 模块进行覆盖：
```js
import config from 'veui/managers/config'
config.set('uploader.requestMode', 'iframe')
config.set('uploader.convertResponse', ({ code, error, result }) => {
/**
* Transform from
*
* {
* code: 0,
* error: '...',
* result: {
* url: '...'
* }
* }
*
* to
*
* {
* success: true,
* message: '...',
* src: '...'
* }
*/
return {
success: code === 0,
src: error ? null : result.url,
message: error || null
}
})
```
如果需要一次修改同一个组件的多项设置，可以使用如下写法：
```js
import config from 'veui/managers/config'
config.set({
requestMode: 'iframe',
convertResponse: data => data
}, 'uploader')
```
`config.set()` 方法参数可为如下形式：
* `(key: string, value: *, namespace: string)`
* `(values: Object<{key: string, value: *}>, namespace: string)`
当提供了 `namespace` 参数时，最终生成的配置项键名为 <code>\`${namespace}.${key}\`</code>。
除此以外，还提供了相同参数列表的 `config.defaults()` 方法，区别在于当需要在配置项中写入的键值已经存在，则不会覆盖。
每个组件、指令等支持的全局配置请查看对应组件、指令的详情页。

124
one/docs/advanced/overlay.md Normal file
View File

@ -0,0 +1,124 @@
# 浮层管理
在 VEUI 中，有大量组件使用到了浮层功能：
* 各种类型的弹框：[对话框](../components/dialog)、[警告弹框](../components/alert-box)等；
* [下拉选择](../components/select)；
* ……
针对这些组件，我们抽离了具备如下功能的浮层模块：
* 能够浮于页面上所有普通元素之上；
* 能够进行层叠顺序管理；
* 能够基于指定元素定位。
## 层叠覆盖
为了避免浮层被上层 `overflow: hidden` 的元素意外遮盖，我们将浮层根元素直接置于 `<body>` 下统一管理。
在[浮层组件](../components/overlay)中，`.veui-overlay-box` 对应了浮层根元素，该元素在组件初始化的时候，会被放置到 `<body>` 之下，组件销毁的时候，会被移除掉。
## 层叠顺序管理
在将浮层根元素置于 `<body>` 下后，原有的层级嵌套关系会丢失，同时也无法通过原生的层叠上下文机制来控制浮层的层叠顺序。比如：
* 某个对话框组件 A 上有一个下拉选择组件 B，那么 B 组件浮层应该位于 A 组件浮层之上。
* 警告框浮层应该位于普通对话框浮层之上。
基于上述限制，浮层模块实现了自己的层叠顺序管理机制。整个浮层层级嵌套关系，是通过一棵树来表达的：
<img class="preview hero" src="/images/development/advanced/overlay-tree.png">
树中每一个蓝色节点都对应关联到具体的[浮层组件](../componets/overlay)实例。针对上图，树的构造顺序可以是：
1. 弹出“对话框 1”，创建一个“对话框 1”节点，根据节点权重信息创建一个分组，然后将分组挂在 root 节点之下。
2. 弹出“对话框 2”，创建一个“对话框 2”节点，发现已经存在相同权重的分组，就直接将“对话框 2”节点放置在该分组的末尾位置。
3. 在“对话框 2”中实例化一个“下拉选择 1”组件实例，由于“对话框 2”组件实例是“下拉选择 1”组件实例的父级，因此对应的浮层节点也应当具备父子关系，因此按照类似于“步骤 1”的顺序在“对话框 2”节点下生成分组及“下拉选择 1”节点。
4. 此时由于程序运行出现了故障，弹出了“警告弹框 1”，由于“警告弹框”类型的组件相对于“对话框”组件具备更高的层级权重，因此在 root 之下新建了一个靠右的分组，并将生成的“警告弹框 1”节点置于分组末尾。
有了树之后，就会按照深度优先的遍历顺序生成每个节点的 `z-index` 值。
其中，基准 `z-index` 值可以通过全局配置对象进行配置：
```js
import config from 'veui/managers/config'
config.set('overlay.baseZIndex', 200)
```
:::warning
必须在[浮层组件](../components/overlay)引入之前设置基准 `z-index`，不然不会生效。
:::
可以针对组件类型，甚至组件实例粒度设置层叠优先级，层叠优先级值越大，最终生成的 `z-index` 值就越大。具有相同层叠优先级的同级组件实例，越靠后实例化的组件，生成的 `z-index` 值越大。
浮层组件、对话框组件、弹框组件等提供了 `priority` 属性，用于自定义组件实例的层叠优先级：
```html
<veui-dialog :priority="300"/>
```
一些比较特殊的组件，会提供基于组件类型粒度的层叠优先级配置：
| 组件 | 配置字段 | 默认值 | 修改配置示例 |
| -- | -- | -- | -- |
| 警告弹框 | `alertbox.priority` | `100` | [^alert-box] |
| 确认弹框 | `confirmbox.priority` | `100` | [^confirm-box] |
| 输入弹框 | `promptbox.priority` | `100` | [^prompt-box] |
^^^alert-box
```js
import config from 'veui/managers/config'
config.set('alertbox.priority', 100)
```
^^^
^^^confirm-box
```js
import config from 'veui/managers/config'
config.set('confirmbox.priority', 100)
```
^^^
^^^prompt-box
```js
import config from 'veui/managers/config'
config.set('promptbox.priority', 100)
```
^^^
总结起来，确定某个浮层系组件实例的层叠优先级的逻辑流程为：
* 如果能够设置组件实例级别的层叠优先级，并且设置了，那么就使用这个层叠优先级值，否则进入下一步；
* 如果能够设置组件类型级别的层叠优先级，并且设置了，那么就使用这个层叠优先级值，否则进入下一步；
* 使用默认的层叠优先级值：`1`。
## 定位
VEUI 中，浮层支持两种定位方式：
* 在页面范围内，以坐标值的形式进行定位；
* 相对于某个元素，指定偏移和变换规则进行定位。
以坐标方式定位时，需要自己写 CSS 进行控制（浮层模块内部只会生成浮层根元素的 `z-index` 值）。
相对元素定位时，可以通过[浮层组件](../components/overlay)的 `options` 属性描述偏移和变换规则。由于目前内部采用 [Tether](http://tether.io/) 实现，因此完整的配置项可以参考 [Tether 官网](http://tether.io/#options)。同时，也支持一些常见场景的简化配置：<code>{ position: &#0096;${side}-${align}&#0096; }</code>，`side` 表示浮层根元素位于目标元素哪一边（`top`/`right`/`bottom`/`left`），`align` 表示对齐方式（`start`/`end`）。其中 `side` 是必须的，`align` 不传表示居中。推荐尽量使用简化的配置。
## 样式
由于浮层根元素被手动放置到 `<body>` 元素之下了，要设置浮层内容的样式，就需要给浮层根元素指定 `class`。所有浮层系组件都支持 `overlay-class` 属性，通过该属性为浮层根元素设置 `class`：
```vue
<template>
<veui-dialog overlay-class="my-dialog-overlay"/>
<template>
<style>
.my-dialg-overlay {
/* 自定义浮层样式 */
}
</style>
```

134
one/docs/advanced/theming.md Normal file
View File

@ -0,0 +1,134 @@
# 主题
VEUI 的组件和主题包是完全解耦的。组件库中不含有任何样式代码，每个组件的样式都需要主题包中对应的样式文件来提供。
为了方便在按需引入的同时不需要手动引入每个组件的样式代码，我们提供了 `veui-loader` 来完成通过配置自动将依赖的样式文件注入组件，详情请参考 `veui-loader` 的[相关介绍](../getting-started/veui-loader)。
## 创建自定义主题包
veui-loader 为 VEUI 注入依赖时，同时支持注入 script 类型及 style 类型的模块。所以主题包中可以为每个组件提供这两种类型的主题配置。
### 自定义样式
:::warning
注意，主题包样式对 VEUI 组件的 DOM 结构会有依赖。
:::
为每个组件提供完整的样式，可以使用任何预处理语言。每个组件具体提供的类名及选择器可以参考 `veui-theme-dls` 中的实现。
```less
.veui-button {
/* ... */
}
```
### 自定义图标
VEUI 的 `Icon` 组件封装了 [Vue-Awesome](https://justineo.github.io/vue-awesome/demo/) 来输出内联 SVG 图标，无法直接在样式代码中指定，需要通过 script 模块进行注册。每个组件都定义了语义明确的图标接口，我们需要做的只是在全局配置中为组件注入相应的图标名称映射并引入对应的图标模块：
```js
import config from 'veui/managers/config'
import '../icons/angle-up-small'
import '../icons/angle-down-small'
config.defaults({
icons: {
expand: 'angle-down-small',
collapse: 'angle-up-small'
}
}, 'select')
```
除了 `veui-theme-dls` 自带的图标外，目前可以使用的图标包还有：
* [`vue-awesome/icons`](https://justineo.github.io/vue-awesome/demo/)：Vue-Awesome 自带 [FontAwesome](https://fontawesome.com/) 图标包
* [`vue-awesome-material-icons/icons`](https://justineo.github.io/vue-awesome-material-icons/demo/)：同样基于 Vue-Awesome 的 [Material Icons](https://material.io/tools/icons) 图标包
### 预设样式及自定义配置
VEUI 中各个组件的可切换的预设样式是通过为主题包提供可扩展的 `ui` 配置实现的。
新增一个预设样式 `foo` 只需要在样式文件中添加 `[ui~="foo"]` 对应的样式并在使用组件时添加对应的 `ui="foo"` 声明即可完成：
```less
.veui-select {
/* ... */
&[ui~="foo"] {
color: #f00;
}
}
```
```html
<veui-select ui="foo">...</veui-select>
```
一个组件也可以同时应用多个预设样式：
```html
<veui-select ui="foo bar">...</veui-select>
```
但如果我们想将预设样式定义得更完善一些，比如 `foo` 与 `bar` 是组件的两种不可同时使用的预设样式怎么办呢？比如 `small` 和 `large` 样式都会自定义组件的尺寸，是互斥的，我们就需要通过在全局配置中为组件注入更详细的 `ui` 配置来实现。
`ui` 字段下每个属性名都是需要声明的预设样式名称，其值的类型为：`{ values, boolean, inherit }`。
字段详情：
| 名称 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `values` | `Array<string>` | - | 预设 `ui` 属性的可选值。 |
| `boolean` | `boolean` | `false` | 预设 `ui` 属性是否为布尔型。 |
| `inherit` | `boolean` | `false` | 预设 `ui` 属性值是否会被子组件继承。 |
以 `Select` 组件为例：
```js
import config from 'veui/managers/config'
config.defaults({
ui: {
size: {
values: ['large', 'small', 'tiny', 'micro'],
inherit: true
},
style: {
values: ['alt']
}
}
}, 'select')
```
在上面这个例子中，我们定义了两个 `ui` 属性：`size` 和 `style`。它们都是枚举类型，其中 `size` 值可被子组件继承。最终调用 `Select` 组件时，可以这样启用预设样式：
```html
<veui-select ui="alt small">...</veui-select>
```
当然，我们也可以完全不定义 `ui` 属性的详情，这时 VEUI 会将用户书写的 `ui` 属性原样输出，不会进行去重、同属性的属性值冲突检测、继承等特殊处理。
:::warning
由于 `ui` 属性最后会将值打平输出到 DOM 元素上，所以各个属性的值不能冲突。
:::
### 指定组件内部组件的预设样式
有一些组件由多个其它组件组合而成，此时我们可能会需要全局指定内部特定部件的预设样式。比如在 `veui-theme-dls` 中，`Dialog` 中的取消按钮默认采用默认样式，而如果在其它主题中我们可能会想重置为 `link` 样式。此时可以使用全局配置修改组件的 `parts` 映射。
```js
import config from 'veui/managers/config'
config.defaults({
parts: {
ok: 'primary',
cancel: 'link'
}
}, 'select')
```
## 主题包列表
* [veui-theme-dls](https://github.com/ecomfe/veui/tree/dev/packages/veui-theme-dls)：基于 DLS 的 VEUI 2.x 主题
* [veui-theme-blue](https://github.com/ecomfe/veui-theme-blue)：基于 Theme Blue 的 VEUI 1.x 主题
* [veui-theme-spectre](https://justineo.github.io/veui-theme-spectre/demo/)：基于 Spectre.css 的 VEUI 1.x 主题

61
one/docs/components/accordion.md Normal file
View File

@ -0,0 +1,61 @@
# Accordion <small>手风琴面板</small>
:::tip
`Accordion` 组件需要内联 [`Collapse`](./collapse) 组件使用。
:::
## 示例
### 尺寸
可选的尺寸 `ui` 属性值：`s`/`m`。
[[ demo src="/demo/accordion/size.vue" ]]
### 允许多个展开
可使用 `multiple` 属性来允许多个面板同时展开。
[[ demo src="/demo/accordion/multiple.vue" ]]
## API
### 属性
| 名称 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `multiple` | `boolean=` | `false` | 是否允许多个子面板同时展开。 |
| `disabled` | `boolean=` | `false` | 是否为禁用状态。 |
| `expanded` | `string|Array<string>` | - | [^expanded] |
^^^expanded
:::badges
`.sync`
:::
已展开的折叠面板标识，对应于内联 `Collapse` 组件的 `name` 属性。当 `multiple` 为 `true` 时，为折叠面板标识的数组。
^^^
### 插槽
| 名称 | 描述 |
| -- | -- |
| `default` | 内容区，用来内联 `Collapse` 组件。 |
### 事件
| 名称 | 描述 |
| -- | -- |
| `toggle` | [^toggle] |
^^^toggle
点击内部折叠面板标题区触发展开/收起时触发。回调参数为 `(expand: boolean, name: string, expanded)`。
+++参数详情
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `expand` | `boolean` | 是否展开。 |
| `name` | `string` | 被切换的折叠面板标识。 |
| `expanded` | `string|Array<string>` | 当前所有被展开的折叠面板标识。 |
+++
^^^

69
one/docs/components/alert-box.md Normal file
View File

@ -0,0 +1,69 @@
# AlertBox <small>警告弹框</small>
## 示例
### 类型
`AlertBox` 有三种类型，分别是 `info`、`success` 和 `error`，可以通过 `type` 属性指定不同的类型。
[[ demo src="/demo/alert-box/type.vue" ]]
### 标题
可以通过 `title` 属性或 `title` 插槽自定义警告弹框的标题。
[[ demo src="/demo/alert-box/title.vue" ]]
## API
### 属性
| 名称 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `open` | `boolean` | `false` | [^open] |
| `type` | `string=` | `'success'` | [^type] |
| `title` | `string=` | - | 标题。 |
| `overlay-class` | `string|Array|Object=` | - | 参考 [`Overlay`](./overlay) 组件的 `overlay-class` 属性。 |
^^^open
:::badges
`.sync`
:::
是否显示警告弹框。
^^^
^^^type
警告框类型。
+++枚举值
| 值 | 描述 |
| -- | -- |
| `info` | 信息提示样式。 |
| `success` | 成功样式。 |
| `error` | 错误样式。 |
+++
^^^
### 插槽
| 名称 | 描述 |
| -- | -- |
| `default` | 内容区。 |
| `title` | 标题区。若同时指定了 `title` 属性和 `title` 插槽，以后者为准。 |
| `foot` | 底部区域，默认会展示一个“知道了”按钮。 |
### 事件
| 名称 | 描述 |
| -- | -- |
| `ok` | 点击“知道了”按钮触发。 |
| `afterclose` | 浮层关闭后触发。如果样式主题提供了退出动画，将在退出动画完毕后触发。 |
### 图标
| 名称 | 描述 |
| -- | -- |
| `info` | 普通信息。 |
| `success` | 成功状态。 |
| `error` | 错误状态。 |

92
one/docs/components/alert.md Normal file
View File

@ -0,0 +1,92 @@
# Alert <small>提示</small>
## 示例
### 类型
`Alert` 有四种类型，分别是 `success`、`info`、`warning` 和 `error`，可以通过 `type` 属性指定不同的类型。
[[ demo src="/demo/alert/type.vue" ]]
### 多消息切换
可以将 `message` 属性指定为数组，来实现展现多条可切换的消息提示。
[[ demo src="/demo/alert/multiple.vue" ]]
## API
### 属性
| 名称 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `type` | `string=` | `'success'` | [^type] |
| `title` | `string` | - | 消息标题。 |
| `message` | `string|Array<string>` | - | 消息内容，当类型为数组时会显示多条数据并支持切换上一条/下一条。 |
| `closable` | `boolean=` | `false` | 是否允许关闭。 |
| `open` | `boolean=` | `true` | [^open] |
| `index` | `number=` | `0` | [^index] |
^^^type
警告框类型。
+++枚举值
| 值 | 描述 |
| -- | -- |
| `info` | 信息提示样式。 |
| `success` | 成功样式。 |
| `warning` | 警告样式。 |
| `error` | 错误样式。 |
+++
^^^
^^^open
:::badges
`.sync`
:::
是否显示消息。
^^^
^^^index
:::badges
`.sync`
:::
在有多条数据时，当前显示的消息的索引。
^^^
### 插槽
| 名称 | 描述 |
| -- | -- |
| `default` | [^scoped-slot-default] |
| `title` | 消息标题的内容区域。 |
| `extra` | 消息之后的额外内容区域。 |
| `content` | 整个消息区域，包括状态图标、切换按钮、关闭按钮等。 |
^^^scoped-slot-default
消息内容区域。
默认内容：消息文本。
+++作用域参数
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `message` | `string` | 消息文本。 |
| `index` | `number=` | 当有多条消息时，当前消息的索引值。 |
| `close` | `function` | 用于关闭提示。 |
+++
^^^
### 图标
| 名称 | 描述 |
| -- | -- |
| `success` | 成功消息。 |
| `warning` | 警告消息。 |
| `info` | 信息消息。 |
| `error` | 错误消息。 |
| `prev` | 上一条。 |
| `next` | 下一条。 |
| `close` | 关闭。 |

64
one/docs/components/anchor.md Normal file
View File

@ -0,0 +1,64 @@
# Anchor <small>锚点</small>
## 示例
### 容器与吸附
使用 `container` 属性设置 `Anchor` 的容器，使用 `sticky` 属性来控制是否在滚动出容器时进行吸附。
[[ demo src="/demo/anchor/sticky.vue" ]]
### 指定偏移
`target-offset` 用来控制锚点滚动到容器何处开始处于激活状态。
`sticky-offset` 用来控制 `Anchor` 处于容器何处时开始吸附。
[[ demo src="/demo/anchor/offset.vue" ]]
## API
### 属性
| 名称 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `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` 开始吸附。 |
^^^items
数据源数组，每个项目类型为 `{label, value, children, ...}`。
+++字段详情
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `label` | `string` | 节点的文字描述。 |
| `value` | `string` | 节点对应的值，一般是页内 hash， 如 `#button` 。 |
| `children` | `Array<Object>=` | 节点的子节点数组，数组项类型同 `items` 数组项。 |
+++
^^^
### 插槽
| 名称 | 描述 |
| -- | -- |
| `item` | [^scoped-slot-item] |
| `item-label` | [^scoped-slot-item-label] |
^^^scoped-slot-item
渲染每个锚点链接。
默认内容：锚点链接。
作用域参数参见 `items` 属性详情。
^^^
^^^scoped-slot-item-label
渲染每个锚点链接的文本。
默认内容：锚点链接的描述文本 `label`。
作用域参数参见 `item` 插槽。
^^^

91
one/docs/components/autocomplete.md Normal file
View File

@ -0,0 +1,91 @@
# Autocomplete <small>自动完成</small>
## 示例
[[ demo src="/demo/autocomplete/normal.vue" ]]
## API
### 属性
| 名称 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `datasource` | `Array<string|Object>=` | `[]` | [^datasource] |
| `value` | `*` | - | [^prop-value] |
| `match` | `function(string|Object, string)=: boolean` | - | 自定义搜索逻辑。 |
| `strict` | `boolean=` | `false` | 建议下拉面板关闭时，若输入值没有完全匹配建议值，那么会清空输入值。 |
| `suggest-trigger` | `string|Array<string>=` | `'input'` | 触发建议下拉面板的时机，可用值有：`'input'`、`'focus'`。 |
| `placeholder` | `string=` | | 输入占位符。 |
| `select-on-focus` | `boolean=` | `false` | 聚焦时是否自动选中输入框文本。 |
| `composition` | `boolean=` | `false` | 是否感知输入法输入过程的值。 |
| `clearable` | `boolean=` | `false` | 是否显示清除按钮。 |
| `disabled` | `boolean=` | `false` | 是否为禁用状态。 |
| `readonly` | `boolean=` | `false` | 是否为只读状态。 |
^^^datasource
数据源数组，项目为 `Object` 时字段为 `{label, value, children, ...}`。
+++字段详情
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `label` | `string` | 节点的文字描述。 |
| `value` | `string` | 节点对应的值，一般是页内 hash， 如 `#button` 。 |
| `children` | `Array<Object>=` | 节点的子节点数组，数组项类型同 `items` 数组项。 |
+++
^^^
^^^prop-value
:::badges
`v-model`
:::
当前选中的值。
^^^
### 插槽
| 名称 | 描述 |
| -- | -- |
| `suggestions` | [^scoped-slot-suggestions] |
| `option-label` | [^scoped-slot-option-label] |
^^^scoped-slot-suggestions
下拉建议面板插槽。
+++作用域参数
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `datasource` | `Array<string|Object>` | 数据源，类型同 `datasource` 属性。 |
| `keyword` | `string` | 搜索关键词。 |
+++
^^^
^^^scoped-slot-option-label
下拉面板中选项插槽。
+++作用域参数
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `label` | `string` | 用来显示的节点文案，不存在则取 `value`。 |
| `value` | `string` | 用来实际选中的值。 |
| `matches` | `Array<{text: string, matched: boolean}>` | 匹配情况，一个节点可能被切分成多断文本，`text` 表示该段文本， `matched` 表示该段文本是否匹配。 |
+++
^^^
### 事件
| 名称 | 描述 |
| -- | -- |
| input | [^event-input] |
| suggest | 采纳建议时触发，参数是当前值。 |
| clear | 清除当前值时触发。 |
^^^event-input
:::badges
`v-model`
:::
当在 `input` 中输入或下拉面板中选值会触发该事件，参数是当前输入值或选中时的选中项目的 `value`。
^^^

52
one/docs/components/badge.md Normal file
View File

@ -0,0 +1,52 @@
# Badge <small>徽标</small>
## 示例
### 文字徽标
徽标内容可以是纯文本。
[[ demo src="/demo/badge/text.vue" ]]
### 数字徽标
徽标内容也可以是数字，超过最大值时可以显示为*最大值+*。
[[ demo src="/demo/badge/number.vue" ]]
### 圆点徽标
不提供插槽内容时，徽标将以圆点样式显示。
[[ demo src="/demo/badge/dot.vue" ]]
## API
### 属性
| 名称 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `type` | `string=` | `'error'` | [^type] |
| `value` | `string|number` | - | 徽标内容值。为 `number` 类型值时，会受 `max` 属性限制。为 `string` 类型时，`max` 会被忽略。 |
| `max` | `number=` | `badge.max` | 徽标数值的最大值，当 `value` 超过此值时，徽标内容会显示为 `{max}+`。当 `value` 为 `string` 时会被忽略。 |
| `hidden` | `boolean=` | `false` | 是否处于隐藏状态。 |
^^^type
徽标状态类型。自带样式的可选值如下。使用其它值时需要自行定义 `.veui-badge-{type}` 的样式。
+++枚举值
| 值 | 描述 |
| -- | -- |
| `info` | 信息提示样式。 |
| `success` | 成功样式。 |
| `warning` | 警告样式。 |
| `error` | 错误样式。 |
| `aux` | 辅助样式。 |
+++
^^^
### 插槽
| 名称 | 描述 |
| -- | -- |
| `default` | 需要显示徽标的目标内容。 |

48
one/docs/components/breadcrumb-item.md Normal file
View File

@ -0,0 +1,48 @@
# BreadcrumbItem <small>面包屑项</small>
:::tip
`BreadcrumbItem` 组件需要在 [`Breadcrumb`](./breadcrumb) 组件内使用。
:::
## 示例
见 [`Breadcrumb` 示例](./breadcrumb#示例)。
## API
### 属性
| 名称 | 类型 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `to` | `string|Object` | - | 点击面包屑项之后要跳转到的地址。见 [`Link`](./link#属性) 组件的同名属性。 |
| `type` | `string` | `'link'` | [^link] |
| `native` | `boolean` | `false` | 当值为 `true` 且指定了 `to` 时，会直接使用原生 `<a>` 元素，`to` 值会被设置到 `<a>` 标签的 `href` 属性上。 |
^^^link
面包屑项的类型。
+++枚举值
| 值 | 描述 |
| -- | -- |
| `link` | 超链接样式。 |
| `text` | 文本样式。 |
+++
^^^
### 插槽
| 名称 | 描述 |
| -- | -- |
| `default` | 填充面包屑项的正文内容区。 |
### 事件
| 名称 | 描述 |
| -- | -- |
| `redirect` | 点击 `type` 为 `link` 的项目时将触发该事件，回调参数为 `(event: Event)`，直接透传[原生点击事件对象](https://developer.mozilla.org/zh-CN/docs/Web/Events/click)。 |
### 图标
| 名称 | 描述 |
| -- | -- |
| `separator` | 分隔符。 |

114
one/docs/components/breadcrumb.md Normal file
View File

@ -0,0 +1,114 @@
# Breadcrumb <small>面包屑</small>
:::tip
`Breadcrumb` 组件可以内联 [`BreadcrumbItem`](./breadcrumb-item) 组件使用。
:::
## 示例
### 风格
可选的风格 `ui` 属性值：`strong`。
[[ demo src="/demo/breadcrumb/style.vue" ]]
### 尺寸
可选的尺寸 `ui` 属性值：`s`/`m`。
[[ demo src="/demo/breadcrumb/size.vue" ]]
### 使用内联 `BreadcrumbItem`
直接内联 `BreadcrumbItem` 使用。
[[ demo src="/demo/breadcrumb/base.vue" ]]
### 使用数据源
也可以传入数据源。
[[ demo src="/demo/breadcrumb/datasource.vue" ]]
### 自定义分隔符
可以使用插槽自定义分隔符。
[[ demo src="/demo/breadcrumb/separator.vue" ]]
### 事件监听
监听跳转事件后处理而非直接路由跳转。
[[ demo src="/demo/breadcrumb/redirect.vue" ]]
## API
### 属性
| 名称 | 类型 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `ui` | `string=` | - | [^ui] |
| `routes` | `Array<Object>` | `[]` | [^routes] |
^^^ui
预设样式。
+++枚举值
| 值 | 描述 |
| -- | -- |
| `s` | 小尺寸样式。 |
| `m` | 中尺寸样式。 |
^^^
^^^routes
面包屑配置，项目类型为 `{label: string, type: string, to: string|Object=, native: boolean=}`，除 `label` 外字段详情可参考 [`BreadcrumbItem`](./breadcrumb-item) 组件的属性。
:::warning
默认情况下，最后一项始终会显示成普通文本样式。
:::
^^^
### 插槽
| 名称 | 描述 |
| -- | -- |
| `default` | 支持内联模式，直接传入 [`BreadcrumbItem`](./breadcrumb-item) 组件列表。填充后 `routes` 属性将被忽略。 |
| `item` | [^slot-item] |
| `separator` | [^slot-separator] |
^^^slot-item
用于为每个项目自定义内容。默认内容为 `routes` 项目的 `label` 或 [`BreadcrumbItem`]('./breadcrumb-item) 组件的默认插槽。
+++作用域参数
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `route` | `Object` | `routes` 中的项目。自定义字段亦会绑定到作用域对象中。 |
+++
^^^
^^^slot-separator
面包屑条目之间的分隔符。默认显示全局配置的分隔图标。
:::warning
当使用 Vue.js `2.5.17` 及以下版本时，必须绑定 `slot-scope` 使用。
:::
^^^^
### 事件
| 名称 | 描述 |
| -- | -- |
| `redirect` | [^redirect] |
^^^redirect
点击 `type` 为 `link` 的项目时将触发该事件，回调参数为 `(event, route, index)`。
+++参数详情
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `event` | [Event](https://developer.mozilla.org/zh-CN/docs/Web/Events/click) | 事件对象。 |
| `route` | `Object` | 面包屑条目对象。 |
| `index` | `number` | 当前点击条目的索引。 |
+++
^^^

110
one/docs/components/button-group.md Normal file
View File

@ -0,0 +1,110 @@
# ButtonGroup <small>按钮组</small>
## 示例
### 风格
可选的 `ui` 属性值：`primary`/`strong`。
[[ demo src="/demo/button-group/style.vue" ]]
### 尺寸
可选的 `ui` 属性值：`xs`/`s`/`m`/`l`/`xl`。
[[ demo src="/demo/button-group/size.vue" ]]
### 使用 `items` 数据源
可以使用 `items` 属性通过数据源指定按钮内容。
[[ demo src="/demo/button-group/items.vue" ]]
### 禁用状态
设置 `disabled` 来使按钮处于禁用状态。
[[ demo src="/demo/button-group/disabled.vue" ]]
## API
### 属性
| 名称 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `ui` | `string=` | - | [^ui] |
| `items` | `Array<Object>` | - | [^items] |
| `disabled` | `boolean=` | `false` | 按钮是否为禁用状态。 |
^^^ui
预设样式。为空格分隔的一组枚举值的组合。
+++枚举值
| 值 | 描述 |
| -- | -- |
| `primary` | 主要按钮，背景显示为主题色。 |
| `strong` | 加强样式。 |
| `xs` | 超小尺寸样式。 |
| `s` | 小尺寸样式。 |
| `m` | 中尺寸样式。 |
| `l` | 大尺寸样式。 |
| `xl` | 超大尺寸样式。 |
+++
^^^
^^^items
按钮数据项的数组，项目类型为 `{label, value}`。
+++字段详情
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `label` | `string` | 按钮文本。 |
| `value` | `*=` | 如传入 `string` 类型的值，则会在点击按钮时触发同名的事件。 |
+++
^^^
### 插槽
| 名称 | 描述 |
| -- | -- |
| `default` | 按钮组内容区。 |
| `item` | [^scoped-slot-item] |
^^^scoped-slot-item
默认作用域插槽，用来定制每个按钮的内容。
默认内容：`label` 属性值。
+++作用域参数
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `label` | `string` | 按钮文本。 |
| `value` | `*=` | 按钮项的 `value` 值。 |
| `index` | `number` | 按钮在 `items` 中的序号。 |
| `disabled` | `boolean=` | 按钮是否禁用。 |
+++
另外，`items` 内数据项中除了上面描述的字段之外的其它字段也会自动通过 `v-bind` 进行绑定到作用域参数上。
^^^
### 事件
| 名称 | 描述 |
| -- | -- |
| `click` | [^click-event] |
| <var>&lt;value&gt;</var> | [^value-var-event] |
^^^click-event
点击后触发，回调参数为 `(item, index)`。
+++参数详情
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `item` | `{label: string, value: *=, ...}` | 数据项。 |
| `index` | `number` | 按钮在 `items` 中的序号。 |
+++
^^^
^^^value-var-event
如果对应数据项有字符串类型的 `value` 字段，则在点击后触发名为 `value` 值的事件，参数与 `click` 事件相同。
^^^

93
one/docs/components/button.md Normal file
View File

@ -0,0 +1,93 @@
# Button <small>按钮</small>
## 示例
### 风格
可选的风格 `ui` 属性值：`primary`/`strong`/`translucent`/`text`/`icon`。
[[ demo src="/demo/button/style.vue" ]]
### 尺寸
可选的尺寸 `ui` 属性值：`xs`/`s`/`m`/`l`/`xl`。
[[ demo src="/demo/button/size.vue" ]]
### 禁用状态
设置 `disabled` 来使按钮处于禁用状态。
[[ demo src="/demo/button/disabled.vue" ]]
### 加载状态
设置 `loading` 来使按钮处于加载状态，无法点击。
[[ demo src="/demo/button/loading.vue" ]]
## API
### 属性
| 名称 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `ui` | `string=` | - | [^ui] |
| `disabled` | `boolean=` | `false` | 是否为禁用状态。 |
| `type` | `string=` | `'button'` | [^type] |
| `loading` | `boolean=` | `false` | 是否处于加载状态。加载状态下按钮不响应用户交互。 |
^^^ui
预设样式。为空格分隔的一组枚举值的组合。
+++枚举值
| 值 | 描述 |
| -- | -- |
| `normal` | 普通按钮，为默认样式。 |
| `primary` | 主要按钮，背景显示为主题色。 |
| `basic` | 基础按钮。 |
| `strong` | 加强样式。可单独使用，也可配合 `text`/`icon` 样式使用。 |
| `translucent` | 半透明样式，用于深色背景。 |
| `text` | 纯文字样式，没有背景色及边框。 |
| `icon` | 纯图标样式，没有背景色及边框。 |
| `aux` | 辅助按钮，用于配合 `text`/`icon` 样式使用。 |
| `square` | 方形按钮。可配合其它样式一同使用。 |
| `xs` | 超小尺寸样式。 |
| `s` | 小尺寸样式。 |
| `m` | 中尺寸样式。 |
| `l` | 大尺寸样式。 |
| `xl` | 超大尺寸样式。 |
+++
^^^
^^^type
按钮类型。参见原生 `<button>` 元素的 [`type`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/button#attr-type)。
+++枚举值
| 值 | 描述 |
| -- | -- |
| `button` | 普通按钮。 |
| `submit` | 提交按钮，点击会触发外部表单提交。 |
| `reset` | 重置按钮，点击会触发外部表单重置为初始值。 |
+++
:::warning
注意，默认值与原生 `<button>` 元素不同。需要触发表单提交时请显式设置为 `submit`。
:::
^^^
### 插槽
| 名称 | 描述 |
| -- | -- |
| `default` | 按钮上显示的内容。 |
### 事件
`Button` 组件支持所有原生 `<button>` 元素支持的原生事件，回调函数的参数均为相应的原生事件对象。
### 图标
| 名称 | 描述 |
| -- | -- |
| `loading` | 加载状态。 |

123
one/docs/components/calendar.md Normal file
View File

@ -0,0 +1,123 @@
# Calendar <small>日历</small>
## 示例
### 单日选择
默认情况下，单击日期可以选中一个日期。
[[ demo src="/demo/calendar/default.vue" ]]
### 多日选择、日期范围选择
配置 `multiple` 属性时，可以选择多个日期。配置 `range` 属性时，可以选择一个日期范围。
[[ demo src="/demo/calendar/range-multiple.vue" ]]
### 多日期范围选择
同时配置 `multiple` 及 `range` 属性时，可以选择多段日期范围。配置 `panel` 属性时，可以指定日历面板的数量。两次选择的时间段合并的策略为，若从未选日期开始选择则选中该时段，否则则取消选择该时段。
[[ demo src="/demo/calendar/multiple-ranges.vue" ]]
## API
### 属性
| 名称 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `type` | `string=` | `'date'` | 日历的类型，可用值为 `'date'`/`'month'`/`'year'`，分别对应日期/月/年视图。 |
| `multiple` | `boolean=` | `false` | 是否可以选择多个日期（范围）。 |
| `range` | `boolean=` | `false` | 是否选择日期范围。 |
| `selected` | `Date|Array=` | - | [^selected] |
| `panel` | `number=` | `1` | 日历面板数量。 |
| `today` | `Date=` | `new Date()` | 「今天」的日期。 |
| `week-start` | `number=` | `calendar.weekStart` | 一周的起始。可进行[全局配置](#全局配置)。 |
| `fill-month` | `boolean=` | `true` | 当只有一个面板时，是否要在当前月份面板显示非本月日期。 |
| `date-class` | `string|Array|Object|function=` | `{}` | 特定日期的自定义 HTML `class`。传非函数时，数据格式为所有 [Vue 支持的 `class` 表达式](https://cn.vuejs.org/v2/guide/class-and-style.html#%E7%BB%91%E5%AE%9A-HTML-Class)；传函数时，签名为 `function(Date): string|Array<string>|Object<string, boolean>`，返回值格式亦为所有 Vue 支持的 `class` 表达式。 |
| `disabled-date` | `function(Date)=: boolean` | `() => false` | 特定日期是否禁用。 |
| `disabled` | `boolean=` | `false` | 是否为禁用状态。 |
| `readonly` | `boolean=` | `false` | 是否为只读状态。 |
^^^selected
:::badges
`v-model`
:::
已选日期（范围）的值，根据 `multiple` 和 `range` 属性值的不同，数据格式不同。
+++类型详情
| `multiple` | `range` | 类型 |
| -- | -- | -- |
| `false` | `false` | `Date` |
| `true` | `false` | `Array<Date>` |
| `false` | `true` | `[Date, Date]` |
| `true` | `true` | `Array<[Date, Date]>` |
+++
^^^
### 插槽
| 名称 | 描述 |
| -- | -- |
| `before` | 日历内，面板上方可供定制的区域。 |
| `after` | 日历内，面板下方可供定制的区域。 |
| `date` | [^scoped-slot-date] |
^^^scoped-slot-date
单日单元格内的区域，可用来定制每一天对应区域的内容。
默认内容：对应日期的 `date`。
+++作用域参数
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `year` | `number` | 完整年份。 |
| `month` | `number` | 月份数，`0` 表示一月。 |
| `date` | `number` | 月份内的日期。 |
+++
^^^
### 事件
| 名称 | 描述 |
| -- | -- |
| `select` | [^event-select] |
| `selectstart` | 选择日期范围时，选择完起始日期时触发，回调参数 `(picking: Date)`，表示已选的起始项日期。 |
| `selectprogress` | [^event-selectprogress] |
| `viewchange` | 面板显示的月份发生变化时触发。回调参数 `(month: Object<{year: number, month: number, index: number}>)`，表示当前年月（`month` 为 `0` 表示一月）。 |
^^^event-select
:::badges
`v-model`
:::
选择修改后触发，回调参数为 `(selected)`。数据类型和 `selected` 属性一致。
^^^
^^^event-selectprogress
选择日期范围时，在已经选择开始日期后，通过鼠标或键盘交互标记到的结束日期变更时触发。回调参数为 `(picking)`，表示当前标记的日期范围，类型取决于 `multiple` 属性的值。
+++参数详请
| `multiple` | 类型 |
| -- | -- |
| `false` | `[Date, Date]` |
| `true` | `Array<[Date, Date]>` |
+++
^^^
### 全局配置
| 名称 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `calendar.weekStart` | `number` | `1` | 一周的第一天是星期几。周一到周日分别对应 `1` 到 `7`。 |
### 图标
| 名称 | 描述 |
| -- | -- |
| `backward` | 上一年。 |
| `prev` | 上一页。 |
| `next` | 下一页。 |
| `forward` | 下一年。 |
| `expand` | 展开下拉菜单。 |

110
one/docs/components/carousel.md Normal file
View File

@ -0,0 +1,110 @@
# Carousel <small>轮播</small>
## 示例
### 切换
使用 `index` 来控制当前显示的项目。
[[ demo src="/demo/carousel/switch.vue" ]]
### 进度指示器类型
使用 `indicator` 属性来指定进度指示器类型。
[[ demo src="/demo/carousel/indicator.vue" ]]
### 自动切换
指定 `autoplay` 属性来允许自动播放。
[[ demo src="/demo/carousel/autoplay.vue" ]]
## API
### 属性
| 名称 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `datasource` | `Array<Object>` | `[]` | [^datasource] |
| `index` | `number=` | `0` | [^index] |
| `indicator` | `string=` | `'radio'` | [^indicator] |
| `switch-trigger` | `string=` | `'click'` | [^switch-trigger] |
| `autoplay` | `boolean=` | `false` | 是否自动轮播。 |
| `pause-on-hover` | `boolean=` | `false` | 在自动轮播时，鼠标悬浮后是否暂停。 |
| `interval` | `number=` | `3000` | 在自动轮播时，切换间隔的毫秒数。 |
| `wrap` | `boolean=` | `false` | 是否可以循环播放。 |
^^^datasource
轮播图数据源，项目类型为：`{src, alt, label}`。
+++字段详情
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `src` | `string` | 图片源地址。 |
| `alt` | `string` | 图片的降级描述文本。 |
| `label` | `string` | 图片的描述性标题。 |
+++
^^^
^^^index
:::badges
`.sync`
:::
当前轮播图序号。
^^^
^^^indicator
播放进度指示器的显示模式。
+++枚举值
| 值 | 描述 |
| -- | -- |
| `radio` | 单选按钮型。 |
| `number` | 显示「当前页数/全部页数」文字提示。 |
| `none` | 不显示指示器。 |
^^^
^^^switch-trigger
当显示单选型指示器时，触发切换的操作。
+++枚举值
| 值 | 描述 |
| -- | -- |
| `click` | 点击时切换。 |
| `hover` | 鼠标悬浮时切换。 |
+++
^^^
### 插槽
| 名称 | 描述 |
| -- | -- |
| `item` | [^scoped-slot-item] |
^^^scoped-slot-item
可用来定制每个轮播项的区域。
默认内容：轮播项图片。
作用域参数为 `datasource` 属性每个列表项的内容（可以有自定义字段）加上 `index: number` 表示轮播项的序号。即整个 `slot-scope` 绑定的值为 `{src, alt, label, index, ...}`。
^^^
### 事件
| 名称 | 描述 |
| -- | -- |
| `change` | [^event-change] |
^^^event-change
切换后触发，回调参数为 `(to: number, from: number)`。分别表示切换后的序号和切换前的序号。
^^^
### 图标
| 名称 | 描述 |
| -- | -- |
| `prev` | 上一页。 |
| `next` | 下一页。 |

88
one/docs/components/check-button-group.md Normal file
View File

@ -0,0 +1,88 @@
# CheckButtonGroup <small>复选按钮组</small>
## 示例
### 尺寸
可选的 `ui` 属性值：`s`/`m`。
[[ demo src="/demo/check-button-group/default.vue" ]]
## API
### 属性
| 名称 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `ui` | `string=` | - | [^ui] |
| `items` | `Array<Object>` | `[]` | [^items] |
| `value` | `Array` | `[]` | [^value] |
| `disabled` | `boolean=` | `false` | 是否为禁用状态。 |
| `readonly` | `boolean=` | `false` | 是否为只读状态。 |
^^^ui
预设样式。
+++枚举值
| 值 | 描述 |
| -- | -- |
| `s` | 小尺寸样式。 |
| `m` | 中尺寸样式。 |
^^^
^^^items
复选按钮组数据源，项目类型为 `{label, value, disabled, ...}`。
+++字段详情
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `label` | `string` | 选项的文字说明。 |
| `value` | `*` | 选项对应的值。 |
| `disabled` | `boolean=` | 选项是否为禁用。 |
+++
^^^
^^^value
:::badges
`v-model`
:::
`items` 中已选项的 `value` 列表。
^^^
### 插槽
| 名称 | 描述 |
| -- | -- |
| `item` | [^scoped-slot-item] |
^^^scoped-slot-item
按钮内文本区域。
默认内容：`label` 属性值。
+++作用域参数
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `label` | `string` | 选项文本。 |
| `value` | `*` | 选项值。 |
| `index` | `number` | 选项在 `items` 中的序号。 |
| `disabled` | `boolean=` | 选项是否禁用。 |
+++
另外，`items` 内数据项中除了上面描述的字段之外的其它字段也会自动通过 `v-bind` 进行绑定到作用域参数上。
^^^
### 事件
| 名称 | 描述 |
| -- | -- |
| `change` | [^event-change] |
^^^event-change
:::badges
`v-model`
:::
选中状态变化后触发，回调参数为 `(value: Array)`。`value` 为当前按钮组已选项内 `value` 字段组成的数组。
^^^

88
one/docs/components/checkbox-group.md Normal file
View File

@ -0,0 +1,88 @@
# CheckboxGroup <small>复选框组</small>
## 示例
### 尺寸
可选的 `ui` 属性值：`s`/`m`。
[[ demo src="/demo/checkbox-group/default.vue" ]]
## API
### 属性
| 名称 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `ui` | `string=` | - | [^ui] |
| `items` | `Array<Object>` | `[]` | [^items] |
| `value` | `Array` | `[]` | [^value] |
| `disabled` | `boolean=` | `false` | 是否为禁用状态。 |
| `readonly` | `boolean=` | `false` | 是否为只读状态。 |
^^^ui
预设样式。
+++枚举值
| 值 | 描述 |
| -- | -- |
| `m` | 中尺寸样式。 |
| `s` | 小尺寸样式。 |
^^^
^^^items
复选框组数据源，项目类型为 `{label, value, disabled, ...}`。
+++字段详情
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `label` | `string` | 选项的文字说明。 |
| `value` | `*` | 选项对应的值。 |
| `disabled` | `boolean=` | 选项是否为禁用。 |
+++
^^^
^^^value
:::badges
`v-model`
:::
`items` 中已选项的 `value` 列表。
^^^
### 插槽
| 名称 | 描述 |
| -- | -- |
| `item` | [^scoped-slot-item] |
^^^scoped-slot-item
选项描述文本区域。
默认内容：`label` 属性值。
+++作用域参数
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `label` | `string` | 选项文本。 |
| `value` | `*` | 选项值。 |
| `index` | `number` | 选项在 `items` 中的序号。 |
| `disabled` | `boolean=` | 选项是否禁用。 |
+++
另外，`items` 内数据项中除了上面描述的字段之外的其它字段也会自动通过 `v-bind` 进行绑定到作用域参数上。
^^^
### 事件
| 名称 | 描述 |
| -- | -- |
| `change` | [^event-change] |
^^^event-change
:::badges
`v-model`
:::
选中状态变化后触发，回调参数为 `(value: Array)`。`value` 为当前复选框组已选项内 `value` 字段组成的数组。
^^^

83
one/docs/components/checkbox.md Normal file
View File

@ -0,0 +1,83 @@
# Checkbox <small>复选框</small>
## 示例
### 尺寸
可选的 `ui` 属性值：`s`/`m`。
[[ demo src="/demo/checkbox/size.vue" ]]
### 值设定
可以通过设置 `true-value` 和 `false-value` 来修改选中、非选中状态下 `model` 属性（`v-model`）的值。
[[ demo src="/demo/checkbox/value.vue" ]]
## API
### 属性
| 名称 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `ui` | `string=` | - | [^ui] |
| `checked` | `boolean=` | `false` | [^checked] |
| `value` | `*` | - | 当 `v-model` 绑定到数组时，代表当前复选框的值。 |
| `true-value` | `*=` | `true` | 选中状态对应的值。 |
| `false-value` | `*=` | `false` | 未选状态对应的值。 |
| `indeterminate` | `boolean=` | `false` | 是否处于半选状态。 |
| `disabled` | `boolean=` | `false` | 是否为禁用状态。 |
| `readonly` | `boolean=` | `false` | 是否为只读状态。 |
^^^ui
预设样式。
+++枚举值
| 值 | 描述 |
| -- | -- |
| `s` | 小尺寸样式。 |
| `m` | 中尺寸样式。 |
+++
^^^
^^^checked
:::badges
`.sync`
:::
是否处于选中状态。
^^^
### 插槽
| 名称 | 描述 |
| -- | -- |
| `default` | 复选框的描述文本，点击时会切换选择状态。无默认内容。 |
### 事件
| 名称 | 描述 |
| -- | -- |
| `change` | 用户切换选中状态时触发，回调参数为 `(checked: boolean)`。`checked` 表示当前是否选中。 |
| `input` | [^event-input] |
^^^event-input
:::badges
`v-model`
:::
选中状态变化后触发，回调参数为 `(val: *)`。`val` 为当前 `v-model` 的值。与 `change` 事件不同，`input` 事件在数据操作导致状态变化时也会触发。
^^^
此外，`Checkbox` 支持如下的原生事件：
`auxclick`、`click`、`contextmenu`、`dblclick`、`mousedown`、`mouseenter`、`mouseleave`、`mousemove`、`mouseover`、`mouseout`、`mouseup`、`select`、`wheel`、`keydown`、`keypress`、`keyup`、`focus`、`blur`、`focusin`、`focusout`。
回调参数均为相应的原生事件对象。
### 图标
| 名称 | 描述 |
| -- | -- |
| `checked` | 已选状态。 |
| `indeterminate` | 半选状态。 |

52
one/docs/components/collapse.md Normal file
View File

@ -0,0 +1,52 @@
# Collapse <small>折叠面板</small>
:::tip
`Collapse` 组件可以内联在 [`Accordion`](./accordion) 组件中使用。
:::
## 示例
### 尺寸
可选的尺寸 `ui` 属性值：`s`/`m`。
[[ demo src="/demo/collapse/size.vue" ]]
## API
### 属性
| 名称 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `label` | `string` | - | 折叠面板标题。 |
| `expanded` | `boolean=` | `false` | [^expanded] |
| `disabled` | `boolean=` | `false` | 是否为禁用状态。 |
| `name` | `string|number=` | - | 当内联在 [`Accordion`](./accordion) 组件中使用时，用来提供已展开面板的唯一标识。 |
^^^expanded
:::badges
`.sync`
:::
折叠面板是否展开。
^^^
### 插槽
| 名称 | 描述 |
| -- | -- |
| `default` | 折叠式面板内容区。 |
| `title` | 折叠式面板标题区。 |
### 事件
| 名称 | 描述 |
| -- | -- |
| `toggle` | 点击标题区触发展开/收起时触发。回调参数为 `(expanded: boolean)`。`expanded` 为面板是否展开。 |
### 图标
| 名称 | 描述 |
| -- | -- |
| `expand` | 收起状态，点击后展开。 |
| `collapse` | 展开状态，点击后收起。 |

75
one/docs/components/column.md Normal file
View File

@ -0,0 +1,75 @@
# Column <small>表格列</small>
:::tip
`Column` 组件需要在 [`Table`](./table) 组件内使用。
:::
## 示例
见 [`Table` 示例](./table#示例)。
## API
### 属性
| 名称 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `title` | `string` | - | 列标题。 |
| `field` | `string` | - | 列的键名，对应所属的 `Table` 组件 `data` 属性数据项的某个字段。 |
| `width` | `string=|number=` | - | 列宽，值为像素值。 |
| `sortable` | `boolean=` | `false` | [^sortable] |
| `align` | `string=` | - | 内容对齐方式，支持 `left`/`center`/`right`。 |
| `span` | `function(number)=: Object` | | [^span] |
^^^sortable
本列是否支持排序。
:::warning
组件本身不会处理排序逻辑，仅会在排序按钮被点击时在 `Table` 上抛出 `sort` 事件，使用者需要自行处理排序逻辑。
:::
^^^
^^^span
单元格合并配置。类型为 `function(index: number): { row: number, col: number }`。`index` 为当前行在所属 `Table` 组件的 `data` 属性中的索引。返回值的 `row`/`col` 字段对应于单元格的 `rowspan`/`colspan`，默认值均为 `1`。
:::tip
可以参考 `Table` 组件中的[示例 › 高级](./table#高级)来了解如何使用。
:::
^^^
### 插槽
| 名称 | 描述 |
| -- | -- |
| `head` | 列头区域。 |
| `foot` | [^slot-foot] |
| `default` | [^scoped-slot-default] |
| `sub-row` | [^scoped-slot-sub-row] |
^^^slot-foot
列脚区域。
:::warning
如果所属的 `Table` 组件定义了 `foot` 插槽，单独的列脚配置将被覆盖。
:::
^^^
^^^scoped-slot-default
单元格的内容。
默认内容：表格 `data` 数据项中与 `field` 属性对应的字段值。
作用域参数为 `data` 内当前行数据中的所有字段。
^^^
^^^scoped-slot-sub-row
展开行后子行的内容。使用此插槽时，内容会作为行展开下方子行中对应列的单元格内容。行数据源来自 `data` 中对应主行数据的 `children` 数组，展开的子行数与 `children` 内数据项数相同，使用相同的列配置。
默认内容：表格 `data[i].children[j]` 数据项中与 `field` 属性对应的字段值。
作用域参数当前子行数据中的所有字段，以及当前主行对应索引值 `index`。
:::warning
如果所属的 `Table` 组件定义了作用域插槽 `sub-row`，单独列的 `sub-row` 将被覆盖。
:::
^^^

41
one/docs/components/confirm-box.md Normal file
View File

@ -0,0 +1,41 @@
# ConfirmBox <small>确认弹框</small>
## 示例
自定义标题和内容区。
[[ demo src="/demo/confirm-box/custom.vue"]]
## API
### 属性
| 名称 | 类型 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `open` | `boolean` | `false` | [^open] |
| `title` | `string=` | - | 标题。 |
| `overlay-class` | `string|Array|Object=` | - | 参考 [Overlay](./overlay) 组件的 `overlay-class` 属性。 |
^^^open
:::badges
`.sync`
:::
是否显示确认弹框。
^^^
### 插槽
| 名称 | 描述 |
| -- | -- |
| `default` | 内容区。 |
| `title` | 标题区。若同时指定了 `title` 属性和 `title` 插槽，以后者为准。 |
| `foot` | 底部区域，默认会展示“确定”、“取消”按钮。 |
### 事件
| 名称 | 描述 |
| -- | -- |
| `ok` | 点击“确定”按钮时触发。 |
| `cancel` | 点击“取消”按钮时触发。 |
| `afterclose` | 浮层关闭后触发。如果样式主题提供了退出动画，将在退出动画完毕后触发。 |

214
one/docs/components/date-picker.md Normal file
View File

@ -0,0 +1,214 @@
# DatePicker <small>日期选择</small>
## 示例
### 单日选择
默认情况下，在下拉浮层中单击日期可以选中一个日期。可以配置 `clearable` 属性来允许清除已选值，用 `placeholder` 属性来配置未选择时的占位文本。
[[ demo src="/demo/date-picker/default.vue" ]]
### 日期范围选择
配置 `range` 属性时，可以在下拉浮层中选择一个日期范围。
[[ demo src="/demo/date-picker/range.vue" ]]
### 设置快捷选项
选择日期范围时，可以通过配置 `shortcuts` 属性来提供快捷选项。
[[ demo src="/demo/date-picker/shortcuts.vue" ]]
## API
### 属性
| 名称 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `type` | `string` | `'date'` | 日历的类型，可用值为 `'date'`/`'month'`/`'year'`，分别对应日期/月/年视图。 |
| `range` | `boolean` | `false` | 是否选择日期范围。 |
| `selected` | `Date|Array` | - | [^selected] |
| `today` | `Date` | `new Date()` | 「今天」的日期。 |
| `week-start` | `number` | `calendar.weekStart` | 一周的起始。可进行[全局配置](./calendar#全局配置)。 |
| `fill-month` | `boolean` | `true` | 当只有一个面板时，是否要在当前月份面板显示非本月日期。 |
| `date-class` | `string|Array|Object|function` | `{}` | 特定日期的自定义 HTML `class`。传非函数时，数据格式为所有 Vue 支持的 `class` 表达式；传函数时，签名为 `function(Date): string|Array<string>|Object<string, boolean>`，返回值格式亦为所有 Vue 支持的 `class` 表达式。 |
| `disabled-date` | `function(Date): boolean` | `() => false` | 特定日期是否禁用。 |
| `clearable` | `boolean` | `false` | 已选值是否可以清除。 |
| `placeholder` | `string` | `range ? datepicker.rangePlaceholder : datepicker.placeholder` | 未选择时的占位文本。可进行[全局配置](#全局配置)。 |
| `format` | `string` | `'yyyy-MM-dd'`/`'yyyy-MM'`/`'yyyy'` | 用于格式化的字符串表达式，具体格式可以参见 [date-fns 的文档](https://date-fns.org/v2.12.0/docs/format)。 |
| `shortcuts` | `Array<Object>` | `datepicker.shortcuts` | [^shortcuts] |
| `disabled` | `boolean=` | `false` | 是否为禁用状态。 |
| `readonly` | `boolean=` | `false` | 是否为只读状态。 |
^^^selected
:::badges
`v-model`
:::
已选日期（范围）的值，根据 `range` 属性值的不同，数据格式不同。
+++类型详情
| `range` | 类型 |
| -- | -- |
| `false` | `Date` |
| `true` | `[Date, Date]` |
+++
^^^
^^^shortcuts
在选择范围时，可以定制的浮层中的快捷选择项列表，格式为 `Array<{label, from, to}>`。可进行[全局配置](#全局配置)。
+++字段详情
<table>
<thead>
<tr>
<th>名称</th>
<th>类型</th>
<th>描述</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>label</code></td>
<td><code>string</code></td>
<td>快捷选项的文本。</td>
</tr>
<tr>
<td><code>from</code></td>
<td colspan="2">开始时间计算方式，见下方<a href="#快捷选项偏移量数据格式">快捷选项偏移量数据格式</a>描述。</td>
</tr>
<tr>
<td><code>to</code></td>
<td colspan="2">结束时间计算方式，见下方<a href="#快捷选项偏移量数据格式">快捷选项偏移量数据格式</a>描述。</td>
</tr>
</tbody>
</table>
+++
^^^
#### 快捷选项偏移量数据格式
`shortcuts` 列表项中的 `from` 及 `to` 字段格式相同，分别用来设置开始结束日期的计算方式。格式为 `number|Object`，默认值为 `0`。
* 类型为 `number` 时，表示以「今天」为基准，偏移指定天数，比如 `-1` 等价于 `{ startOf: 'day', days: -1 }`，即「昨天」；
* 类型为 `Object` 时，支持的格式为：`{startOf: string=, days: number=, weeks: number=, months: number=, }`。
+++字段详情
| 名称 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `startOf` | `string=` | `'day'` | 起始日期基准，支持的值有 `'day'`/`'week'`/`'month'`/`'quarter'`/`'year'`。 |
| `day` | `number=` | - | 偏移的天数。 |
| `week` | `number=` | - | 偏移的周数。 |
| `month` | `number=` | - | 偏移的月数。 |
| `quarter` | `number=` | - | 偏移的季度数。 |
| `year` | `number=` | - | 偏移的年数。 |
计算方式是先根据 `startOf` 设置基准，然后根据其它字段进行偏移量的叠加。
可以根据下面的例子，结合 `label` 理解计算方式。掌握以后，就可以非常快速地对快捷选项进行设置了。
```js
[
{
label: '上个月',
// 本月第一天往前算一个月，即上月第一天
from: {
startOf: 'month',
month: -1
},
// 本月第一天往前算一天，即上月最后一天
to: {
startOf: 'month',
days: -1
}
},
{
label: '本月',
// 本月第一天
from: {
startOf: 'month'
},
// 今天
to: 0
},
{
label: '本周',
// 本周第一天，days 为 0 是可以省略的
from: {
startOf: 'week',
days: 0
},
// 今天
to: 0
},
{
label: '最近7天',
// 往前算 6 天
from: -6,
// 到今天
to: 0
},
{
label: '今天',
to: 0
}
]
```
### 插槽
| 名称 | 描述 |
| -- | -- |
| `date` | [^scoped-slot-date] |
^^^scoped-slot-date
浮层中日历的单日单元格内的区域，可用来定制每一天对应区域的内容。
默认内容：对应日期的 `date`。
+++作用域参数
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `year` | `number` | 完整年份。 |
| `month` | `number` | 月份数，`0` 表示一月。 |
| `date` | `number` | 月份内的日期。 |
+++
^^^
### 事件
| 名称 | 描述 |
| -- | -- |
| `select` | [^event-select] |
^^^event-select
:::badges
`v-model`
:::
选择修改后触发，回调参数为 `(selected)`。数据类型和 `selected` 属性一致。
^^^
### 全局配置
| 配置项 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `datepicker.shortcuts` | `Array` | `[]` | 快捷选项配置。 |
| `datepicker.placeholder` | `string` | `@@datepicker.selectDate` | 选择单日时，未选择状态的占位文本。 |
| `datepicker.monthPlaceholder` | `string` | `@@datepicker.selectMonth` | 选择月份时，未选择状态的占位文本。 |
| `datepicker.yearPlaceholder` | `string` | `@@datepicker.selectYear` | 选择年时，未选择状态的占位文本。 |
| `datepicker.rangePlaceholder` | `string` | `@@datepicker.selectRange` | 选择日期范围时，未选择状态的占位文本。 |
| `datepicker.monthRangePlaceholder` | `string` | `@@datepicker.selectMonthRange` | 选择月份范围时，未选择状态的占位文本。 |
| `datepicker.yearRangePlaceholder` | `string` | `@@datepicker.selectYearRange` | 选择年份范围时，未选择状态的占位文本。 |
:::tip
`@@` 开头的值表示引用多语言配置中的相应字段。
:::
### 图标
| 名称 | 描述 |
| -- | -- |
| `calendar` | 日历。 |
| `clear` | 清除内容。 |

130
one/docs/components/dialog.md Normal file
View File

@ -0,0 +1,130 @@
# Dialog <small>对话框</small>
## 示例
### 模态与非模态
[[ demo src="/demo/dialog/modal.vue" ]]
### 自定义内容
[[ demo src="/demo/dialog/custom.vue" ]]
### 异步支持
[[ demo src="/demo/dialog/async.vue" ]]
### 可拖拽
[[ demo src="/demo/dialog/draggable.vue" ]]
### 层叠顺序
[[ demo src="/demo/dialog/stack.vue" ]]
## API
### 属性
| 名称 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `ui` | `string=` | - | [^ui] |
| `modal` | `boolean=` | `true` | 是否是模态对话框。模态对话框默认遮挡底层（无法点击）且抢占焦点（关闭后焦点会回归）。 |
| `title` | `string=` | - | 对话框标题文本。如果指定了 `title` 插槽，则优先使用 `title` 插槽。 |
| `open` | `boolean` | `false` | [^open] |
| `closable` | `boolean=` | `true` | 是否显示关闭按钮。 |
| `outside-closable` | `boolean=` | `false` | 点击对话框外部时是否关闭对话框。 |
| `draggable` | `boolean=` | `false` | 是否可拖拽。 |
| `escapable` | `boolean=` | `false` | 按下 <kbd>esc</kbd> 键是否可以关闭对话框。仅在 `closable` 为 `true` 时生效。 |
| `inline` | `boolean=` | `false` | 是否内联在内容中显示并占用内容空间。 |
| `footless` | `boolean=` | `false` | 是否不显示默认的底部操作栏。 |
| `loading` | `boolean=` | `false` | 是否处于加载状态。处于加载状态时确定按钮也将进入加载状态，无法点击。 |
| `priority` | `number=` | - | 对话框浮层层叠权重，参考 [`Overlay`](./overlay) 组件的 [`priority`](./overlay#props) 属性。 |
| `before-close` | `function(string)=: boolean=|Promise<boolean=>` | - | [^before-close] |
| `overlay-class` | `string|Object=` | - | 对话框浮层根元素类名，参考 [`Overlay`](./overlay) 组件的 [`overlay-class`](./overlay#props) 属性。 |
^^^ui
预设样式。
+++枚举值
| 值 | 描述 |
| -- | -- |
| `s` | 小内容尺寸（内容及部件尺寸，非对话框整体空间大小）。 |
| `m` | 中内容尺寸（内容及部件尺寸，非对话框整体空间大小）。 |
| `narrow` | 窄尺寸样式。 |
| `medium` | 中尺寸样式。 |
| `wide` | 宽尺寸样式。 |
| `fullscreen` | 全屏尺寸样式。 |
| `auto` | 自适应尺寸样式。 |
+++
^^^
^^^open
:::badges
`.sync`
:::
是否显示对话框。
^^^
^^^before-close
在将触发对话框关闭的操作发生后执行，类型为 `function(type: string): boolean=|Promise<boolean=>`。`type` 为触发关闭的类型，默认情况下可选值为 `'ok'|'cancel'`。返回值可以是一个 `boolean`，也可以是一个 resolve `boolean` 的 `Promise`，用来处理可能需要异步决定对话框关闭状态的情况。返回值或 resolve 值非 `false` 时才会关闭对话框。
+++调用示例
```html
<veui-dialog :open.sync="dialogOpen" :before-close="submit">...</veui-dialog>
```
```js
methods: {
submit (type) {
if (type === 'ok') {
return axios.post('/item/create', {/* ... */})
.then(({ id, error }) => {
if (error) {
this.showError(error)
return false // resolve `false` 将阻止对话框关闭
}
})
}
// resolve 但不返回 `false` 时会关闭对话框
},
// ...
}
```
+++
^^^
### 插槽
| 名称 | 描述 |
| -- | -- |
| `default` | 内容区。 |
| `title` | 标题区。若同时指定了 `title` 属性和 `title` 插槽，以后者为准。 |
| `foot` | [^slot-foot] |
^^^slot-foot
底部区域，默认会展示“确定”、“取消”按钮。
+++作用域参数
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `close` | `function(type: string): void` | 触发对话框关闭的回调函数。`type` 为关闭的类型，将作为参数传入 `before-close` 钩子函数作为参数，同时将同步触发同名的事件。 |
+++
^^^
### 事件
| 名称 | 描述 |
| -- | -- |
| `ok` | 点击“确定”按钮时或通过调用作用域函数 `close('ok')` 时触发。 |
| `cancel` | 点击“取消”按钮、关闭按钮、通过 <kbd>esc</kbd> 关闭对话框时，或者通过调用作用域函数 `close('cancel')` 时触发。 |
| <var>&lt;value&gt;</var> | 通过调用作用域函数 `close(value)` 时触发。 |
| `afterclose` | 浮层关闭后触发。如果样式主题提供了退出动画，将在退出动画完毕后触发。 |
### 图标
| 名称 | 描述 |
| -- | -- |
| `close` | 关闭。 |

98
one/docs/components/drawer.md Normal file
View File

@ -0,0 +1,98 @@
# Drawer <small>抽屉</small>
## 示例
### 位置
使用 `placement` 属性控制抽屉弹出的位置。
[[ demo src="/demo/drawer/placement.vue" ]]
### 模态与非模态
使用 `modal` 属性控制抽屉是否为模态类型。
[[ demo src="/demo/drawer/modal.vue" ]]
### 自定义内容
[[ demo src="/demo/drawer/custom.vue" ]]
## API
### 属性
| 名称 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `ui` | `string=` | - | [^ui] |
| `placement` | `string` | `'right'` | [^placement] |
| `modal` | `boolean` | `true` | 是否是模态抽屉。模态抽屉默认遮挡底层（无法点击）且抢占焦点（关闭后焦点会回归）。 |
| `title` | `string` | - | 抽屉标题文本。如果指定了 `title` 插槽，则优先使用 `title` 插槽。 |
| `open` | `boolean` | `false` | [^open] |
| `closable` | `boolean` | `true` | 是否显示关闭按钮。 |
| `outside-closable` | `boolean` | `false` | 点击抽屉外部时是否关闭抽屉。 |
| `draggable` | `boolean` | `false` | 是否可拖拽。 |
| `escapable` | `boolean` | `false` | 按下 <kbd>esc</kbd> 键是否可以关闭抽屉。仅在 `closable` 为 `true` 时生效。 |
| `footless` | `boolean` | `false` | 是否不显示默认的底部操作栏。 |
| `before-close` | `function(string): boolean=|Promise<boolean=>` | - | 在将触发抽屉关闭的操作发生后执行，参考 [`Dialog`](./dialog) 组件的 [`before-close`](./dialog#props) 属性。 |
| `overlay-class` | `string|Object` | - | 抽屉浮层根元素类名，参考 [`Overlay`](./overlay) 组件的 [`overlay-class`](./overlay#props) 属性。 |
^^^ui
预设样式。
+++枚举值
| 值 | 描述 |
| -- | -- |
| `s` | 小内容尺寸（内容及部件尺寸，非抽屉整体空间大小）。 |
| `m` | 中内容尺寸（内容及部件尺寸，非抽屉整体空间大小）。 |
+++
^^^
^^^placement
抽屉位置。
+++枚举值
| 值 | 描述 |
| -- | -- |
| `top` | 从上面滑出。 |
| `right` | 从右面滑出。 |
| `bottom` | 从下面滑出。 |
| `left` | 从左面滑出。 |
+++
^^^
^^^open
:::badges
`.sync`
:::
是否显示抽屉。
^^^
### 插槽
| 名称 | 描述 |
| -- | -- |
| `default` | 内容区。 |
| `title` | 标题区。若同时指定了 `title` 属性和 `title` 插槽，以后者为准。 |
| `foot` | [^slot-foot] |
^^^slot-foot
底部区域，默认会展示“确定”、“取消”按钮。
+++作用域参数
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `close` | `function(type: string): void` | 触发抽屉关闭的回调函数。`type` 为关闭的类型，将作为参数传入 `before-close` 钩子函数作为参数，同时将同步触发同名的事件。 |
+++
^^^
### 事件
| 名称 | 描述 |
| -- | -- |
| `ok` | 点击“确定”按钮时或通过调用作用域函数 `close('ok')` 时触发。 |
| `cancel` | 点击“取消”按钮、关闭按钮、通过 <kbd>esc</kbd> 关闭抽屉时，或者通过调用作用域函数 `close('cancel')` 时触发。 |
| <var>&lt;value&gt;</var> | 通过调用作用域函数 `close(value)` 时触发。 |
| `afterclose` | 浮层关闭后触发。如果样式主题提供了退出动画，将在退出动画完毕后触发。 |

169
one/docs/components/dropdown.md Normal file
View File

@ -0,0 +1,169 @@
# Dropdown <small>下拉菜单</small>
:::tip
`Dropdown` 组件可以内联 [`Option`](./option) 或 [`OptionGroup`](./option-group) 组件使用。
:::
## 示例
### 样式
可选的样式 `ui` 属性值： `primary`/`text`。
[[ demo src="/demo/dropdown/style.vue" ]]
### 尺寸
可选的尺寸 `ui` 属性值：`xs`/`s`/`m`/`l`。
[[ demo src="/demo/dropdown/size.vue" ]]
### 内联模式
`Dropdown` 组件内支持内联使用 `OptionGroup` 及 `Option` 组件来代替 `options` 属性。
[[ demo src="/demo/dropdown/inline.vue" ]]
### 含搜索的下拉框菜单
使用 `searchable` 属性使组件支持搜索并高亮显示符合条件的选项。
[[ demo src="/demo/dropdown/searchable.vue" ]]
### 禁用状态的下拉框菜单
使用数据源中的 `disabled` 属性来禁用下拉项。
[[ demo src="/demo/dropdown/disable.vue" ]]
### 下拉触发时机与分离按钮
使用 `trigger` 属性指定展开下拉菜单的时机，使用 `split` 属性来使命令按钮与下拉按钮分离。
[[ demo src="/demo/dropdown/other.vue" ]]
## API
### 属性
| 名称 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `ui` | `string=` | - | [^ui] |
| `options` | `Array<Object>=` | `[]` | [^options] |
| `label` | `string` | - | 下拉按钮的描述文本。 |
| `trigger` | `string=` | `'click'` | 触发下拉框展开的时机，可选值为 `'click'`/`'hover'`。 |
| `split` | `boolean=` | `false` | 是否将下拉按钮分离为指令按钮和切换下拉按钮两部分。 |
| `disabled` | `boolean=` | `false` | 是否为禁用状态。 |
| `overlay-class` | `string|Array|Object=` | - | 参考 [Overlay](./overlay) 组件的 [`overlay-class` 属性](./overlay#属性)。 |
^^^ui
预设样式。
+++枚举值
| 值 | 描述 |
| -- | -- |
| `primary` | 主题色样式。 |
| `text` | 文字样式。 |
| `xs` | 特小尺寸样式。 |
| `s` | 小尺寸样式。 |
| `m` | 中等尺寸样式。 |
| `l` | 大尺寸样式。 |
+++
^^^
^^^options
选项列表，项目的类型为 `{label, value, options, disabled, ...}`。
+++字段详情
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `label` | `string` | 选项的文字说明。 |
| `value` | `*` | 选项对应的值。 |
| `options` | `Array<Object>=` | 选项的子选项数组，数组项类型同 `options` 属性数组项。 |
| `disabled` | `boolean=` | 选项是否为禁用。 |
+++
^^^
### 插槽
| 名称 | 描述 |
| -- | -- |
| `default` | 选项列表的内容。在没有指定 `options` 属性时，可以用来直接内联 `Option` 或 `OptionGroup` |
| `before` | 选项列表前的内容。无默认内容。 |
| `after` | 选项列表后的内容。无默认内容。 |
| `label` | [^scoped-slot-label] |
| `group-label` | [^scoped-slot-group-label] |
| `option-label` | [^scoped-slot-option-label] |
| `option` | [^scoped-slot-option] |
^^^scoped-slot-label
下拉按钮文本区域。
默认内容：`label` 属性值。
+++作用域参数
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `label` | `string` | `label` 属性对应文本。 |
+++
^^^
^^^scoped-slot-group-label
下拉选项组（带 `options` 的选项）的标题文本区域。
默认内容：选项的 `label` 属性值。
+++作用域参数
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `label` | `string` | 选项组标题文本。 |
| `disabled` | `boolean=` | 选项组是否禁用。 |
+++
另外，当前选项数据中除了上面描述的字段之外的其它字段也会自动通过 `v-bind` 进行绑定到作用域参数上。
^^^
^^^scoped-slot-option-label
下拉选项（不带 `options` 的选项）的文本区域。
默认内容：选项的 `label` 属性值。
+++作用域参数
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `label` | `string` | 选项文本。 |
| `value` | `*` | 选项值。 |
| `disabled` | `boolean=` | 选项是否禁用。 |
+++
另外，当前选项数据中除了上面描述的字段之外的其它字段也会自动通过 `v-bind` 进行绑定到作用域参数上。
^^^
^^^scoped-slot-option
可供选择的下拉选项的整个区域。
默认内容：`Option` 内的组件默认结构。
+++作用域参数
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `label` | `string` | 选项文本。 |
| `value` | `*` | 选项值。 |
| `disabled` | `boolean=` | 选项是否禁用。 |
+++
另外，当前选项数据中除了上面描述的字段之外的其它字段也会自动通过 `v-bind` 进行绑定到作用域参数上。
^^^
### 事件
| 名称 | 描述 |
| -- | -- |
| `click` | 点击选项后触发，回调参数为 `(value: *=)`。`value` 为当前已选项 `value` 字段的值。当 `split` 属性为 `true` 时，直接点击指令按钮部分也会触发，但不会携带 `value` 参数。 |
### 图标
| 名称 | 描述 |
| -- | -- |
| `expand` | 展开浮层。 |
| `collapse` | 收起浮层。 |

72
one/docs/components/embedded.md Normal file
View File

@ -0,0 +1,72 @@
# Embedded <small>嵌入式面板</small>
## 示例
### 尺寸
可选的尺寸 `ui` 属性值：`xs`/`s`/`m`/`l`/`xl`。
[[ demo src="/demo/embedded/size.vue" ]]
## API
### 属性
| 名称 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `ui` | `string=` | - | [^ui] |
| `title` | `string=` | - | 折叠式面板标题文本。如果指定了 `title` 插槽，则优先使用 `title` 插槽。 |
| `open` | `boolean` | `false` | [^open] |
| `closable` | `boolean=` | `true` | 是否显示关闭按钮。 |
| `footless` | `boolean=` | `false` | 是否不显示默认的底部操作栏。 |
| `loading` | `boolean=` | `false` | 是否处于加载状态。处于加载状态时确定按钮也将进入加载状态，无法点击。 |
| `priority` | `number=` | - | 折叠式面板浮层层叠权重，参考 [`Overlay`](./overlay) 组件的 [`priority`](./overlay#props) 属性。 |
| `before-close` | `function(string)=: boolean=|Promise<boolean=>` | - | 在将触发折叠式面板关闭的操作发生后执行，参考 [`Dialog`](./dialog) 组件的 [`before-close`](./dialog#props) 属性。 |
| `overlay-class` | `string|Object=` | - | 折叠式面板浮层根元素类名，参考 [`Overlay`](./overlay) 组件的 [`overlay-class`](./overlay#props) 属性。 |
^^^ui
预设样式。
+++枚举值
| 值 | 描述 |
| -- | -- |
| `s` | 小内容尺寸。 |
| `m` | 中内容尺寸。 |
+++
^^^
^^^open
:::badges
`.sync`
:::
是否显示折叠式面板。
^^^
### 插槽
| 名称 | 描述 |
| -- | -- |
| `default` | 内容区。 |
| `title` | 标题区。若同时指定了 `title` 属性和 `title` 插槽，以后者为准。 |
| `foot` | [^slot-foot] |
^^^slot-foot
底部区域，默认会展示“确定”、“取消”按钮。
+++作用域参数
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `close` | `function(type: string): void` | 触发折叠式面板关闭的回调函数。`type` 为关闭的类型，将作为参数传入 `before-close` 钩子函数作为参数，同时将同步触发同名的事件。 |
+++
^^^
### 事件
| 名称 | 描述 |
| -- | -- |
| `ok` | 点击“确定”按钮时或通过调用作用域函数 `close('ok')` 时触发。 |
| `cancel` | 点击“取消”按钮、关闭按钮、通过 <kbd>esc</kbd> 关闭折叠式面板时，或者通过调用作用域函数 `close('cancel')` 时触发。 |
| <var>&lt;value&gt;</var> | 通过调用作用域函数 `close(value)` 时触发。 |
| `afterclose` | 浮层关闭后触发。如果样式主题提供了退出动画，将在退出动画完毕后触发。 |

131
one/docs/components/field.md Normal file
View File

@ -0,0 +1,131 @@
# Field <small>表单项</small>
:::tip
`Field` 组件需要配合 [`Form`](./form) 及 [`Fieldset`](./fieldset) 组件使用。一个 `Field` 对应一个输入组件。
:::
## 示例
见 [`Form` 示例](./form#示例)。
## API
### 属性
| 名称 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `ui` | `string=` | - | [^ui] |
| `readonly` | `boolean=` | `false` | 内部输入组件是否为只读状态。 |
| `disabled` | `boolean=` | `false` | 内部输入组件是否为禁用状态。 |
| `label` | `string` | - | 表单项描述。 |
| `tip` | `string` | - | 表单项提示。 |
| `name` | `string` | - | 表单项名称，可用于指定数据字段名或展示错误消息的定位。 |
| `field` | `string` | - | [^field] |
| `rules` | `string|Array<Object>` | - | [^rules] |
^^^ui
预设样式。
+++枚举值
| 值 | 描述 |
| -- | -- |
| `xs` | 超小尺寸样式。 |
| `s` | 小尺寸样式。 |
| `m` | 中尺寸样式。 |
| `l` | 大尺寸样式。 |
+++
^^^
^^^message
出错信息，可以覆盖规则默认出错信息。
若类型为 `string`，可以通过 `{ruleValue}` 引用 `ruleValue`、`{value}` 引用 `value`。例如：
```js
let minLengthRule = {
validate (value, ruleValue) {
return !isEmpty(value) ? val.length >= ruleValue : true
},
message: '字符长度不能短于 {ruleValue}，当前长度 {value}',
priority: 100
}
```
若类型为 `function`，参数为 `(ruleValue: ?*=, value: *)`。例如：
```js
let minLengthRule = {
validate (value, ruleValue) {
return !isEmpty(value) ? val.length >= ruleValue : true
},
message (ruleValue, value) {
return `字符长度不能短于${ruleValue}，当前长度${value}`
},
priority: 100
}
```
:::tip
如果需要支持多语言，`message` 必须使用 `function` 类型。
:::
^^^
^^^rules
表单项校验规则，同步的单值校验。对于 `Array` 类型，项目的类型为 `{triggers, name, message, value, priority}`。
+++字段详情
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `triggers` | `string` | 触发校验的事件名称集合，逗号分隔。 |
| `name` | `string` | 规则名称。 |
| `value` | `*` | 规则要匹配的值。`boolean` 类型的规则，默认为 `true`。 |
| `message` | `string|function` | [^message] |
| `priority` | `number` | 规则优先级，可以覆盖规则默认优先级。 |
+++
+++内置规则
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `required` | `boolean` | 值不能为空值（`null`/`undefined`/`''`/`[]`）。 |
| `numeric` | `boolean` | 值必须可描述十进制数值。(`6`/`66.6`/`6e6`/`'6'`/`.6`) |
| `pattern` | `RegExp|string` | 正则匹配。 |
| `maxLength` | `number` | 值的 `length` 属性不能大于限定值。 |
| `minLength` | `number` | 值的 `length` 属性不能小于限定值。 |
| `max` | `number` | 值不能大于限定值。 |
| `min` | `number` | 值不能小于限定值。 |
+++
:::warning
对于 `string` 类型，格式为 `rule1,rule2,...`，仅支持 `value` 类型为 `boolean` 的规则。
优先级会影响最后展示的出错信息，出错信息栈内会保留所有规则的错误提示，但仅展现优先级最高的那一个。
自定义 `rule` 请参考[高级 › 自定义校验规则](../advanced/custom-rules)。
:::
^^^
^^^field
非必须，默认取 `name` 属性值。在特殊情况下，用于指定表单 `data` 属性对应字段的路径。
+++格式示例
| 值 | 描述 |
| -- | -- |
| `username` | 对应表单 `data` 属性引用值的 `username` 属性，等价于 `data.username`。 |
| `users[0]` | 等价于 `data.users[0]`。 |
| `user.username` | 等价于 `data.user.username`。 |
+++
^^^
### 插槽
| 名称 | 描述 |
| -- | -- |
| `default` | 用于内联输入组件。无默认内容。 |
| `label` | 填充表单项描述的内容。默认为 `label` 属性的文本值。 |
| `tip` | 填充表单项提示的内容。默认为 `tip` 属性的文本值。 |
### 图标
| 名称 | 描述 |
| -- | -- |
| `alert` | 警示图标。 |

30
one/docs/components/fieldset.md Normal file
View File

@ -0,0 +1,30 @@
# Fieldset <small>表单项集合</small>
:::tip
`Fieldset` 组件需要配合 [`Form`](./form) 及 [`Field`](./field) 组件使用。一个 `Fieldset` 可以包含多个 `Field`。
:::
## 示例
见 [`Form` 示例](./form#示例)。
## API
### 属性
| 名称 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `readonly` | `boolean=` | `false` | 内部输入组件是否为只读状态。 |
| `disabled` | `boolean=` | `false` | 内部输入组件是否为禁用状态。 |
| `label` | `string` | - | 表单项集合描述。 |
| `tip` | `string` | - | 表单项集合提示。 |
| `name` | `string` | - | 表单项集合名称，用于展示错误消息的定位。 |
| `required` | `boolean` | - | 是否显示必要性星号提示。 |
### 插槽
| 名称 | 描述 |
| -- | -- |
| `default` | 用于内联 `Field` 组件。无默认内容。 |
| `label` | 填充表单项集合描述的内容。默认为 `label` 属性的文本值。 |
| `tip` | 填充表单项集合提示的内容。默认为 `tip` 属性的文本值。 |

58
one/docs/components/filter-panel.md Normal file
View File

@ -0,0 +1,58 @@
# FilterPanel <small>过滤面板</small>
## 示例
[[ demo src="/demo/filter-panel/default.vue"]]
## API
### 属性
| 名称 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `datasource` | `Array<Object>` | `[]` | 数据源，项目类型为 `{label: string, ...}`。 |
| `searchable` | `boolean=` | `true` | 是否允许搜索。 |
| `filter` | `function=` | 见描述 | [^filter] |
| `search-on-input` | `boolean=` | `true` | 是否在输入的时候触发搜索。 |
| `placeholder` | `string=` | - | 搜索框的占位符。 |
^^^filter
搜索过滤函数，签名为 `function(keyword, item, index, datasource): boolean`。返回值为 `false` 的项目将被从结果中过滤掉。
+++参数详情
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `keyword` | `string` | 搜索关键词。 |
| `item` | `Object` | 当前遍历到的数据节点。 |
| `index` | `number` | 当前数据节点在兄弟节点中的索引。 |
| `datasource` | `Array<{label: string, ...}>` | 与 `datasource` 属性一致。 |
+++
+++默认值
```js
import { includes } from 'lodash'
function (keyword, { label }) {
return includes(label, keyword)
}
```
+++
^^^
### 插槽
| 名称 | 描述 |
| -- | -- |
| `head` | 标题区域。默认显示 `title` 属性值。 |
| `no-data` | `datasource` 中没数据时显示的内容。 |
| `default` | [^default] |
^^^default
主内容区域。
+++参数属性
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `items` | `Array<Object>` | `datasource` 经过过滤后的数据，类型与 `datasource` 保持一致。 |
+++
^^^

198
one/docs/components/form.md Normal file
View File

@ -0,0 +1,198 @@
# Form <small>表单</small>
:::tip
`Form` 组件需要配合 [`Fieldset`](./fieldset) 及 [`Field`](./field) 组件使用。
:::
## 示例
### 基础样式
使用 `actions` 插槽来提供表单操作按钮。
[[ demo src="/demo/form/normal.vue" ]]
### 只读状态
设置 `readonly` 来使内部表单项处于只读状态。
[[ demo src="/demo/form/readonly.vue" ]]
### 禁用状态
设置 `disabled` 来使内部表单项处于禁用状态。
[[ demo src="/demo/form/disabled.vue" ]]
### 校验
[[ demo src="/demo/form/validate.vue" ]]
## API
### 属性
| 名称 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `readonly` | `boolean=` | `false` | 内部输入组件是否为只读状态。 |
| `disabled` | `boolean=` | `false` | 内部输入组件是否为禁用状态。 |
| `data` | `Object` | - | [^data] |
| `validators` | `Array<Object>=` | - | [^validators] |
| `before-validate` | `function=` | - | 表单进入提交流程后，进行校验之前的 hook，传入参数为 `(data)`，`data` 为表单 `data` 属性值的副本。支持返回 `Promise`，返回值或 `Promise.resolve` 的值为 `true` 或 `undefined` 表示流程继续，其它返回值表示中断流程并触发 [`invalid`](#事件) 事件。|
| `after-validate` | `function=` | - | 表单校验成功后，触发 `submit` 事件之前的 hook，传入参数为 `(data)`，与 `beforeValidate` 的入参是同一个引用。支持返回 `Promise`，返回值或 `Promise.resolve` 的值为 `true` 或 `undefined` 表示流程继续，其它返回值表示中断流程并触发 [`invalid`](#事件) 事件。|
^^^data
表单绑定的数据，和表单中的输入组件通过 `v-model` 绑定，也是表单校验时的数据源。
:::warning
[`Field`](./field) 如果处于 `disabled` 状态，提交流程中处理 `data` 副本时其对应的数据键值对会被过滤，校验时同理。
:::
^^^
^^^validators
表单联合校验、异步校验器。项目类型为 `{fields, validate, triggers}`。
+++属性详情
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `fields` | `Array` | 对应 `Field` 的 `field` 描述的集合。事件会绑定到对应 `Field` 中的输入组件上。 |
| `validate` | `function` | 自定义校验函数，传入参数为 `(data[fields[0]], data[fields[1]], ...)`，`data` 为表单 `data` 属性值的引用。返回 `undefined`/`true` 代表校验成功，返回 `{[field]: message, ...}` 表示校验失败信息，详见[表单 › 表单校验逻辑](#表单校验逻辑)。 |
| `triggers` | `string|Array<string>` | 事件名称集合。 |
+++
+++规则详情
| `fields` | `triggers` | 绑定事件情况 |
| -- | -- | -- |
| `['a']` | `['change', 'blur,input,xxx', 'submit']` | a(change) |
| `['a','b','c']` | `['change', 'blur,input,xxx', 'submit']` | a(change), b(blur,input,xxx), c(submit) |
| `['a','b','c']` | `'blur'` | a(blur), b(submit), c(submit) |
| `['a','b','c']` | `'blur,input'` | a(blur,input), b(blur,input), c(blur,input) |
+++
^^^
### 插槽
| 名称 | 描述 |
| -- | -- |
| `default` | 可直接内联 `Fieldset` 或 `Field` 组件。无默认内容。 |
| `actions` | 表单操作内容，如“提交”、“取消”按钮等。无默认内容。 |
### 事件
| 名称 | 描述 |
| -- | -- |
| `submit` | [^event-submit] |
| `invalid` | [^event-invalid] |
^^^event-submit
在原生 `submit` 事件之后触发，回调参数为 `(data, event)`。具体提交流程请参考[表单 › 表单提交流程](#表单提交流程)。
+++参数详情
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `data` | `Object` | 表单 `data` 属性值的引用。 |
| `event` | `Event` | 原生事件对象。 |
+++
^^^
^^^event-invalid
`beforeValidate`、`validate`、`afterValidate` 流程中某一项返回中断时触发，回调参数为流程 function 的返回值，参数为 `(result)`，表示流程中断的信息，具体返回值类型由流程返回决定。具体提交流程请参考[表单 › 表单提交流程](#表单提交流程)，`validate` 逻辑见[表单 › 表单校验逻辑](#表单校验逻辑)。
^^^
### 表单提交流程
```mermaid
graph TD
A[Native submit event] --> B[Clone data object]
B --> C["beforeValidate(data)"]
C -- not set / resolved --> D["validate()"]
D --> E{isValid?}
E -- Y --> F["afterValidate(data)"]
F -- not set / reslved --> G["$emit('submit', data, event')"]
C -- rejected --> H["$emit('invalid', result)"]
D -- N --> H
F -- rejected --> H
```
:::warning
`beforeValidate` 和 `afterValidate` 以及 `sumbit` 事件操作的 `data` 均为 props `data` 的同一个副本。考虑到校验信息和 UI 中数据的一致性，`validate` 的目标数据是 props `data` 的源数据。因此在 `beforeValidate` 中**不建议**修改 `data` 副本。
:::
### 表单校验逻辑
表单校验内部分为 `Field` 的 `rule` 校验和 `validators` 的校验。
1. `Field` 的 `rule` 是单值、同步校验。详见[表单项](./field)。
2. `validators` 可以是多值、异步的校验。
+++validators 示例
```js
validators: [
{
fields: ['start', 'end'],
validate (start, end) {
if (start == null || end == null) {
return true
}
if (parseInt(start, 10) >= parseInt(end, 10)) {
return {
start: '下限必须小于上限'
}
}
return true
},
triggers: ['change', 'submit,input']
},
{
fields: ['phone'],
validate (phone) {
return new Promise(function (resolve) {
setTimeout(function () {
let res
if (phone === '18888888888') {
res = {
phone: '该手机已被注册'
}
}
return resolve(res)
}, 3000)
})
},
triggers: ['input']
}
]
```
+++
#### `Field` 的 `rule` 和 `validators` 的优先级
校验失败的信息会添加到对应的 `Field` 的 `validities` 信息中。由于同个操作触发的校验，`validators` 的校验结果优先级大于 `Field` 的 `rule`，不同操作触发的校验，展现最后一个结果。`Field` 的 `rule` 内部的优先级，参考[表单项 › 属性](./field#属性)。
#### 交互过程的校验
```mermaid
graph LR
A[Interaction events] -->B[Field#validate]
A --> C[validators.validate]
B --> D{isValid?}
C --> D
D -- Y --> E[Hide validities]
D -- N --> F[Show errors]
```
#### 提交过程的校验
```mermaid
graph LR
A[validate] -->B[Field#validate]
A --> C[validators.validate]
B --> D[Merge validities]
C --> D
D --> E{isValid?}
E -- Y --> F["Promise.resolve(true)"]
E -- N --> G["Promise.resolve(error)"]
```
提交时，其中一个过程的校验失败不会导致整个校验终止，校验信息将在两个过程执行完毕后进行整合，并传递到 [`invalid`](#事件) 事件中去。

26
one/docs/components/grid-column.md Normal file
View File

@ -0,0 +1,26 @@
# GridColumn <small>栅格栏</small>
:::tip
`GridColumn` 组件需要配合 [`GridContainer`](./grid-container) 及 [`GridRow`](./grid-row) 组件使用。
:::
## 示例
见 [`GridContainer` 示例](./grid-container#示例)。
## API
### 属性
| 名称 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `span` | `number` | - | 栅格栏横跨的列数，不传则默认占满整行。 |
| `offset` | `number=` | `0` | 偏移列数，将影响后续栅格栏的位置。 |
| `pull` | `number=` | `0` | 栅格栏向左偏移列数，不影响其它栅格栏的位置。不能与 `push` 同时使用。 |
| `push` | `number=` | `0` | 栅格栏向右偏移列数，不影响其它栅格栏的位置。不能与 `pull` 同时使用。 |
### 插槽
| 名称 | 描述 |
| -- | -- |
| `default` | 栅格栏内容。 |

48
one/docs/components/grid-container.md Normal file
View File

@ -0,0 +1,48 @@
# GridContainer <small>栅格容器</small>
:::tip
`GridContainer` 组件需要配合 [`GridRow`](./grid-row) 及 [`GridColumn`](./grid-column) 组件使用。
:::
## 示例
### 默认栅格
[[ demo src="/demo/grid/default.vue" browser="/demos/grid/default.vue" ]]
### 定宽栅格
[[ demo src="/demo/grid/fixed.vue" browser="/demos/grid/fixed.vue" ]]
## API
### 属性
| 名称 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `columns` | `number=` | `gridcontainer.columns` | 栅格列数。 |
| `margin` | `number=` | `gridcontainer.margin` | 栅格两侧边距 `px` 数值。 |
| `gutter` | `number=` | `gridcontainer.gutter` | 栅格列间距 `px` 数值。 |
| `width` | `number=` | - | 当需要创建定宽布局时，用来传入容器宽度 `px` 数值。 |
### 插槽
| 名称 | 描述 |
| -- | -- |
| `default` | 布局内容，直接子组件只能包含 [`GridRow`](./grid-row) 组件。 |
### 全局配置
| 配置项 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `gridcontainer.columns` | `number` | `12` | 栅格列数。 |
| `gridcontainer.gutter` | `number` | `30` | 栅格列间距 `px` 数值。 |
| `gridcontainer.margin` | `number` | `0` | 栅格两侧边距 `px` 数值。 |
#### `veui-theme-dls` 中的默认配置
| 配置项 | 类型 | 默认值 |
| -- | -- | -- | -- |
| `gridcontainer.columns` | `number` | `24` |
| `gridcontainer.gutter` | `number` | `20` |
| `gridcontainer.margin` | `number` | `20` |

17
one/docs/components/grid-row.md Normal file
View File

@ -0,0 +1,17 @@
# GridRow <small>栅格行</small>
:::tip
`GridRow` 组件需要配合 [`GridContainer`](./grid-container) 及 [`GridColumn`](./grid-column) 组件使用。
:::
## 示例
见 [`GridContainer` 示例](./grid-container#示例)。
## API
### 插槽
| 名称 | 描述 |
| -- | -- |
| `default` | 栅格行内容，直接子组件只能包含 [`GridColumn`](./grid-column) 组件。 |

33
one/docs/components/icon.md Normal file
View File

@ -0,0 +1,33 @@
# Icon <small>图标</small>
:::tip
VEUI 的 `Icon` 组件目前兼容 [Vue-Awesome](https://github.com/Justineo/vue-awesome) 的方式注册并通过字符串类型的 `name` 属性指定图标；也支持直接传入组件定义进行渲染。
:::
## 示例
[[ demo src="/demo/icon/default.vue"]]
## API
### 属性
| 名称 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `name` | `string` | - | 图标名称或其组件定义。 |
| `label` | `string` | - | 图标的文字说明，对辅助设备可见。当不设置时，图标对辅助设备隐藏。 |
| `scale` | `number` | - | 图标尺寸倍数。不设置时相当于 `1`。 |
| `spin` | `boolean` | `false` | 是否保持旋转状态。 |
| `pulse` | `boolean` | `false` | 是否保持步进旋转状态。 |
| `inverse` | `boolean` | `false` | 是否翻转颜色（用白色绘制，用于深色背景）。 |
| `flip` | `string` | - | 是否翻转，可选值为 `'horizontal'`/`'vertical'`，分别表示水平翻转与垂直翻转。 |
:::warning
当 `name` 属性使用组件定义时，仅支持 `spin` 属性。
:::
### 插槽
| 名称 | 描述 |
| -- | -- |
| `default` | 用来实现图标堆叠，当内部有 `Icon` 子组件时会层叠在一起居中显示，且外部 `Icon` 组件不需要设置 `name` 属性。 |

21
one/docs/components/input-group.md Normal file
View File

@ -0,0 +1,21 @@
# InputGroup <small>输入组件组</small>
:::tip
`Input` 组件需要内联 [`Input`](./input)、[`NumberInput`](./number-input)、[`Autocomplete`](autocomplete)、[`SearchBox`](./search-box)、[`Select`](./select)、[DatePicker](./date-picker)、[TimePicker](./time-picker)、[`Dropdown`](./dropdown)、[`Button`](./button)、[`ButtonGroup`](./button-group)、[`Label`](./label)、[`Span`](./span) 等组件配合使用。
:::
## 示例
### 任意组合
可选的尺寸 `ui` 属性值：`xs`/`s`/`m`/`l`。
[[ demo src="/demo/input-group/default.vue" ]]
## API
### 插槽
| 名称 | 描述 |
| -- | -- |
| `default` | 内容区，用来内联输入组件。 |

120
one/docs/components/input.md Normal file
View File

@ -0,0 +1,120 @@
# Input <small>输入</small>
## 示例
### 尺寸
可选的尺寸 `ui` 属性值：`xs`/`s`/`m`/`l`。
[[ demo src="/demo/input/size.vue" ]]
### 只读状态
设置 `readonly` 来使输入框处于只读状态。
[[ demo src="/demo/input/readonly.vue" ]]
### 禁用状态
设置 `disabled` 来使输入框处于禁用状态。
[[ demo src="/demo/input/disabled.vue" ]]
## API
### 属性
| 名称 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `ui` | `string=` | - | [^ui] |
| `value` | `string` | '' | [^value] |
| `disabled` | `boolean=` | `false` | 输入框是否为禁用状态。 |
| `readonly` | `boolean=` | `false` | 输入框是否为只读状态。 |
| `type` | `string=` | `'text'` | [^type] |
| `placeholder` | `string=` | - | 输入占位符。 |
| `clearable` | `boolean=` | `false` | 是否显示清除按钮。 |
| `composition` | `boolean=` | `false` | 是否感知输入法输入过程的值。 |
| `select-on-focus` | `boolean=` | `false` | 聚焦时是否自动选中输入框文本。 |
^^^ui
预设样式。
+++枚举值
| 值 | 描述 |
| -- | -- |
| `xs` | 超小尺寸样式。 |
| `s` | 小尺寸样式。 |
| `m` | 中尺寸样式。 |
| `l` | 大尺寸样式。 |
+++
^^^
^^^value
:::badges
`v-model`
:::
输入框的值。
^^^
^^^type
输入类型。参见原生 `<input>` 元素的 [`type`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/Input#attr-type)。
+++枚举值
| 值 | 描述 |
| -- | -- |
| `text` | 文本输入框。 |
| `password` | 密码输入框。 |
| `hidden` | 隐藏的输入框，但是值允许提交。 |
+++
^^^
### 插槽
| 名称 | 描述 |
| -- | -- |
| `before` | 输入框内前置内容。 |
| `after` | 输入框内后置内容。 |
| `placeholder` | 未输入时的占位内容。 |
:::warning
注意，插槽宽度会挤压输入框宽度。
:::
### 事件
| 名称 | 描述 |
| -- | -- |
| `change` | [^event-change] |
| `input` | [^event-input] |
^^^event-change
输入框内容变化时触发，即原生 `change` 事件触发时。回调参数为 `(value, event)`。
+++参数详情
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `value` | `string` | 输入框的值。 |
| `event` | [`Event`](https://developer.mozilla.org/zh-CN/docs/Web/Events/change) | 原生 `change` 事件对象。 |
+++
^^^
^^^event-input
:::badges
`v-model`
:::
有效输入时触发，受 `composition` 属性影响。回调参数为 `(value: string)`，`value` 为输入框的 `value` 值。
^^^
此外，`Input` 支持如下的原生事件：
`auxclick`、`click`、`contextmenu`、`dblclick`、`mousedown`、`mouseenter`、`mouseleave`、`mousemove`、`mouseover`、`mouseout`、`mouseup`、`select`、`wheel`、`keydown`、`keypress`、`keyup`、`focus`、`blur`、`focusin`、`focusout`。
回调函数的参数都为原生事件对象。
### 图标
| 名称 | 描述 |
| -- | -- |
| `remove` | 清除按钮。 |

36
one/docs/components/label.md Normal file
View File

@ -0,0 +1,36 @@
# Label <small>标签</small>
## 示例
### 激活输入组件
可以使用 `for` 属性指定被激活组件的 `ref`。点击标签区域可以触发
[[ demo src="/demo/label/default.vue" ]]
## API
### 属性
| 名称 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `for` | `string=` | - | [^for] |
^^^for
允许通过 [`ref`](https://cn.vuejs.org/v2/guide/components-edge-cases.html#%E8%AE%BF%E9%97%AE%E5%AD%90%E7%BB%84%E4%BB%B6%E5%AE%9E%E4%BE%8B%E6%88%96%E5%AD%90%E5%85%83%E7%B4%A0)、[Vue 组件实例](https://cn.vuejs.org/v2/guide/instance.html)、[`HTMLElement`](https://developer.mozilla.org/zh-CN/docs/Web/API/HTMLElement) 的方式指定目标组件或元素。如果指定的是组件，点击标签后会调用对应组件的 `activate` 方法（如果存在）；如果指定的是元素，点击标签后会调用对应元素的 [`click` 方法](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/click)。
+++类型详情
| 类型 | 描述 |
| -- | -- |
| `string` | 在当前浮层组件所在上下文中，通过匹配 `$refs` 中的键名查找 HTML 元素或对应组件实例的根元素。 |
| `Vue` | 如果传入的是组件实例，就直接返回该组件的根元素。 |
| `HTMLElement` | 如果已经是一个 HTML 元素了，就直接使用该元素。 |
+++
^^^
### 插槽
| 名称 | 描述 |
| -- | -- |
| `default` | 默认插槽。无默认内容。用于填充行内内容，**不允许**放入块级内容。 |

51
one/docs/components/link.md Normal file
View File

@ -0,0 +1,51 @@
# Link <small>链接</small>
## 示例
[[ demo src="/demo/link/default.vue"]]
## API
### 属性
| 名称 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `ui` | `string=` | - | [^ui] |
| `to` | `string|Object` | - | 链接路径。当配合 Vue Router 使用时，会透传到 [`<router-link>`](https://router.vuejs.org/api/#router-link) 的[同名属性](https://router.vuejs.org/api/#to)；否则只支持 `string` 类型，输出到 `<a>` 元素的 `href` 属性中。 |
| `rel` | `string` | - | HTML 原生的链接类型，可参考 [MDN 的相关介绍](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Link_types)。 |
| `target` | `string` | - | [^target] |
| `native` | `boolean` | `false` | 是否强制使用原生的 `<a>` 元素。 |
| `fallback` | `string` | `'span'` | 在 `to` 属性为空时使用的原生元素类型。 |
| `disabled` | `boolean=` | `false` | 是否为禁用状态。 |
^^^ui
预设样式。
+++枚举值
| 值 | 描述 |
| -- | -- |
| `strong` | 加强样式。 |
| `s` | 小尺寸样式。 |
| `m` | 中尺寸样式。 |
+++
^^^
^^^target
指定在何处显示链接的资源，可参考 [MDN 的相关介绍](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/a#attr-target)。
:::tip
当 `target` 为 `_blank` 时将自动增加 `noopener` 值（如果用户未指定该值）以增强默认情况下的安全性。
:::
^^^
### 插槽
| 名称 | 描述 |
| -- | -- |
| `default` | 链接内容。 |
### 事件
| 名称 | 描述 |
| -- | -- |
| `click` | 在 `to` 属性为空或指定了 `native` 为 `true` 的情况下，点击时触发。回调参数为 `(event)`，`event` 类型为原生 [`Event`](https://developer.mozilla.org/zh-CN/docs/Web/Events/click)。 |

56
one/docs/components/loading.md Normal file
View File

@ -0,0 +1,56 @@
# Loading <small>加载</small>
## 示例
### 风格
可选的风格 `ui` 属性值：`normal`/`strong`/`reverse`。
[[demo src="/demo/loading/style.vue"]]
### 尺寸
可选的尺寸 `ui` 属性值：`s`/`m`/`l`。
[[demo src="/demo/loading/size.vue"]]
### 排列方式
可选的排列方式 `ui` 属性值：`vertical`。
[[demo src="/demo/loading/layout.vue"]]
### 自定义加载图标
通过 `spinner` 插槽设置自定义加载图标。
[[demo src="/demo/loading/slot.vue"]]
## API
| 名称 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `ui` | `string=` | `normal` `m` | [^ui] |
| `loading` | `boolean` | `false` | 是否处于加载状态。 |
^^^ui
预设样式。为空格分隔的一组枚举值的组合。
+++枚举值
| 值 | 描述 |
| -- | -- |
| `strong` | 加强样式。 |
| `reverse` | 反白样式，用于深色背景。 |
| `vertical` | 垂直排列样式。|
| `s` | 小尺寸样式。 |
| `m` | 中尺寸样式。 |
| `l` | 大尺寸样式。 |
+++
^^^
### 插槽
| 名称 | 描述 |
| -- | -- |
| `spinner` | 加载图标。 |
| `default` | 加载中提示文字。 |

147
one/docs/components/menu.md Normal file
View File

@ -0,0 +1,147 @@
# Menu <small>边栏菜单</small>
## 示例
### 普通
结合 Vue Router 使用边栏菜单。
[[ demo src="/demo/menu/normal.vue" ]]
### 可折叠
使用 `collapsible` 属性控制菜单是否可以折叠。
[[ demo src="/demo/menu/collaspible.vue" ]]
### 自定义插槽
[[ demo src="/demo/menu/slot.vue" ]]
## API
### 属性
| 名称 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `ui` | `string=` | - | [^ui] |
| `items` | `Array<Object>=` | `[]` | [^items] |
| `active` | `string` | - | [^active] |
| `matches` | `function(Object, string): boolean` | - | [^matches] |
| `collapsible` | `boolean` | `false` | 整个导航菜单是否可折叠。 |
| `collapsed` | `boolean` | `false` | [^collapsed] |
| `expanded` | `Array<string>=` | `[]` | [^expanded] |
^^^ui
预设样式。
+++枚举值
| 值 | 描述 |
| -- | -- |
| `s` | 小尺寸样式。 |
| `m` | 中尺寸样式。 |
+++
^^^
^^^active
当前激活节点，若该节点定义了 `name` 则就是该 `name` 值，否则该值是由 `to` 生成的路由路径（[route.path](https://router.vuejs.org/api/#route-object-properties)）。
^^^
^^^items
数据源数组，每个节点类型为 `{label, to, name, icon, disabled, children, ...}`。
+++字段详情
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `label` | `string` | 节点的文字描述。 |
| `to` | `string|Object` | 节点的导航目的地。参考 [`Link`](./link) 组件的 [`to`](./link#props) 属性。 |
| `name` | `string` | 节点的唯一标识，`name` 和 `to` 二者至少有一个存在。 |
| `disabled` | `boolean=` | 节点是否被禁用。 |
| `icon` | `string|{render: function}` | 首层节点使用的图标。 |
| `children` | `Array<Object>=` | 节点的子节点数组，数组项类型同 `items` 数组项。 |
+++
^^^
^^^matches
当路由发生切换时，用来从 `items` 中找到激活的项目。
默认实现：项目路由路径和当前路由的路径相等 (===) 则认为该项目是激活的。
^^^
^^^collapsed
:::badges
`.sync`
:::
当前折叠状态。
^^^
^^^expanded
:::badges
`.sync`
:::
指定当前展开的节点，是一个对应于 `items` 中节点数据中 `name` 属性或路由路径的数组。
^^^
### 插槽
| 名称 | 描述 |
| -- | -- |
| `before` | 前置插槽。 |
| `item` | [^item] |
| `icon` | [^icon] |
| `item-label` | [^item-label] |
| `after` | 后置插槽。 |
^^^item
每个节点的渲染插槽。
默认内容：渲染了 `icon` 插槽和 `item-label` 插槽。
+++作用域参数
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `label` | `string` | 图标名称。 |
| `to` | `string|Object` | 节点的导航目的地。参考 [`Link`](./link) 组件的 [`to`](./link#props) 属性。 |
| `name` | `string` | 节点的唯一标识，`name` 和 `to` 二者至少有一个存在。 |
| `disabled` | `boolean=` | 节点是否被禁用。 |
| `icon` | `string` | 首层节点使用的图标。 |
| `children` | `Array<Object>=` | 节点的子节点数组，数组项类型同 `items` 数组项。 |
+++
^^^
^^^icon
节点前的图标插槽。
默认内容：渲染 `item.icon` 指定的图标。
+++作用域参数
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `icon` | `string|{render: function}` | 图标名称。 |
+++
^^^
^^^item-label
节点的 `label` 插槽。
默认内容：渲染节点对应的 `Link`。
作用域参数参考 `item` 插槽。
^^^
### 事件
| 名称 | 描述 |
| -- | -- |
| `activate` | 用户点击有 `to` 的节点触发，参数是激活节点的整个 `item` 数据。 |
| `click` | 用户点击节点时触发，参数是激活节点整个 `item` 数据。 |
### 图标
| 名称 | 描述 |
| -- | -- |
| `expand` | 展开。 |
| `collapse` | 折叠。 |

107
one/docs/components/number-input.md Normal file
View File

@ -0,0 +1,107 @@
# NumberInput <small>数字输入</small>
## 示例
### 尺寸
可选的尺寸 `ui` 属性值：`xs`/`s`/`m`。
[[ demo src="/demo/number-input/size.vue" ]]
### 只读状态
设置 `readonly` 来使数字输入框处于只读状态。
[[ demo src="/demo/number-input/readonly.vue" ]]
### 禁用状态
设置 `disabled` 来使数字输入框处于禁用状态。
[[ demo src="/demo/number-input/disabled.vue" ]]
## API
### 属性
| 名称 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `ui` | `string=` | - | [^ui] |
| `value` | `number` | - | [^value] |
| `readonly` | `boolean=` | `false` | 数字输入框是否为只读状态。 |
| `disabled` | `boolean=` | `false` | 数字输入框是否为禁用状态。 |
| `placeholder` | `string` | - | 输入占位符。 |
| `select-on-focus` | `boolean` | `false` | 聚焦时是否自动选中数字输入框文本。 |
| `max` | `number` | - | 允许的最大值。 |
| `min` | `number` | - | 允许的最小值。 |
| `decimalPlace` | `number` | 0 | 数值的小数精度位数，默认精确到整数位，`-1` 表示不处理精度。 |
^^^ui
预设样式。
+++枚举值
| 值 | 描述 |
| -- | -- |
| `xs` | 超小尺寸样式。 |
| `s` | 小尺寸样式。 |
| `m` | 中尺寸样式。 |
+++
^^^
^^^value
:::badges
`v-model`
:::
数字输入框的值。
^^^
### 插槽
| 名称 | 描述 |
| -- | -- |
| `before` | 数字输入框前置内容。 |
| `after` | 数字输入框后置内容。位于增减按钮之后。 |
:::warning
注意，插槽宽度会挤压输入框宽度。
:::
### 事件
| 名称 | 描述 |
| -- | -- |
| `change` | [^event-change] |
| `input` | [^event-input] |
^^^event-change
原生 `change` 事件，回调参数为 `(value, event)`。
+++参数详情
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `value` | `number` | 数字输入框的值。 |
| `event` | `Event` | 原生事件对象。 |
+++
^^^
^^^event-input
:::badges
`v-model`
:::
有效输入时触发，受数字格式化影响，若当前值格式化为无效值，则不触发。回调参数为 `(value: string)`，`value` 为数字输入框的 `value` 值。
^^^
此外，`NumberInput` 支持如下的原生事件：
`auxclick`、`click`、`contextmenu`、`dblclick`、`mousedown`、`mouseenter`、`mouseleave`、`mousemove`、`mouseover`、`mouseout`、`mouseup`、`select`、`wheel`、`keydown`、`keypress`、`keyup`、`focus`、`blur`、`focusin`、`focusout`。
回调函数的参数都为原生事件对象。
### 图标
| 名称 | 描述 |
| -- | -- |
| `increase` | 增加按钮。 |
| `decrease` | 减少按钮。 |

121
one/docs/components/option-group.md Normal file
View File

@ -0,0 +1,121 @@
# OptionGroup <small>选择组</small>
:::tip
`OptionGroup` 组件需要在 [`Select`](./select)、[`Dropdown`](./dropdown) 或其它 `OptionGroup` 组件内使用，可以配合 [`Option`](./option) 组件使用。
:::
## 示例
见 [`Select` 示例](./select#示例)或 [`Dropdown` 示例](./dropdown#示例)。
## API
### 属性
| 名称 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `label` | `string` | - | 选项组的标题。 |
| `options` | `Array<Object>` | `[]` | [^options] |
| `position` | `string` | `inline` | [^position] |
| `overlay-class` | `string|Array|Object=` | - | 参考 [Overlay](./overlay) 组件的 `overlay-class` 属性。 |
^^^options
选项列表，项目的类型为 `{label, value, disabled, ...}`。
+++字段详情
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `label` | `string` | 选项的文字说明。 |
| `value` | `*` | 选项对应的值。 |
| `disabled` | `boolean=` | 选项是否为禁用。 |
+++
^^^
^^^position
内部选项显示的方式。
+++枚举值
| 值 | 描述 |
| -- | -- |
| `inline` | 内联方式直接显示。 |
| `popup` | 在浮层中显示。 |
+++
^^^
### 插槽
| 名称 | 描述 |
| -- | -- |
| `default` | 选项列表的内容。在没有指定 `options` 属性时，可以用来直接内联 `Option` 或其它 `OptionGroup` 组件。 |
| `label` | [^scoped-slot-label] |
| `group-label` | [^scoped-slot-group-label] |
| `option-label` | [^scoped-slot-option-label] |
| `option` | [^scoped-slot-option] |
^^^scoped-slot-label
选项组标题文本区域。
默认内容：`label` 属性对应的文本。
+++作用域参数
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `label` | `string` | 选项组标题文本。 |
| `disabled` | `boolean=` | 选项组是否禁用。 |
+++
^^^
^^^scoped-slot-group-label
子选项组的标题文本区域。
默认内容：带 `options` 的选项对应的 `label` 属性值。
+++作用域参数
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `label` | `string` | 选项组文本。 |
| `disabled` | `boolean=` | 选项组是否禁用。 |
+++
另外，当前选项组数据中除了上面描述的字段之外的其它字段也会自动通过 `v-bind` 进行绑定到作用域参数上。
^^^
^^^scoped-slot-option-label
选项的文本区域。
默认内容：不带 `options` 的选项对应的 `label` 属性值。
+++作用域参数
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `label` | `string` | 选项文本。 |
| `value` | `string` | 选项值。 |
| `selected` | `boolean` | 是否已选择。 |
| `disabled` | `boolean=` | 选项是否禁用。 |
+++
另外，当前选项数据中除了上面描述的字段之外的其它字段也会自动通过 `v-bind` 进行绑定到作用域参数上。
^^^
^^^scoped-slot-option
可供选择的选项的整个区域。
默认内容：`Option` 内的组件默认结构。
+++作用域参数
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `label` | `string` | 选项文本。 |
| `value` | `string` | 选项值。 |
| `selected` | `boolean` | 是否已选择。 |
| `disabled` | `boolean=` | 选项是否禁用。 |
+++
另外，当前选项数据中除了上面描述的字段之外的其它字段也会自动通过 `v-bind` 进行绑定到作用域参数上。
^^^
### 图标
| 名称 | 描述 |
| -- | -- |
| `expandable` | 可展开的项目。 |

37
one/docs/components/option.md Normal file
View File

@ -0,0 +1,37 @@
# Option <small>选项</small>
:::tip
`Option` 组件需要配合 [`Select`](./select) 或 [`Dropdown`](./dropdown) 或 [`OptionGroup`](./option) 组件使用。
:::
## 示例
见 [`Select` 示例](./select#示例)或 [`Dropdown` 示例](./dropdown#示例)。
## API
### 属性
| 名称 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `label` | `string` | - | 选项的文本。 |
| `value` | `*` | - | 选项对应的值。 |
| `disabled` | `boolean=` | `false` | 是否为禁用状态。 |
| `hidden` | `boolean=` | `false` | 是否为隐藏状态。 |
### 插槽
| 名称 | 描述 |
| -- | -- |
| `default` | 选项的整个区域。默认显示文本及勾选图标等。 |
| `label` | 选项的文本区域。默认显示 `label` 属性内容。 |
### 事件
在选项被点击时触发 `click` 事件，没有参数。
### 图标
| 名称 | 描述 |
| -- | -- |
| `checked` | 已选状态。 |

102
one/docs/components/overlay.md Normal file
View File

@ -0,0 +1,102 @@
# Overlay <small>浮层</small>
## 示例
### 自定义定位
浮层可以在页面内按照自定义方式定位。
[[ demo src="/demo/overlay/position.vue" ]]
### 相对已有元素定位
浮层可以相对于页面内某个 DOM 元素定位。
[[ demo src="/demo/overlay/relative-base.vue" ]]
### 层叠顺序管理
同层级且相同优先级的浮层，越晚显示的层叠顺序越高。
[[ demo src="/demo/overlay/stack-display-order.vue" ]]
打开的浮层，会建立新的层叠上下文，从中打开的浮层层叠顺序会高于父级浮层。
[[ demo src="/demo/overlay/stack-on-overlay.vue" ]]
子浮层的层叠顺序受父浮层影响。
[[ demo src="/demo/overlay/stack-display-order-with-on-overlay.vue" ]]
## API
### 属性
| 名称 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `ui` | `string=` | - | 预设样式。`veui-theme-dls` 未提供，可自定义。 |
| `open` | `boolean` | `false` | [^open] |
| `target` | `string|Vue|Element` | - | [^target] |
| `priority` | `number` | - | [^priority] |
| `autofocus` | `boolean` | - | 是否自动抢占焦点到浮层内的第一个可聚焦元素。 |
| `modal` | `boolean` | `false` | 是否是模态浮层。模态浮层会抢占焦点且限制键盘导航处于浮层内部（关闭后焦点会回归）。 |
| `inline` | `boolean` | `false` | 是否将浮层渲染为内联内容。 |
| `local` | `boolean` | `false` | 是否将浮层保留在原来的 DOM 位置，而非移动到全局位置并参与[全局浮层管理](../advanced/overlay)。 |
| `overlay-class` | `string|Array|Object=` | - | [^overlay-class] |
| `options` | `Object` | 透传给底层 Popper.js 实现的 `modifiers` 配置项，具体内容参见[这里](https://popper.js.org/docs/v1/#modifiers)。 |
^^^open
:::badges
`.sync`
:::
是否显示浮层。
^^^
^^^target
允许通过 [`ref`](https://cn.vuejs.org/v2/guide/components-edge-cases.html#%E8%AE%BF%E9%97%AE%E5%AD%90%E7%BB%84%E4%BB%B6%E5%AE%9E%E4%BE%8B%E6%88%96%E5%AD%90%E5%85%83%E7%B4%A0)、[Vue 组件实例](https://cn.vuejs.org/v2/guide/instance.html)、[`Element`](https://developer.mozilla.org/zh-CN/docs/Web/API/Element) 的方式指定目标元素。如果目标元素存在，浮层会相对于该元素进行定位，具体定位参数由 `options` 属性指定。
+++类型详情
| 类型 | 描述 |
| -- | -- |
| `string` | 在当前浮层组件所在上下文中，通过匹配 `$refs` 中的键名查找 DOM 元素或对应组件实例的根元素。 |
| `Vue` | 如果传入的是组件实例，就直接返回该组件的根元素。 |
| `Element` | 如果已经是一个 DOM 元素了，就直接使用该元素。 |
+++
^^^
^^^priority
当前浮层组件实例与其它实例在层叠关系上的权重，数值越大，越靠上。
:::tip
由于所有浮层组件的浮层根元素都会放置到 `<body>` 元素下，所以为了更好地控制浮层层叠顺序，浮层模块内部实现了全局的层叠上下文。组件的父子关系决定了浮层的嵌套关系，在同层级内的每个浮层组件实例都可以通过指定 `priority` 来实现不同实例间的相对层叠顺序。相同 `priority` 数值的组件实例，按照实例化的先后顺序来决定层叠顺序，后实例化的组件在之前组件的上面。
:::
^^^
^^^overlay-class
浮层根元素类名，数据格式为所有 [Vue 支持的 `class` 表达式](https://cn.vuejs.org/v2/guide/class-and-style.html#%E7%BB%91%E5%AE%9A-HTML-Class)。
:::tip
由于浮层根元素会放置在 `<body>` 元素下，可以通过这个属性给浮层根元素设置类名以自定义样式。
:::
^^^
### 插槽
| 名称 | 描述 |
| -- | -- |
| `default` | 浮层内容。 |
### 事件
| 名称 | 描述 |
| -- | -- |
| `locate` | 浮层定位发生变化时触发。 |
| `afteropen` | 浮层打开后触发。如果样式主题提供了退出动画，将在退出动画完毕后触发。 |
| `afterclose` | 浮层关闭后触发。如果样式主题提供了退出动画，将在退出动画完毕后触发。 |
### 全局配置
| 配置项 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `overlay.overlayClass` | `string|Array|Object=` | `[]` | 全局配置需要添加到浮层容器上的类名，数据格式为所有 [Vue 支持的 `class` 表达式](https://cn.vuejs.org/v2/guide/class-and-style.html#%E7%BB%91%E5%AE%9A-HTML-Class)。 |

67
one/docs/components/pagination.md Normal file
View File

@ -0,0 +1,67 @@
# Pagination <small>翻页</small>
## 示例
### 尺寸
[[ demo src="/demo/pagination/size.vue" ]]
### 跳转到指定页
使用 `goto` 属性开启跳转到指定页的功能。
[[ demo src="/demo/pagination/goto.vue" ]]
## API
### 属性
| 名称 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `ui` | `string=` | - | [^ui] |
| `page` | `number` | `1` | 当前页码（从 `1` 开始）。 |
| `total` | `number` | - | 总页数。 |
| `to` | `string|Object` | `''` | [^to] |
| `native` | `boolean` | `false` | 原生链接跳转。 |
| `page-size` | `number` | `pagination.pageSize` | [^page-size] |
| `page-sizes` | `Array` | `pagination.pageSizes` | 每页个数候选项。 |
| `goto` | `boolean` | `false` | 是否显示直接跳转到页码。 |
^^^ui
预设样式。
+++枚举值
| 值 | 描述 |
| -- | -- |
| `xs` | 超小尺寸样式。 |
| `s` | 小尺寸样式。 |
| `m` | 中尺寸样式。 |
+++
^^^
^^^to
目标链接模板。类型见 [`Link`](./link#属性) 组件的同名属性。其中，类型为 `string` 路径时其中的 `:page` 关键词会被替换为实际页码。类型为 `Object` 时，会将起转换为 `string` 后替换掉 `:page` 部分。
^^^
^^^page-size
:::badges
`.sync`
:::
每页个数。
^^^
### 事件
| 名称 | 描述 |
| -- | -- |
| `pagesizechange` | `page-size` 改变时触发，回调参数为 `(size: number)`。`size` 为新的 `page-size` 值。 |
| `redirect` | 链接跳转时触发，回调参数为 `(page: number, event: Object)`。`page` 为要跳转的目标页码。`event` 为原生的事件对象，在 `native` 为 `true` 时，调用 `event.preventDefault` 可阻止跳转。 |
### 全局配置
| 配置项 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `pagination.pageSize` | `number` | `30` | 每页个数。 |
| `pagination.pageSizes` | `Array<number>` | `[30, 50, 100]` | 每页个数候选项。 |

70
one/docs/components/popover.md Normal file
View File

@ -0,0 +1,70 @@
# Popover <small>气泡提示</small>
## 示例
### 风格
可选的 `ui` 属性值：`s`/`m`。
[[ demo src="/demo/popover/ui.vue" ]]
### 定位
使用 `position` 属性来指定气泡显示的位置。
[[ demo src="/demo/popover/position.vue" ]]
### 触发时机
使用 `trigger` 属性来指定显示/隐藏气泡的时机。
[[ demo src="/demo/popover/trigger.vue" ]]
## API
### 属性
| 名称 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `ui` | `string=` | - | [^ui] |
| `open` | `boolean` | `false` | [^open] |
| `target` | `string|Vue|Node` | - | 参考 [`Overlay`](./overlay) 组件的 `target` 属性。 |
| `position` | `string` | `'top'` | [^position] |
| `trigger` | `string` | `'hover'` | [^trigger] |
| `hide-delay` | `number` | `tooltip.hideDelays` | 触发关闭条件满足后延迟关闭等待时间的毫秒数。可以用来防止光标移出 `target` 后移入气泡进行交互前已经自动关闭。 |
| `overlay-class` | `string|Array|Object=` | - | 参考 [`Overlay`](./overlay) 组件的 [`overlay-class` 属性](./overlay#属性)。 |
^^^ui
预设样式。
+++枚举值
| 值 | 描述 |
| -- | -- |
| `s` | 小尺寸样式。 |
| `m` | 中尺寸样式。 |
+++
^^^
^^^open
:::badges
`.sync`
:::
是否显示气泡提示。
^^^
^^^position
指定定位参数。使用 [Popper.js](https://popper.js.org/) 风格的定位语法指定，可参考 [`Popper.placements`](https://popper.js.org/popper-documentation.html#Popper.placements)。
^^^
^^^trigger
触发气泡提示的方式。支持指定的值为 `v-outside` 指令绑定值的 `trigger` 参数，并支持使用 <code>&#0096;${open}-${close}&#0096;</code> 语法分别指定触发打开/关闭提示的时机。另外，当 `trigger` 指定为 `custom` 时，将不会使用 `v-outside` 功能自动进行处理。
例如：`click` 表示点击 `target` 后打开，在空白处点击时关闭；`hover-mousedown` 表示光标移入 `target` 后打开，在空白处按下鼠标时关闭。
^^^
### 插槽
| 名称 | 描述 |
| -- | -- |
| `default` | 气泡提示内容。 |

60
one/docs/components/progress.md Normal file
View File

@ -0,0 +1,60 @@
# Progress <small>进度条</small>
## 示例
[[ demo src="/demo/progress/default.vue" ]]
## API
### 属性
| 名称 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `ui` | `string=` | - | [^ui] |
| `type` | `string` | `'bar'` | 进度条类型。可选值为 `bar`/`circular`，分别是柱状和环形。 |
| `desc` | `boolean` | `false` | 是否显示文字提示。 |
| `value` | `number` | `0` | 进度值。 |
| `min` | `number` | `0` | 最小值。 |
| `max` | `number` | `1` | 最大值。 |
| `decimal-place` | `number` | `0` | 保留的小数位数。 |
| `status` | `string` | - | [^status] |
| `autosucceed` | `boolean|number` | - | 是否在进度值到达最大时自动进入 `success` 状态。`true` 表示直接进入成功状态，如果是 `number` 类型则表示在到达最大值后切换为成功状态前等待的毫秒数。 |
^^^ui
预设样式。
+++枚举值
| 值 | 描述 |
| -- | -- |
| `fluid` | 柱状进度条自适应宽度样式。 |
| `s` | 小尺寸样式。 |
| `m` | 中尺寸样式。 |
^^^
^^^status
:::badges
`.sync`
:::
进度状态。可选值为 `success`/`alert`，分别表示成功及危险警告状态。
^^^
### 插槽
| 名称 | 描述 |
| -- | -- |
| `default` | [^scoped-slot-default] |
^^^scoped-slot-default
可用来定制文字提示区域的内容。
默认内容：完成率百分比。
+++作用域参数
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `percent` | `number` | 进度完成百分比。 |
| `value` | `number` | 进度值，同 `value` 属性。 |
| `status` | `string` | 进度状态，同 `status` 属性。 |
+++
^^^

60
one/docs/components/prompt-box.md Normal file
View File

@ -0,0 +1,60 @@
# PromptBox <small>输入弹框</small>
## 示例
获取用户输入的值。
[[ demo src="/demo/prompt-box/base.vue" ]]
## API
### 属性
| 名称 | 类型 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `open` | `boolean` | `false` | [^open] |
| `title` | `string` | - | 标题。 |
| `content` | `string` | `'请输入'` | 输入框上方的说明内容。 |
| `value` | `string` | `''` | [^value] |
| `overlay-class` | `string|Array|Object=` | - | 参考 [Overlay](./overlay) 组件的 `overlay-class` 属性。 |
^^^open
:::badges
`.sync`
:::
是否显示输入弹框。
^^^
^^^value
:::badges
`v-model`
:::
输入框值。
^^^
### 插槽
| 名称 | 描述 |
| -- | -- |
| `default` | 内容区。 |
| `title` | 标题区。若同时指定了 `title` 属性和 `title` 插槽，以后者为准。 |
| `foot` | 底部区域，默认会展示“确定”、“取消”按钮。 |
### 事件
| 名称 | 描述 |
| -- | -- |
| `input` | [^event-input] |
| `ok` | 点击“确定”按钮时触发。 |
| `cancel` | 点击“取消”按钮时触发。 |
| `afterclose` | 浮层关闭后触发。如果样式主题提供了退出动画，将在退出动画完毕后触发。 |
^^^event-input
:::badges
`v-model`
:::
输入框值发生变化后触发。回调参数为 `(value: string)`，`value` 为输入框当前值。
^^^

88
one/docs/components/radio-button-group.md Normal file
View File

@ -0,0 +1,88 @@
# RadioButtonGroup <small>单选按钮组</small>
## 示例
### 尺寸
可选的 `ui` 属性值：`s`/`m`。
[[ demo src="/demo/radio-button-group/default.vue" ]]
## API
### 属性
| 名称 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `ui` | `string=` | - | [^ui] |
| `items` | `Array<Object>` | `[]` | [^items] |
| `value` | `*` | - | [^value] |
| `disabled` | `boolean=` | `false` | 是否为禁用状态。 |
| `readonly` | `boolean=` | `false` | 是否为只读状态。 |
^^^ui
预设样式。
+++枚举值
| 值 | 描述 |
| -- | -- |
| `s` | 小尺寸样式。 |
| `m` | 中尺寸样式。 |
^^^
^^^items
单选按钮组数据源，项目类型为 `{label, value, disabled, ...}`。
+++字段详情
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `label` | `string` | 选项的文字说明。 |
| `value` | `*` | 选项对应的值。 |
| `disabled` | `boolean=` | 选项是否为禁用。 |
+++
^^^
^^^value
:::badges
`v-model`
:::
`items` 中已选项的 `value` 列表。
^^^
### 插槽
| 名称 | 描述 |
| -- | -- |
| `item` | [^scoped-slot-item] |
^^^scoped-slot-item
按钮内文本区域。
默认内容：`label` 属性值。
+++作用域参数
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `label` | `string` | 选项文本。 |
| `value` | `string` | 选项值。 |
| `index` | `number` | 选项在 `items` 中的序号。 |
| `disabled` | `boolean=` | 选项是否禁用。 |
+++
另外，`items` 内数据项中除了上面描述的字段之外的其它字段也会自动通过 `v-bind` 进行绑定到作用域参数上。
^^^
### 事件
| 名称 | 描述 |
| -- | -- |
| `change` | [^event-change] |
^^^event-change
:::badges
`v-model`
:::
选中状态变化后触发，回调参数为 `(value: *)`。`value` 为当前按钮组已选项内 `value` 字段的值。
^^^

88
one/docs/components/radio-group.md Normal file
View File

@ -0,0 +1,88 @@
# RadioGroup <small>单选框组</small>
## 示例
### 尺寸
可选的 `ui` 属性值：`s`/`m`。
[[ demo src="/demo/radio-group/default.vue" ]]
## API
### 属性
| 名称 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `ui` | `string=` | - | [^ui] |
| `items` | `Array<Object>` | `[]` | [^items] |
| `value` | `*` | - | [^value] |
| `disabled` | `boolean=` | `false` | 是否为禁用状态。 |
| `readonly` | `boolean=` | `false` | 是否为只读状态。 |
^^^ui
预设样式。
+++枚举值
| 值 | 描述 |
| -- | -- |
| `s` | 小尺寸样式。 |
| `m` | 中尺寸样式。 |
^^^
^^^items
单选框组数据源，项目类型为 `{label, value, disabled, ...}`。
+++字段详情
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `label` | `string` | 选项的文字说明。 |
| `value` | `*` | 选项对应的值。 |
| `disabled` | `boolean=` | 选项是否为禁用。 |
+++
^^^
^^^value
:::badges
`v-model`
:::
`items` 中已选项的 `value`。
^^^
### 插槽
| 名称 | 描述 |
| -- | -- |
| `item` | [^scoped-slot-item] |
^^^scoped-slot-item
选项描述文本区域。
默认内容：`label` 属性值。
+++作用域参数
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `label` | `string` | 选项文本。 |
| `value` | `*` | 选项值。 |
| `index` | `number` | 选项在 `items` 中的序号。 |
| `disabled` | `boolean=` | 选项是否禁用。 |
+++
另外，`items` 内数据项中除了上面描述的字段之外的其它字段也会自动通过 `v-bind` 进行绑定到作用域参数上。
^^^
### 事件
| 名称 | 描述 |
| -- | -- |
| `change` | [^event-change] |
^^^event-change
:::badges
`v-model`
:::
选中状态变化后触发，回调参数为 `(value: *)`。`value` 为当前按钮组已选项内 `value` 字段的值。
^^^

73
one/docs/components/radio.md Normal file
View File

@ -0,0 +1,73 @@
# Radio <small>单选框</small>
## 示例
### 尺寸
可选的 `ui` 属性值：`s`/`m`。
[[ demo src="/demo/radio/size.vue" ]]
### 值设定
可以通过设置 `value` 来修改选中状态下 `model` 属性（`v-model`）的值。
[[ demo src="/demo/radio/model.vue" ]]
## API
### 属性
| 名称 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `ui` | `string=` | - | [^ui] |
| `checked` | `boolean` | `false` | [^checked] |
| `value` | `*` | `true` | 选中状态对应的值。 |
| `disabled` | `boolean=` | `false` | 是否为禁用状态。 |
| `readonly` | `boolean=` | `false` | 是否为只读状态。 |
^^^ui
预设样式。
+++枚举值
| 值 | 描述 |
| -- | -- |
| `s` | 小尺寸样式。 |
| `m` | 中尺寸样式。 |
+++
^^^
^^^checked
:::badges
`.sync`
:::
是否处于选中状态。
^^^
### 插槽
| 名称 | 描述 |
| -- | -- |
| `default` | 单选框的描述文本，点击时会进行选中。无默认内容。 |
### 事件
| 名称 | 描述 |
| -- | -- |
| `change` | 用户切换选中状态时触发，回调参数为 `(checked: boolean)`。`checked` 表示当前是否选中。 |
| `input` | [^event-input] |
^^^event-input
:::badges
`v-model`
:::
选中状态变化后触发，回调参数为 `(val: *)`。`val` 为当前 `v-model` 的值。与 `change` 事件不同，`input` 事件在数据操作导致状态变化时也会触发。
^^^
此外，`Radio` 支持如下的原生事件：
`auxclick`、`click`、`contextmenu`、`dblclick`、`mousedown`、`mouseenter`、`mouseleave`、`mousemove`、`mouseover`、`mouseout`、`mouseup`、`select`、`wheel`、`keydown`、`keypress`、`keyup`、`focus`、`blur`、`focusin`、`focusout`。
回调参数均为相应的原生事件对象。

81
one/docs/components/region-picker.md Normal file
View File

@ -0,0 +1,81 @@
# RegionPicker <small>地域选择</small>
## 示例
[[ demo src="/demo/region-picker/default.vue" ]]
## API
### 属性
| 名称 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `datasource` | `Array<Object>` | `[]` | [^datasource] |
| `selected` | `Array<string>` | - | [^selected] |
| `include-indeterminate` | `boolean` | `false` | 是否将半选状态的节点加入已选项。`datasource` 节点中的非叶子节点若有部分子孙节点被选中，则为半选状态。 |
| `disabled` | `boolean=` | `false` | 是否为禁用状态。 |
| `readonly` | `boolean=` | `false` | 是否为只读状态。 |
^^^datasource
数据源，项目类型为 `{label, value, disabled, children, ...}`。
+++字段详情
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `label` | `string` | 节点的文字说明。 |
| `value` | `string=` | 节点对应的值。 |
| `disabled` | `boolean=` | 节点是否为禁用。 |
| `children` | `Array<Object>=` | 子节点列表，列表项类型与本节点相同。 |
+++
^^^
^^^selected
:::badges
`v-model`
:::
已选项 `value` 的数组。
^^^
### 插槽
| 名称 | 描述 |
| -- | -- |
| `label` | [^scoped-slot-label] |
^^^scoped-slot-label
每个节点文本描述的内容。
默认内容：每个节点 `label` 字段对应的文本内容。
+++作用域参数
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `label` | `string` | 节点的文字说明。 |
| `value` | `string` | 节点对应的值。 |
| `disabled` | `boolean=` | 节点是否为禁用。 |
| `children` | `Array<Object>=` | 子节点列表，列表项类型与本节点相同。 |
| `level` | `number` | 节点所在的层级。顶层节点层级为 `0`。 |
| `overlay` | `boolean=` | 是否在浮层中。 |
+++
另外，`datasource` 内节点中除了上面描述的字段之外的其它字段也会自动通过 `v-bind` 进行绑定到作用域参数上。
:::tip
`level` 为 `2` 且 `overlay` 为 `true` 时为在浮层中展现的三级标题，默认内容会附带被选中的子节点个数及子节点总数信息。
:::
^^^
### 事件
| 名称 | 描述 |
| -- | -- |
| `select` | [^event-select] |
^^^event-select
:::badges
`v-model`
:::
选中状态变化后触发，回调参数为 `(value: Array)`。`value` 类型与 `selected` 属性相同。
^^^

154
one/docs/components/schedule.md Normal file
View File

@ -0,0 +1,154 @@
# Schedule <small>时段选择</small>
## 示例
[[ demo src="/demo/schedule/default.vue" ]]
## API
### 属性
| 名称 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `selected` | `Object` | - | [^selected] |
| `hour-class` | `string|Array|Object|function` | `{}` | 特定小时的自定义 HTML `class`。传非函数时，数据格式为所有 [Vue 支持的 `class` 表达式](https://cn.vuejs.org/v2/guide/class-and-style.html#%E7%BB%91%E5%AE%9A-HTML-Class)；传函数时，签名为 `function(day: number, hour: number): string|Array<string>|Object<string, boolean>`，返回值格式亦为所有 Vue 支持的 `class` 表达式。 |
| `disabled-date` | `function(number, number): boolean` | `() => false` | 特定小时是否禁用。参数类型为 `(day: number, hour: number)`，分别表示一周的第几天（`0` 表示周日）及对应的小时数。 |
| `shortcuts` | `Array` | `schedule.shortcuts` | [^shortcuts] |
| `shortcuts-display` | `string` | `'inline'` | 快捷选择项的显示方式，支持 `inline`/`popup`，分别对应内联按钮组与下拉选择。 |
| `statuses` | `Array<{label: string, value: string}>` | `schedule.statuses` | 图例数据源。会为图例项目添加 `class` 值 <code>&#0096;veui-schedule-legend-${value}&#0096;</code>，`label` 则会显示为图例文本。 |
| `disabled` | `boolean=` | `false` | 是否为禁用状态。 |
| `readonly` | `boolean=` | `false` | 是否为只读状态。 |
^^^selected
:::badges
`v-model`
:::
已选时段。类型为 `Object<number, Array>`。
键为一周的第几天，`0` 表示周日，与 [`Date.prototype.getDay()`](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Date/getDay) 返回值相同。值为每天被选取的时段，每个时段格式为 `[start: number, end: number]`，`start` 与 `end` 均为 `0`–`23` 的小时数。
+++数据样例
```json
{
1: [
[9, 17]
],
6: [
[0, 2],
[18, 20]
]
}
```
本例表示周一的 9:00–18:00 与周六的 0:00–3:00 和 18:00–21:00。结束时间表示的是时段最后一小时的开始时间。
+++
^^^
^^^shortcuts
快捷选择选项列表。类型为 `{label: string, selected: boolean|Array}`。
`label` 为显示的提示文字。`selected` 表示预选择的时段，类型为数组时，格式与 `selected` 属性相同；值为 `true` 时等同于 `[[0, 23]]`。
^^^
### 插槽
| 名称 | 描述 |
| -- | -- |
| `header` | 顶部区域。 |
| `header-content` | 顶部区域的内容，不包括外层容器。 |
| `shortcuts` | 顶部快捷选项区域。 |
| `legend` | 顶部图例区域。 |
| `legend-label` | [^scoped-slot-legend-label] |
| `hour` | [^scoped-slot-hour] |
| `label` | [^scoped-slot-label] |
| `tooltip` | [^scoped-slot-tooltip] |
^^^scoped-slot-legend-label
每个图例的文本区域。
默认内容：每个图例状态 `label` 字段对应的文本内容。
+++作用域参数
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `label` | `string` | 图例状态的文字说明。 |
| `value` | `string` | 图例状态对应的值。 |
+++
另外，`status` 内对应图例状态对象中除了上面描述的字段之外的其它字段也会自动通过 `v-bind` 进行绑定到作用域参数上。
^^^
^^^scoped-slot-hour
每小时区域的内容。
默认内容：无。
+++作用域参数
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `day` | `number` | 一周的第几天，`0` 表示周日。 |
| `hour` | `number` | 小时序号。 |
+++
^^^
^^^scoped-slot-label
已选时间段的区域。
默认内容：时段在 3 小时及以上时，显示时段范围 <code>&#0096;${from}:00–${to + 1}:00&#0096;</code>；选择全天的显示为“全天”；小于 3 小时无内容。
+++作用域参数
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `from` | `number` | 时段开始的小时。 |
| `to` | `number` | 时段结束的小时。 |
+++
^^^
^^^scoped-slot-tooltip
光标移入每个小时格子的悬浮提示内容。
默认内容：当前小时格子的时间范围 <code>&#0096;${hour}:00–${hour + 1}:00&#0096;</code>。
+++作用域参数
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `day` | `number` | 一周的第几天，`0` 表示周日。 |
| `hour` | `number` | 小时序号。 |
+++
^^^
### 事件
| 名称 | 描述 |
| -- | -- |
| `select` | [^event-select] |
^^^event-select
:::badges
`v-model`
:::
选中状态变化后触发，回调参数为 `(value: Object)`。`value` 类型与 `selected` 属性相同。
^^^
### 全局配置
| 配置项 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `schedule.statuses` | Array<{name, label}> | 见描述。 | [^config-statuses] |
^^^config-statuses
默认图例状态数组。数组项类型为 `{name: string, label: string}`，默认值为：
```js
[
{ name: 'selected', label: '@@schedule.selectedRanges' },
{ name: 'available', label: '@@schedule.availableRanges' }
]
```
:::tip
`@@` 开头的值表示引用多语言配置中的相应字段。
:::
^^^

176
one/docs/components/search-box.md Normal file
View File

@ -0,0 +1,176 @@
# SearchBox <small>搜索框</small>
## 示例
### 风格
可选的 `ui` 属性值：`strong`。
[[ demo src="/demo/search-box/style.vue" ]]
### 尺寸
可选的 `ui` 属性值：`xs`/`s`/`m`/`l`。
[[ demo src="/demo/search-box/size.vue" ]]
### 只读与禁用
[[ demo src="/demo/search-box/disabled.vue" ]]
### 推荐列表
[[ demo src="/demo/search-box/suggestion.vue" ]]
## API
### 属性
| 名称 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| `ui` | `string=` | - | [^ui] |
| `placeholder` | `string` | - | 搜索框占位符。 |
| `value` | `string` | - | [^value] |
| `autofocus` | `boolean` | `false` | 是否自动聚焦。 |
| `clearable` | `boolean` | `false` | 是否显示清除按钮。 |
| `select-on-focus` | `boolean` | `false` | 聚焦时是否自动选择文本。 |
| `composition` | `boolean` | `false` | 是否感知输入法状态。 |
| `suggestions` | `Array<string>|Array<Object>` | - | [^suggestions] |
| `replace-on-select` | `boolean` | `true` | 选择推荐项时是否自动使用其内容填充文本框。 |
| `suggest-trigger` | `Array<string>|string` | `input` | [^suggest-trigger] |
| `disabled` | `boolean=` | `false` | 是否为禁用状态。 |
| `readonly` | `boolean=` | `false` | 是否为只读状态。 |
^^^ui
按钮预设样式。
+++枚举值
| 值 | 描述 |
| -- | -- |
| `strong` | 加强样式，搜索图标变成搜索按钮，背景为主题色。 |
| `xs` | 特小尺寸样式。 |
| `s` | 小尺寸样式。 |
| `m` | 中等尺寸样式。 |
| `l` | 大尺寸样式。 |
+++
^^^
^^^value
:::badges
`v-model`
:::
输入框的值。
^^^
^^^suggestions
推荐列表。列表项为 `Object` 时格式为 `{label, value}`。
+++字段详情
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `label` | `string` | 推荐项文本。 |
| `value` | `string` | 推荐项值。 |
+++
^^^
^^^suggest-trigger
展示推荐列表的触发时机。可以是枚举值，也可以枚举值的组合。
+++枚举值
| 值 | 描述 |
| -- | -- |
| `focus` | 输入框聚焦时。 |
| `input` | 输入框触发 `input` 事件时。 |
| `submit` | 点击搜索按钮时。 |
+++
^^^
### 插槽
| 名称 | 描述 |
| -- | -- |
| `suggestions` | [^slot-suggestions] |
| `suggestions-before` | 插入推荐列表前的内容。 |
| `suggestions-after` | 插入推荐列表后的内容。 |
| `suggestion` | [^slot-suggestion] |
^^^slot-suggestions
推荐列表内容。
+++作用域参数
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `suggestions` | `Array<{value: string, label: string}>` | 从 `suggestions` 属性归一化类型后的推荐列表。 |
| `select` | `function(suggestion: {value: string, label: string}): void` | 选择指定的推荐项。 |
^^^slot-suggestion
推荐列表的单项插槽，用来定制选项内容。
+++作用域参数
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `label` | `string` | 选项文本。 |
| `value` | `string` | 选项值。 |
`suggestions` 中的每一项，除了 `label` 和 `value` 外的字段也会自动通过 `v-bind` 进行绑定。
当 `suggestions` 为 `Array<string>` 类型时，`label` 和 `value` 均为单项 `string` 值。
+++
^^^
### 事件
| 名称 | 描述 |
| -- | -- |
| `input` | [^event-input] |
| `suggest` | [^event-suggest] |
| `select` | [^event-select] |
| `search` | [^event-search] |
^^^event-input
输入框中文本发生变化时触发该事件，回调参数为 `(value: string)`。
+++参数详情
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `value` | `string` | 输入框的值。 |
+++
^^^
^^^event-suggest
需要展示推荐列表时触发，回调参数为 `(value: string)`。
+++参数详情
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `value` | `string` | 输入框的值。 |
+++
^^^
^^^event-select
选择推荐列表某个选项时触发，回调参数为 `(item: Object)`。
+++参数详情
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `item` | `{label: string, value: string=, ...}` | 单个选项。 |
+++
^^^
^^^event-search
输入内容被提交时触发，回调参数为 `(value: string, event: Event)`。
+++参数详情
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `value` | `string` | 输入框的值。 |
| `event` | [`Event`](https://developer.mozilla.org/en-US/docs/Web/Events/click) | 原生点击事件。 |
+++
^^^
### 图标
| 名称 | 描述 |
| -- | -- |
| `search` | 搜索。 |

Some files were not shown because too many files have changed in this diff Show More