diff --git a/packages/vant/docs/markdown/use-page-visibility.en-US.md b/packages/vant/docs/markdown/use-page-visibility.en-US.md new file mode 100644 index 000000000..d963e77f1 --- /dev/null +++ b/packages/vant/docs/markdown/use-page-visibility.en-US.md @@ -0,0 +1,40 @@ +# usePageVisibility + +### Intro + +Get the visible state of the page. + +## Usage + +### Basic Usage + +```js +import { watch } from 'vue'; +import { usePageVisibility } from '@vant/use'; + +export default { + setup() { + const pageVisibility = usePageVisibility(); + + watch(pageVisibility, (value) => { + console.log('visibility: ', value); + }); + }, +}; +``` + +## API + +### Type Declarations + +```ts +type VisibilityState = 'visible' | 'hidden'; + +function usePageVisibility(): Ref; +``` + +### Return Value + +| Name | Description | Type | +| --- | --- | --- | +| visibilityState | The current visible state of the page, could be `visible` or `hidden` | _Ref\_ | diff --git a/packages/vant/docs/markdown/use-rect.en-US.md b/packages/vant/docs/markdown/use-rect.en-US.md new file mode 100644 index 000000000..1b1721763 --- /dev/null +++ b/packages/vant/docs/markdown/use-rect.en-US.md @@ -0,0 +1,52 @@ +# useRect + +### Intro + +Get the size of an element and its position relative to the viewport, equivalent to [Element.getBoundingClientRect](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect). + +## Usage + +### Basic Usage + +```html +
+``` + +```js +import { ref, onMounted } from 'vue'; +import { useRect } from '@vant/use'; + +export default { + setup() { + const root = ref(); + + onMounted(() => { + const rect = useRect(root); + console.log(rect); // -> the size of an element and its position relative to the viewport + }); + + return { root }; + }, +}; +``` + +## API + +### Type Declarations + +```ts +function useRect( + element: Element | Window | Ref +): DOMRect; +``` + +### Return Value + +| Name | Description | Type | +| --- | --- | --- | +| width | Width of the element | _number_ | +| height | Height of the element | _number_ | +| top | The distance from the top to the top-left of the viewport | _number_ | +| left | The distance from the left to the top-left of the viewport | _number_ | +| right | The distance from the right to the top-left of the viewport | _number_ | +| bottom | The distance from the bottom to the top-left of the viewport | _number_ | diff --git a/packages/vant/docs/markdown/use-relation.en-US.md b/packages/vant/docs/markdown/use-relation.en-US.md new file mode 100644 index 000000000..3e190f0ab --- /dev/null +++ b/packages/vant/docs/markdown/use-relation.en-US.md @@ -0,0 +1,80 @@ +# useRelation + +### Intro + +Establish the association relationship between parent and child components, perform data communication and method invocation, based on `provide` and `inject` implementation. + +## Usage + +### Basic Usage + +Use `useChildren` in parent to associate child components: + +```js +import { ref } from 'vue'; +import { useChildren } from '@vant/use'; + +const RELATION_KEY = Symbol('my-relation'); + +export default { + setup() { + const { linkChildren } = useChildren(RELATION_KEY); + + const count = ref(0); + const add = () => { + count.value++; + }; + + // provide data and methods to children + linkChildren({ add, count }); + }, +}; +``` + +Use `useParent` in child component to get the data and methods provided by parent. + +```js +import { useParent } from '@vant/use'; + +export default { + setup() { + const { parent } = useParent(RELATION_KEY); + + // use data and methods provided by parent + if (parent) { + parent.add(); + console.log(parent.count.value); // -> 1 + } + }, +}; +``` + +## API + +### Type Declarations + +```ts +function useParent(key: string | symbol): { + parent?: T; + index?: Ref; +}; + +function useChildren(key: string | symbol): { + children: ComponentPublicInstance[]; + linkChildren: (value: any) => void; +}; +``` + +### Return Value of useParent + +| Name | Description | Type | +| --- | --- | --- | +| parent | Data and methods provided by parent | _any_ | +| index | Index position of the current component in all child of the parent component | _Ref\_ | + +### Return Value of useChildren + +| Name | Description | Type | +| --- | --- | --- | +| children | Component list of children | _ComponentPublicInstance[]_ | +| linkChildren | Function to provide values to child | _(value: any) => void_ | diff --git a/packages/vant/docs/markdown/use-scroll-parent.en-US.md b/packages/vant/docs/markdown/use-scroll-parent.en-US.md new file mode 100644 index 000000000..83cdccabb --- /dev/null +++ b/packages/vant/docs/markdown/use-scroll-parent.en-US.md @@ -0,0 +1,57 @@ +# useScrollParent + +### Intro + +Get the closest parent element that is scrollable. + +## Usage + +### Basic Usage + +```html +
+``` + +```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 + +### Type Declarations + +```ts +function useScrollParent( + element: Ref +): Ref; +``` + +### Params + +| Name | Description | Type | Default Value | +| ------- | ------------------- | --------------- | ------------- | +| element | The current element | _Ref\_ | - | + +### Return Value + +| Name | Description | Type | +| --- | --- | --- | +| scrollParent | The closest parent element that is scrollable | _Ref\_ | diff --git a/packages/vant/docs/markdown/use-window-size.en-US.md b/packages/vant/docs/markdown/use-window-size.en-US.md new file mode 100644 index 000000000..21019d74d --- /dev/null +++ b/packages/vant/docs/markdown/use-window-size.en-US.md @@ -0,0 +1,45 @@ +# useWindowSize + +### Intro + +Get the viewport width and height of the browser window, and update it automatically when the window size changes. + +## Usage + +### Basic Usage + +```js +import { watch } from 'vue'; +import { useWindowSize } from '@vant/use'; + +export default { + setup() { + const { width, height } = useWindowSize(); + + console.log(width.value); // -> width of browser window + console.log(height.value); // -> height of browser window + + watch([width, height], () => { + console.log('window resized'); + }); + }, +}; +``` + +## API + +### Type Declarations + +```ts +function useWindowSize(): { + width: Ref; + height: Ref; +}; +``` + +### Return Value + +| Name | Description | Type | +| ------ | ---------------------------- | -------------- | +| width | The width of browser window | _Ref\_ | +| height | The height of browser window | _Ref\_ | diff --git a/packages/vant/docs/markdown/vant-use-intro.en-US.md b/packages/vant/docs/markdown/vant-use-intro.en-US.md index ffe9bec17..30ba38401 100644 --- a/packages/vant/docs/markdown/vant-use-intro.en-US.md +++ b/packages/vant/docs/markdown/vant-use-intro.en-US.md @@ -38,4 +38,9 @@ console.log(height.value); // -> window height | [useCountDown](#/en-US/use-count-down) | Used to manage the countdown | | [useCustomFieldValue](#/en-US/use-custom-field-value) | Used to custom Field value | | [useEventListener](#/en-US/use-event-listener) | Used to attach event | +| [usePageVisibility](#/en-US/use-page-visibility) | Get the visible state of the page | +| [useRect](#/en-US/use-rect) | Get the size of an element and its position relative to the viewport | +| [useRelation](#/en-US/use-relation) | Establish the association relationship between parent and child components | +| [useScrollParent](#/en-US/use-scroll-parent) | Get the closest parent element that is scrollable | | [useToggle](#/en-US/use-toggle) | Used to switch between `true` and `false` | +| [useWindowSize](#/en-US/use-window-size) | Get the viewport width and height of the browser window | diff --git a/packages/vant/vant.config.mjs b/packages/vant/vant.config.mjs index 4499d8bbf..86e34d454 100644 --- a/packages/vant/vant.config.mjs +++ b/packages/vant/vant.config.mjs @@ -854,30 +854,30 @@ export default { path: 'use-event-listener', title: 'useEventListener', }, - // { - // path: 'use-page-visibility', - // title: 'usePageVisibility', - // }, - // { - // path: 'use-rect', - // title: 'useRect', - // }, - // { - // path: 'use-relation', - // title: 'useRelation', - // }, - // { - // path: 'use-scroll-parent', - // title: 'useScrollParent', - // }, + { + path: 'use-page-visibility', + title: 'usePageVisibility', + }, + { + path: 'use-rect', + title: 'useRect', + }, + { + path: 'use-relation', + title: 'useRelation', + }, + { + path: 'use-scroll-parent', + title: 'useScrollParent', + }, { path: 'use-toggle', title: 'useToggle', }, - // { - // path: 'use-window-size', - // title: 'useWindowSize', - // }, + { + path: 'use-window-size', + title: 'useWindowSize', + }, ], }, {