From 00bda601023f6ea7ccc6e241d856cb8b37bec178 Mon Sep 17 00:00:00 2001
From: Alan Wang <wp_scut@163.com>
Date: Wed, 27 Apr 2022 17:08:12 +0800
Subject: [PATCH] docs: translate docs of composables (#10561)
---
.../markdown/use-page-visibility.en-US.md | 40 ++++++++++
packages/vant/docs/markdown/use-rect.en-US.md | 52 ++++++++++++
.../vant/docs/markdown/use-relation.en-US.md | 80 +++++++++++++++++++
.../docs/markdown/use-scroll-parent.en-US.md | 57 +++++++++++++
.../docs/markdown/use-window-size.en-US.md | 45 +++++++++++
.../docs/markdown/vant-use-intro.en-US.md | 5 ++
packages/vant/vant.config.mjs | 40 +++++-----
7 files changed, 299 insertions(+), 20 deletions(-)
create mode 100644 packages/vant/docs/markdown/use-page-visibility.en-US.md
create mode 100644 packages/vant/docs/markdown/use-rect.en-US.md
create mode 100644 packages/vant/docs/markdown/use-relation.en-US.md
create mode 100644 packages/vant/docs/markdown/use-scroll-parent.en-US.md
create mode 100644 packages/vant/docs/markdown/use-window-size.en-US.md
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<VisibilityState>;
+```
+
+### Return Value
+
+| Name | Description | Type |
+| --- | --- | --- |
+| visibilityState | The current visible state of the page, could be `visible` or `hidden` | _Ref\<VisibilityState>_ |
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
+<div ref="root" />
+```
+
+```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<Element | Window | undefined>
+): 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<T>(key: string | symbol): {
+ parent?: T;
+ index?: Ref<number>;
+};
+
+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\<number>_ |
+
+### 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
+<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
+
+### Type Declarations
+
+```ts
+function useScrollParent(
+ element: Ref<Element | undefined>
+): Ref<Element | Window | undefined>;
+```
+
+### Params
+
+| Name | Description | Type | Default Value |
+| ------- | ------------------- | --------------- | ------------- |
+| element | The current element | _Ref\<Element>_ | - |
+
+### Return Value
+
+| Name | Description | Type |
+| --- | --- | --- |
+| scrollParent | The closest parent element that is scrollable | _Ref\<Element>_ |
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<number>;
+ height: Ref<number>;
+};
+```
+
+### Return Value
+
+| Name | Description | Type |
+| ------ | ---------------------------- | -------------- |
+| width | The width of browser window | _Ref\<number>_ |
+| height | The height of browser window | _Ref\<number>_ |
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',
+ },
],
},
{