Skip to content

Commit b852376

Browse files
MoonofweishengMoonofweisheng
authored
feat: ✨ 添加组合式API文档并提供相关API (#972)
1 parent 58157d8 commit b852376

10 files changed

Lines changed: 445 additions & 8 deletions

File tree

‎docs/.vitepress/config.mts‎

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
/*
22
* @Author: weisheng
33
* @Date: 2023-07-27 10:26:09
4-
* @LastEditTime: 2025-03-19 18:53:23
4+
* @LastEditTime: 2025-03-25 16:27:19
55
* @LastEditors: weisheng
66
* @Description:
77
* @FilePath: /wot-design-uni/docs/.vitepress/config.mts
@@ -423,8 +423,8 @@ export default defineConfig({
423423
link: "/component/number-keyboard",
424424
text: "NumberKeyboard 数字键盘"
425425
}]
426-
}, {
427-
426+
},
427+
{
428428
text: "数据展示",
429429
collapsed: false,
430430
items: [{
@@ -482,6 +482,15 @@ export default defineConfig({
482482
link: "/component/table",
483483
text: "Table 表格"
484484
}]
485+
},
486+
{
487+
text: '组合式API',
488+
items: [
489+
{ text: 'useUpload', link: '/component/use-upload' },
490+
{ text: 'useCountDown', link: '/component/use-count-down' },
491+
{ text: 'useToast', link: '/component/use-toast' },
492+
{ text: 'useMessage', link: '/component/use-message' }
493+
]
485494
}
486495
]
487496
}

‎docs/.vitepress/plugins/markdown-transform.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,3 @@
1-
21
import { Plugin } from 'vite';
32
import { camelCase } from '../../../src/uni_modules/wot-design-uni/components/common/util'
43
import path from 'path'
@@ -9,6 +8,7 @@ export function MarkdownTransform(): Plugin {
98
async transform(code, id) {
109
if (!id.endsWith('.md')) return
1110
if (!id.includes('/component')) return
11+
if (id.includes('/use-')) return
1212
const GITHUB_URL = 'https://github.com/Moonofweisheng/wot-design-uni/tree/master'
1313
const componentId = path.basename(id, '.md')
1414
const componentName = `wd-${componentId}`

‎docs/.vitepress/theme/components/VPDoc.vue‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,9 @@ const { hasSidebar, hasAside, leftAside } = useSidebar()
1515
const pageName = computed(() =>
1616
route.path.replace(/[./]+/g, '_').replace(/_html$/, '')
1717
)
18-
const isComponent = computed(() => route.path.startsWith('/component'))
18+
const isComponent = computed(() =>
19+
route.path.startsWith('/component') && !route.path.includes('/use-')
20+
)
1921
const expanded = ref(true)
2022
2123
</script>

‎docs/component/use-count-down.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# useCountDown
2+
3+
用于处理倒计时相关的逻辑。
4+
5+
## 基础用法
6+
7+
```ts
8+
import { useCountDown } from '@/uni_modules/wot-design-uni'
9+
10+
const { start, pause, reset, current } = useCountDown({
11+
time: 60 * 1000,
12+
onChange(current) {
13+
console.log('剩余时间', current)
14+
},
15+
onFinish() {
16+
console.log('倒计时结束')
17+
}
18+
})
19+
20+
// 开始倒计时
21+
start()
22+
23+
// 暂停倒计时
24+
pause()
25+
26+
// 重置倒计时
27+
reset()
28+
29+
// 获取当前时间
30+
console.log(current.value)
31+
```
32+
33+
## API
34+
35+
### 参数
36+
37+
| 参数 | 说明 | 类型 | 默认值 |
38+
|-----|------|------|--------|
39+
| time | 倒计时总时间(ms) | number | - |
40+
| millisecond | 是否开启毫秒级渲染 | boolean | false |
41+
| onChange | 倒计时变化回调 | (current: CurrentTime) => void | - |
42+
| onFinish | 倒计时结束回调 | () => void | - |
43+
44+
### 方法
45+
46+
| 方法名 | 说明 | 参数 | 返回值 |
47+
|-------|------|------|--------|
48+
| start | 开始倒计时 | - | - |
49+
| pause | 暂停倒计时 | - | - |
50+
| reset | 重置倒计时 | time?: number | - |
51+
52+
### CurrentTime 结构
53+
54+
```ts
55+
type CurrentTime = {
56+
days: number
57+
hours: number
58+
total: number
59+
minutes: number
60+
seconds: number
61+
milliseconds: number
62+
}
63+
```

‎docs/component/use-message.md‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
# useMessage
2+
3+
用于便捷地调用 MessageBox 弹框组件。
4+
5+
## Alert 弹框
6+
7+
alert 弹框只有确定按钮，用于强提醒。
8+
9+
```html
10+
<wd-message-box></wd-message-box>
11+
<wd-button @click="alert">alert</wd-button>
12+
```
13+
14+
```ts
15+
import { useMessage } from '@/uni_modules/wot-design-uni'
16+
const message = useMessage()
17+
18+
function alert() {
19+
message.alert('操作成功')
20+
}
21+
```
22+
23+
## Confirm 弹框
24+
25+
用于提示用户操作。
26+
27+
```html
28+
<wd-message-box />
29+
<wd-button @click="confirm">confirm</wd-button>
30+
```
31+
32+
```ts
33+
import { useMessage } from '@/uni_modules/wot-design-uni'
34+
const message = useMessage()
35+
36+
function confirm() {
37+
message
38+
.confirm({
39+
msg: '提示文案',
40+
title: '标题'
41+
})
42+
.then(() => {
43+
console.log('点击了确定按钮')
44+
})
45+
.catch(() => {
46+
console.log('点击了取消按钮')
47+
})
48+
}
49+
```
50+
51+
## Prompt 弹框
52+
53+
prompt 会展示一个输入框，并可以进行输入校验。
54+
55+
```html
56+
<wd-message-box />
57+
<wd-button @click="prompt">prompt</wd-button>
58+
```
59+
60+
```ts
61+
import { useMessage } from '@/uni_modules/wot-design-uni'
62+
const message = useMessage()
63+
64+
function prompt() {
65+
message
66+
.prompt({
67+
title: '请输入邮箱',
68+
inputPattern: /.+@.+\..+/i,
69+
inputError: '邮箱格式不正确'
70+
})
71+
.then((resp) => {
72+
console.log(resp)
73+
})
74+
.catch((error) => {
75+
console.log(error)
76+
})
77+
}
78+
```
79+
80+
## API
81+
82+
### Methods
83+
84+
| 方法名称 | 说明 | 参数 |
85+
|--------|----------------|---------|
86+
| show | 展示弹框 | options |
87+
| alert | 展示 Alert 弹框 | options |
88+
| confirm| 展示 Confirm 弹框| options |
89+
| prompt | 展示 Prompt 弹框| options |
90+
| close | 关闭弹框 | - |
91+
92+
### Options
93+
94+
| 参数 | 说明 | 类型 | 可选值 | 默认值 |
95+
|-----|------|------|--------|--------|
96+
| title | 标题 | string | - | - |
97+
| msg | 消息文案 | string | - | - |
98+
| type | 弹框类型 | string | alert / confirm / prompt | alert |
99+
| closeOnClickModal | 是否支持点击蒙层进行关闭 | boolean | - | true |
100+
| inputType | 当type为prompt时，输入框类型 | string | - | text |
101+
| inputValue | 当type为prompt时，输入框初始值 | string / number | - | - |
102+
| inputPlaceholder | 当type为prompt时，输入框placeholder | string | - | 请输入内容 |
103+
| inputPattern | 当type为prompt时，输入框正则校验 | RegExp | - | - |
104+
| inputValidate | 当type为prompt时，输入框校验函数 | function | - | - |
105+
| inputError | 当type为prompt时，输入框检验不通过时的错误提示文案 | string | - | 输入的数据不合法 |
106+
| confirmButtonText | 确定按钮文案 | string | - | 确定 |
107+
| cancelButtonText | 取消按钮文案 | string | - | 取消 |
108+
| zIndex | 弹窗层级 | number | - | 99 |
109+
| selector | 指定唯一标识 | string | - | '' |

‎docs/component/use-notify.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# useNotify
2+
3+
用于便捷地调用 Notify 消息通知组件。
4+
5+
## 基本用法
6+
7+
需要在页面中引入 wd-notify 组件作为挂载点。
8+
9+
```html
10+
<wd-notify />
11+
<wd-button @click="showNotify">notify</wd-button>
12+
```
13+
14+
```ts
15+
import { useNotify } from '@/uni_modules/wot-design-uni'
16+
17+
const { showNotify } = useNotify()
18+
19+
function showNotify() {
20+
showNotify('通知内容')
21+
}
22+
```
23+
24+
## 通知类型
25+
26+
支持 `primary`、`success`、`warning`、`danger` 四种通知类型，默认为 `danger`。
27+
28+
```ts
29+
// 主要通知
30+
showNotify({ type: 'primary', message: '通知内容' })
31+
32+
// 成功通知
33+
showNotify({ type: 'success', message: '通知内容' })
34+
35+
// 危险通知
36+
showNotify({ type: 'danger', message: '通知内容' })
37+
38+
// 警告通知
39+
showNotify({ type: 'warning', message: '通知内容' })
40+
```
41+
42+
## 自定义样式
43+
44+
```ts
45+
showNotify({
46+
message: '自定义颜色',
47+
color: '#ad0000',
48+
background: '#ffe1e1'
49+
})
50+
51+
showNotify({
52+
message: '自定义位置',
53+
position: 'bottom'
54+
})
55+
56+
showNotify({
57+
message: '自定义时长',
58+
duration: 1000
59+
})
60+
```
61+
62+
## API
63+
64+
### Methods
65+
66+
| 方法名称 | 说明 | 参数 |
67+
|---------|------|------|
68+
| showNotify | 展示提示 | `NotifyOptions` / `string` |
69+
| closeNotify | 关闭提示 | - |
70+
| setNotifyDefaultOptions | 修改默认配置，影响所有的 `showNotify` 调用 | `NotifyOptions` |
71+
| resetNotifyDefaultOptions | 重置默认配置，影响所有的 `showNotify` 调用 | - |
72+
73+
### Options
74+
75+
| 参数 | 说明 | 类型 | 可选值 | 默认值 |
76+
|-----|------|------|--------|--------|
77+
| type | 类型 | NotifyType | `primary` `success` `warning` `danger` | `danger` |
78+
| message | 展示文案，支持通过\n换行 | string | - | - |
79+
| duration | 展示时长(ms)，值为 0 时，notify 不会消失 | number | - | 3000 |
80+
| zIndex | 层级 | number | - | 99 |
81+
| position | 弹出位置 | NotifyPosition | `top` `bottom` | `top` |
82+
| color | 字体颜色 | string | - | - |
83+
| background | 背景颜色 | string | - | - |
84+
| safeHeight | 顶部安全高度 | number / string | - | - |
85+
| onClick | 点击时的回调函数 | (event: MouseEvent) => void | - | - |
86+
| onClosed | 关闭时的回调函数 | () => void | - | - |
87+
| onOpened | 展示后的回调函数 | () => void | - | - |

0 commit comments

Comments
 (0)