mirror of
https://github.com/youzan/vant.git
synced 2025-10-16 16:04:04 +00:00
docs: migrate vant-use document to vant
This commit is contained in:
chenjiahan
@@ -1,85 +0,0 @@
|
||||
# useClickAway
|
||||
|
||||
监听点击元素外部的事件。
|
||||
|
||||
## 代码演示
|
||||
|
||||
### 基本用法
|
||||
|
||||
```html
|
||||
<div ref="root" />
|
||||
```
|
||||
|
||||
```js
|
||||
import { ref } from 'vue';
|
||||
import { useClickAway } from '@vant/use';
|
||||
|
||||
export default {
|
||||
setup() {
|
||||
const root = ref();
|
||||
useClickAway(root, () => {
|
||||
console.log('click outside!');
|
||||
});
|
||||
|
||||
return { root };
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
### 自定义事件
|
||||
|
||||
通过 `eventName` 选项可以自定义需要监听的事件类型。
|
||||
|
||||
```html
|
||||
<div ref="root" />
|
||||
```
|
||||
|
||||
```js
|
||||
import { ref } from 'vue';
|
||||
import { useClickAway } from '@vant/use';
|
||||
|
||||
export default {
|
||||
setup() {
|
||||
const root = ref();
|
||||
useClickAway(
|
||||
root,
|
||||
() => {
|
||||
console.log('touch outside!');
|
||||
},
|
||||
{ eventName: 'touchstart' }
|
||||
);
|
||||
|
||||
return { root };
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
## API
|
||||
|
||||
### 类型定义
|
||||
|
||||
```ts
|
||||
type Options = {
|
||||
eventName?: string;
|
||||
};
|
||||
|
||||
function useClickAway(
|
||||
target: Element | Ref<Element | undefined>,
|
||||
listener: EventListener,
|
||||
options?: Options
|
||||
): void;
|
||||
```
|
||||
|
||||
### 参数
|
||||
|
||||
| 参数 | 说明 | 类型 | 默认值 |
|
||||
| -------- | ------------------------ | -------------------------- | ------ |
|
||||
| target | 绑定事件的元素 | _Element \| Ref\<Element>_ | - |
|
||||
| listener | 点击外部时触发的回调函数 | _EventListener_ | - |
|
||||
| options | 可选的配置项 | _Options_ | 见下表 |
|
||||
|
||||
### Options
|
||||
|
||||
| 参数 | 说明 | 类型 | 默认值 |
|
||||
| --------- | -------------- | -------- | ------- |
|
||||
| eventName | 监听的事件类型 | _string_ | `click` |
|
||||
@@ -1,118 +0,0 @@
|
||||
# useCountDown
|
||||
|
||||
提供倒计时管理能力。
|
||||
|
||||
## 代码演示
|
||||
|
||||
### 基本用法
|
||||
|
||||
```html
|
||||
<span>总时间：{{ current.total }}</span>
|
||||
<span>剩余天数：{{ current.days }}</span>
|
||||
<span>剩余小时：{{ current.hours }}</span>
|
||||
<span>剩余分钟：{{ current.minutes }}</span>
|
||||
<span>剩余秒数：{{ current.seconds }}</span>
|
||||
<span>剩余毫秒：{{ current.milliseconds }}</span>
|
||||
```
|
||||
|
||||
```js
|
||||
import { useCountDown } from '@vant/use';
|
||||
|
||||
export default {
|
||||
setup() {
|
||||
const countDown = useCountDown({
|
||||
// 倒计时 24 小时
|
||||
time: 24 * 60 * 60 * 1000,
|
||||
});
|
||||
|
||||
// 开始倒计时
|
||||
countDown.start();
|
||||
|
||||
return {
|
||||
current: countDown.current,
|
||||
};
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
### 毫秒级渲染
|
||||
|
||||
倒计时默认每秒渲染一次，设置 millisecond 属性可以开启毫秒级渲染。
|
||||
|
||||
```js
|
||||
import { useCountDown } from '@vant/use';
|
||||
|
||||
export default {
|
||||
setup() {
|
||||
const countDown = useCountDown({
|
||||
time: 24 * 60 * 60 * 1000,
|
||||
millisecond: true,
|
||||
});
|
||||
countDown.start();
|
||||
|
||||
return {
|
||||
current: countDown.current,
|
||||
};
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
## API
|
||||
|
||||
### 类型定义
|
||||
|
||||
```ts
|
||||
type CurrentTime = {
|
||||
days: number;
|
||||
hours: number;
|
||||
total: number;
|
||||
minutes: number;
|
||||
seconds: number;
|
||||
milliseconds: number;
|
||||
};
|
||||
|
||||
type CountDown = {
|
||||
start: () => void;
|
||||
pause: () => void;
|
||||
reset: (totalTime: number) => void;
|
||||
current: ComputedRef<CurrentTime>;
|
||||
};
|
||||
|
||||
type UseCountDownOptions = {
|
||||
time: number;
|
||||
millisecond?: boolean;
|
||||
onChange?: (current: CurrentTime) => void;
|
||||
onFinish?: () => void;
|
||||
};
|
||||
|
||||
function useCountDown(options: UseCountDownOptions): CountDown;
|
||||
```
|
||||
|
||||
### 参数
|
||||
|
||||
| 参数 | 说明 | 类型 | 默认值 |
|
||||
| --- | --- | --- | --- |
|
||||
| time | 倒计时时长，单位毫秒 | _number_ | - |
|
||||
| millisecond | 是否开启毫秒级渲染 | _boolean_ | `false` |
|
||||
| onChange | 倒计时改变时触发的回调函数 | _(current: CurrentTime) => void_ | - |
|
||||
| onFinish | 倒计时结束时触发的回调函数 | - |
|
||||
|
||||
### 返回值
|
||||
|
||||
| 参数 | 说明 | 类型 |
|
||||
| ------- | ---------------------------------- | ----------------------- |
|
||||
| current | 当前剩余的时间 | _CurrentTime_ |
|
||||
| start | 开始倒计时 | _() => void_ |
|
||||
| pause | 暂停倒计时 | _() => void_ |
|
||||
| reset | 重置倒计时，支持传入新的倒计时时长 | _(time?: number): void_ |
|
||||
|
||||
### CurrentTime 格式
|
||||
|
||||
| 名称 | 说明 | 类型 |
|
||||
| ------------ | ---------------------- | -------- |
|
||||
| total | 剩余总时间（单位毫秒） | _number_ |
|
||||
| days | 剩余天数 | _number_ |
|
||||
| hours | 剩余小时 | _number_ |
|
||||
| minutes | 剩余分钟 | _number_ |
|
||||
| seconds | 剩余秒数 | _number_ |
|
||||
| milliseconds | 剩余毫秒 | _number_ |
|
||||
@@ -1,65 +0,0 @@
|
||||
# useEventListener
|
||||
|
||||
方便地进行事件绑定，在组件 `mounted` 和 `activated` 时绑定事件，`unmounted` 和 `deactivated` 时解绑事件。
|
||||
|
||||
## 代码演示
|
||||
|
||||
### 基本用法
|
||||
|
||||
```js
|
||||
import { ref } from 'vue';
|
||||
import { useEventListener } from '@vant/use';
|
||||
|
||||
export default {
|
||||
setup() {
|
||||
// 在 window 上绑定 resize 事件
|
||||
// 未指定监听对象时，默认会监听 window 的事件
|
||||
useEventListener('resize', () => {
|
||||
console.log('window resize');
|
||||
});
|
||||
|
||||
// 在 body 元素上绑定 click 事件
|
||||
useEventListener(
|
||||
'click',
|
||||
() => {
|
||||
console.log('click body');
|
||||
},
|
||||
{ target: document.body }
|
||||
);
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
## 类型定义
|
||||
|
||||
```ts
|
||||
type Options = {
|
||||
target?: EventTarget | Ref<EventTarget>;
|
||||
capture?: boolean;
|
||||
passive?: boolean;
|
||||
};
|
||||
|
||||
function useEventListener(
|
||||
type: string,
|
||||
listener: EventListener,
|
||||
options?: Options
|
||||
): void;
|
||||
```
|
||||
|
||||
## API
|
||||
|
||||
### 参数
|
||||
|
||||
| 参数 | 说明 | 类型 | 默认值 |
|
||||
| -------- | ------------------------ | --------------- | ------ |
|
||||
| type | 监听的事件类型 | _string_ | - |
|
||||
| listener | 点击外部时触发的回调函数 | _EventListener_ | - |
|
||||
| options | 可选的配置项 | _Options_ | - |
|
||||
|
||||
### Options
|
||||
|
||||
| 参数 | 说明 | 类型 | 默认值 |
|
||||
| --- | --- | --- | --- |
|
||||
| target | 绑定事件的元素 | _EventTarget \| Ref\<EventTarget>_ | `window` |
|
||||
| capture | 是否在事件捕获阶段触发 | _boolean_ | `false` |
|
||||
| passive | 设置为 `true` 时，表示 `listener` 永远不会调用 `preventDefault` | _boolean_ | `false` |
|
||||
@@ -1,38 +0,0 @@
|
||||
# usePageVisibility
|
||||
|
||||
获取页面的可见状态。
|
||||
|
||||
## 代码演示
|
||||
|
||||
### 基本用法
|
||||
|
||||
```js
|
||||
import { watch } from 'vue';
|
||||
import { usePageVisibility } from '@vant/use';
|
||||
|
||||
export default {
|
||||
setup() {
|
||||
const pageVisibility = usePageVisibility();
|
||||
|
||||
watch(pageVisibility, (value) => {
|
||||
console.log('visibility: ', value);
|
||||
});
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
## API
|
||||
|
||||
### 类型定义
|
||||
|
||||
```ts
|
||||
type VisibilityState = 'visible' | 'hidden';
|
||||
|
||||
function usePageVisibility(): Ref<VisibilityState>;
|
||||
```
|
||||
|
||||
### 返回值
|
||||
|
||||
| 参数 | 说明 | 类型 |
|
||||
| --- | --- | --- |
|
||||
| visibilityState | 页面当前的可见状态，`visible` 为可见，`hidden` 为隐藏 | _Ref\<VisibilityState>_ |
|
||||
@@ -1,48 +0,0 @@
|
||||
# useRect
|
||||
|
||||
获取元素的大小及其相对于视口的位置，等价于 [Element.getBoundingClientRect](https://developer.mozilla.org/zh-CN/docs/Web/API/Element/getBoundingClientRect)。
|
||||
|
||||
## 代码演示
|
||||
|
||||
### 基本用法
|
||||
|
||||
```html
|
||||
<div ref="root" />
|
||||
```
|
||||
|
||||
```js
|
||||
import { ref } from 'vue';
|
||||
import { useRect } from '@vant/use';
|
||||
|
||||
export default {
|
||||
setup() {
|
||||
const root = ref();
|
||||
const rect = useRect();
|
||||
|
||||
console.log(rect); // -> 元素的大小及其相对于视口的位置
|
||||
|
||||
return { root };
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
## API
|
||||
|
||||
### 类型定义
|
||||
|
||||
```ts
|
||||
function useRect(
|
||||
element: Element | Window | Ref<Element | Window | undefined>
|
||||
): DOMRect;
|
||||
```
|
||||
|
||||
### 返回值
|
||||
|
||||
| 参数 | 说明 | 类型 |
|
||||
| ------ | -------------------------- | -------- |
|
||||
| width | 宽度 | _number_ |
|
||||
| height | 高度 | _number_ |
|
||||
| top | 顶部与视图窗口左上角的距离 | _number_ |
|
||||
| left | 左侧与视图窗口左上角的距离 | _number_ |
|
||||
| right | 右侧与视图窗口左上角的距离 | _number_ |
|
||||
| bottom | 底部与视图窗口左上角的距离 | _number_ |
|
||||
@@ -1,80 +0,0 @@
|
||||
# useRelation
|
||||
|
||||
建立父子组件之间的关联关系，进行数据通信和方法调用，基于 `provide` 和 `inject` 实现。
|
||||
|
||||
## 代码演示
|
||||
|
||||
### 基本用法
|
||||
|
||||
```js
|
||||
// Parent.vue
|
||||
import { ref } from 'vue';
|
||||
import { useChildren } from '@vant/use';
|
||||
|
||||
const RELATION_KEY = 'my-relation';
|
||||
|
||||
export default {
|
||||
setup() {
|
||||
const { linkChildren } = useChildren(RELATION_KEY);
|
||||
|
||||
const count = ref(0);
|
||||
const add = () => {
|
||||
count.value++;
|
||||
};
|
||||
|
||||
// 向子组件提供数据和方法
|
||||
linkChildren({ add, count });
|
||||
},
|
||||
};
|
||||
|
||||
// Child.vue
|
||||
import { useParent } from '@vant/use';
|
||||
|
||||
const RELATION_KEY = 'my-relation';
|
||||
|
||||
export default {
|
||||
setup() {
|
||||
const { parent } = useParent(RELATION_KEY);
|
||||
|
||||
// 调用父组件提供的数据和方法
|
||||
if (parent) {
|
||||
parent.add();
|
||||
console.log(parent.count.value); // -> 1
|
||||
}
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
## API
|
||||
|
||||
### 类型定义
|
||||
|
||||
```ts
|
||||
function useParent<T>(
|
||||
key: string | symbol
|
||||
): {
|
||||
parent?: T;
|
||||
index?: Ref<number>;
|
||||
};
|
||||
|
||||
function useChildren(
|
||||
key: string | symbol
|
||||
): {
|
||||
children: ComponentPublicInstance[];
|
||||
linkChildren: (value: any) => void;
|
||||
};
|
||||
```
|
||||
|
||||
### useParent 返回值
|
||||
|
||||
| 参数 | 说明 | 类型 |
|
||||
| ------ | -------------------------------------------- | -------------- |
|
||||
| parent | 父组件提供的值 | _any_ |
|
||||
| index | 当前组件在父组件的所有子组件中对应的索引位置 | _Ref\<number>_ |
|
||||
|
||||
### useChildren 返回值
|
||||
|
||||
| 参数 | 说明 | 类型 |
|
||||
| ------------ | -------------------- | --------------------------- |
|
||||
| children | 子组件列表 | _ComponentPublicInstance[]_ |
|
||||
| linkChildren | 向子组件提供值的方法 | _(value: any) => void_ |
|
||||
@@ -1,55 +0,0 @@
|
||||
# useScrollParent
|
||||
|
||||
获取元素最近的可滚动父元素。
|
||||
|
||||
## 代码演示
|
||||
|
||||
### 基本用法
|
||||
|
||||
```html
|
||||
<div ref="root" />
|
||||
```
|
||||
|
||||
```js
|
||||
import { ref, watch } from 'vue';
|
||||
import { useScrollParent, useEventListener } from '@vant/use';
|
||||
|
||||
export default {
|
||||
setup() {
|
||||
const root = ref();
|
||||
const scrollParent = useScrollParent(root);
|
||||
|
||||
useEventListener(
|
||||
'scroll',
|
||||
() => {
|
||||
console.log('scroll');
|
||||
},
|
||||
{ target: scrollParent }
|
||||
);
|
||||
|
||||
return { root };
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
## API
|
||||
|
||||
### 类型定义
|
||||
|
||||
```ts
|
||||
function useScrollParent(
|
||||
element: Ref<Element | undefined>
|
||||
): Ref<Element | Window | undefined>;
|
||||
```
|
||||
|
||||
### 参数
|
||||
|
||||
| 参数 | 说明 | 类型 | 默认值 |
|
||||
| ------- | -------- | --------------- | ------ |
|
||||
| element | 当前元素 | _Ref\<Element>_ | - |
|
||||
|
||||
### 返回值
|
||||
|
||||
| 参数 | 说明 | 类型 |
|
||||
| ------------ | ------------------ | --------------- |
|
||||
| scrollParent | 最近的可滚动父元素 | _Ref\<Element>_ |
|
||||
@@ -1,62 +0,0 @@
|
||||
# useToggle
|
||||
|
||||
用于在 `true` 和 `false` 之间进行切换。
|
||||
|
||||
## 代码演示
|
||||
|
||||
### 基本用法
|
||||
|
||||
```js
|
||||
import { useToggle } from '@vant/use';
|
||||
|
||||
export default {
|
||||
setup() {
|
||||
const [state, toggle] = useToggle();
|
||||
|
||||
toggle(true);
|
||||
console.log(state.value); // -> true
|
||||
|
||||
toggle(false);
|
||||
console.log(state.value); // -> false
|
||||
|
||||
toggle();
|
||||
console.log(state.value); // -> true
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
### 设置默认值
|
||||
|
||||
```js
|
||||
import { useToggle } from '@vant/use';
|
||||
|
||||
export default {
|
||||
setup() {
|
||||
const [state, toggle] = useToggle(true);
|
||||
console.log(state.value); // -> true
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
## API
|
||||
|
||||
### 类型定义
|
||||
|
||||
```ts
|
||||
function useToggle(
|
||||
defaultValue: boolean
|
||||
): [Ref<boolean>, (newValue: boolean) => void];
|
||||
```
|
||||
|
||||
### 参数
|
||||
|
||||
| 参数 | 说明 | 类型 | 默认值 |
|
||||
| ------------ | ------ | --------- | ------- |
|
||||
| defaultValue | 默认值 | _boolean_ | `false` |
|
||||
|
||||
### 返回值
|
||||
|
||||
| 参数 | 说明 | 类型 |
|
||||
| ------ | ---------------- | ------------------------------ |
|
||||
| state | 状态值 | _Ref\<boolean>_ |
|
||||
| toggle | 切换状态值的函数 | _(newValue?: boolean) => void_ |
|
||||
@@ -1,43 +0,0 @@
|
||||
# useWindowSize
|
||||
|
||||
获取浏览器窗口的视口宽度和高度，并在窗口大小变化时自动更新。
|
||||
|
||||
## 代码演示
|
||||
|
||||
### 基本用法
|
||||
|
||||
```js
|
||||
import { watch } from 'vue';
|
||||
import { useWindowSize } from '@vant/use';
|
||||
|
||||
export default {
|
||||
setup() {
|
||||
const { width, height } = useWindowSize();
|
||||
|
||||
console.log(width.value); // -> 窗口宽度
|
||||
console.log(height.value); // -> 窗口高度
|
||||
|
||||
watch([width, height], () => {
|
||||
console.log('window resized');
|
||||
});
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
## API
|
||||
|
||||
### 类型定义
|
||||
|
||||
```ts
|
||||
function useWindowSize(): {
|
||||
width: Ref<number>;
|
||||
height: Ref<number>;
|
||||
};
|
||||
```
|
||||
|
||||
### 返回值
|
||||
|
||||
| 参数 | 说明 | 类型 |
|
||||
| ------ | -------------- | -------------- |
|
||||
| width | 浏览器窗口宽度 | _Ref\<number>_ |
|
||||
| height | 浏览器窗口高度 | _Ref\<number>_ |
|
||||
Reference in New Issue
Block a user