From a9f314f32a4376088a1500aaeb59a3d14d7e3be1 Mon Sep 17 00:00:00 2001 From: inottn Date: Fri, 16 Jun 2023 10:06:24 +0800 Subject: [PATCH] types(RollingText): fix missing types export and improve docs content (#11976) * types(RollingText): fix missing types export and improve docs content * docs(RollingText): improve docs content --- packages/vant/src/rolling-text/README.md | 66 +++++++++++++------ .../vant/src/rolling-text/README.zh-CN.md | 62 ++++++++++++----- .../vant/src/rolling-text/RollingText.tsx | 21 ++++-- packages/vant/src/rolling-text/demo/index.vue | 33 +++++----- packages/vant/src/rolling-text/index.ts | 6 ++ packages/vant/src/rolling-text/types.ts | 15 +++++ 6 files changed, 145 insertions(+), 58 deletions(-) diff --git a/packages/vant/src/rolling-text/README.md b/packages/vant/src/rolling-text/README.md index 463aa5f1c..62ba97c86 100644 --- a/packages/vant/src/rolling-text/README.md +++ b/packages/vant/src/rolling-text/README.md @@ -59,7 +59,7 @@ You can set the order of stopping the animation of each digit through the `stop- /> ``` -### Rolling Non-numeric Text +### Roll Non-numeric Text You can set non-numeric content flip using the `text-array` props. @@ -75,6 +75,7 @@ You can set non-numeric content flip using the `text-array` props. ```js import { ref } from 'vue'; + export default { setup() { const textArray = ref([ @@ -95,7 +96,7 @@ export default { ```html { - rollTextEl.value.start(); + rollingTextRef.value.start(); }; const reset = () => { - rollTextEl.value.reset(); + rollingTextRef.value.reset(); }; - return { rollTextEl, start, reset }; + return { rollingTextRef, start, reset }; }, }; ``` @@ -161,20 +162,45 @@ export default { | Attribute | Description | Type | Default | | --- | --- | --- | --- | -| start-num | Start number | _number_ | 0 | +| start-num | Start number | _number_ | `0` | | target-num | Target number | _number_ | - | -| text-array | Text array | _Array_ | [] | -| duration | Duration of the animation, in seconds | _number_ | 2 | +| text-array | Text array | _Array_ | `[]` | +| duration | Duration of the animation, in seconds | _number_ | `2` | | direction | Rolling direction of the number, with `down` and `up` as the values | _string_ | `down` | -| auto-start | Whether to start the animation | _boolean_ | true | +| auto-start | Whether to start the animation | _boolean_ | `true` | | stop-order | Order of stopping the animation of each digit, with `ltr` and `rtl` as the values | _string_ | `ltr` | -### Type Definition +### Methods + +Use [ref](https://v3.vuejs.org/guide/component-template-refs.html) to get RollingText instance and call instance methods. + +| Name | Description | Attribute | Return value | +| ----- | ------------------- | --------- | ------------ | +| start | Start the animation | - | - | +| reset | Reset the animation | - | - | + +### Types The component exports the following type definitions: ```ts -import type { RollingTextProps } from 'vant'; +import type { + RollingTextProps, + RollingTextInstance, + RollingTextDirection, + RollingTextStopOrder, +} from 'vant'; +``` + +`RollingTextInstance` is the type of component instance: + +```ts +import { ref } from 'vue'; +import type { RollingTextInstance } from 'vant'; + +const rollingTextRef = ref(); + +rollingTextRef.value?.start(); ``` ## Theming diff --git a/packages/vant/src/rolling-text/README.zh-CN.md b/packages/vant/src/rolling-text/README.zh-CN.md index 17611fa30..98cbb6f00 100644 --- a/packages/vant/src/rolling-text/README.zh-CN.md +++ b/packages/vant/src/rolling-text/README.zh-CN.md @@ -75,6 +75,7 @@ app.use(RollingText); ```js import { ref } from 'vue'; + export default { setup() { const textArray = ref([ @@ -95,7 +96,7 @@ export default { ```html { - rollTextEl.value.start(); + rollingTextRef.value.start(); }; const reset = () => { - rollTextEl.value.reset(); + rollingTextRef.value.reset(); }; - return { rollTextEl, start, reset }; + return { rollingTextRef, start, reset }; }, }; ``` @@ -161,20 +162,45 @@ export default { | 参数 | 说明 | 类型 | 默认值 | | --- | --- | --- | --- | -| start-num | 开始数值 | _number_ | 0 | +| start-num | 开始数值 | _number_ | `0` | | target-num | 目标数值 | _number_ | - | -| text-array | 内容数组，翻转非数字内容，需要传此参数 | _Array_ | [] | -| duration | 动画时长，单位为秒 | _number_ | 2 | +| text-array | 内容数组，翻转非数字内容，需要传此参数 | _Array_ | `[]` | +| duration | 动画时长，单位为秒 | _number_ | `2` | | direction | 数值翻滚方向，值为 `down` 和 `up` | _string_ | `down` | -| auto-start | 是否自动开始动画 | _boolean_ | true | +| auto-start | 是否自动开始动画 | _boolean_ | `true` | | stop-order | 各个数位动画停止先后顺序，值为 `ltr` 和 `rtl` | _string_ | `ltr` | +### 方法 + +通过 ref 可以获取到 RollingText 实例并调用实例方法，详见[组件实例方法](#/zh-CN/advanced-usage#zu-jian-shi-li-fang-fa)。 + +| 方法名 | 说明 | 参数 | 返回值 | +| ------ | -------- | ---- | ------ | +| start | 开始动画 | - | - | +| reset | 重置动画 | - | - | + ### 类型定义 组件导出以下类型定义： ```ts -import type { RollingTextProps } from 'vant'; +import type { + RollingTextProps, + RollingTextInstance, + RollingTextDirection, + RollingTextStopOrder, +} from 'vant'; +``` + +`RollingTextInstance` 是组件实例的类型，用法如下： + +```ts +import { ref } from 'vue'; +import type { RollingTextInstance } from 'vant'; + +const rollingTextRef = ref(); + +rollingTextRef.value?.start(); ``` ## 主题定制 diff --git a/packages/vant/src/rolling-text/RollingText.tsx b/packages/vant/src/rolling-text/RollingText.tsx index bcf4eb0c5..405b732fe 100644 --- a/packages/vant/src/rolling-text/RollingText.tsx +++ b/packages/vant/src/rolling-text/RollingText.tsx @@ -1,5 +1,5 @@ import { ref, defineComponent, computed, type ExtractPropTypes } from 'vue'; -import RollingTextItem from './RollingTextItem'; + // Utils import { createNamespace, @@ -8,12 +8,21 @@ import { makeStringProp, truthProp, } from '../utils'; + +// Composables import { useExpose } from '../composables/use-expose'; -const [name, bem] = createNamespace('rolling-text'); +// Components +import RollingTextItem from './RollingTextItem'; -export type RollingTextDirection = 'up' | 'down'; -export type RollingTextStopOrder = 'ltr' | 'rtl'; +// Types +import { + RollingTextDirection, + RollingTextStopOrder, + RollingTextExpose, +} from './types'; + +const [name, bem] = createNamespace('rolling-text'); export const rollingTextProps = { startNum: makeNumberProp(0), @@ -90,6 +99,7 @@ export default defineComponent({ }; const isStart = ref(false); + const start = () => { isStart.value = true; }; @@ -97,7 +107,8 @@ export default defineComponent({ const reset = () => { isStart.value = false; }; - useExpose({ + + useExpose({ start, reset, }); diff --git a/packages/vant/src/rolling-text/demo/index.vue b/packages/vant/src/rolling-text/demo/index.vue index d2070064c..496f5c7f6 100644 --- a/packages/vant/src/rolling-text/demo/index.vue +++ b/packages/vant/src/rolling-text/demo/index.vue @@ -1,5 +1,5 @@ @@ -131,7 +131,7 @@ const reset = () => {
{
{ .van-button { margin-left: var(--van-padding-md); } + .van-rolling-text { margin-left: var(--van-padding-md); } + .van-grid { margin-left: var(--van-padding-md); } -.my-rolling-te11xt { +.my-rolling-text { gap: 6px; + .van-roll-single { color: white; background: deepskyblue; diff --git a/packages/vant/src/rolling-text/index.ts b/packages/vant/src/rolling-text/index.ts index 178c84d55..0e3daaec8 100644 --- a/packages/vant/src/rolling-text/index.ts +++ b/packages/vant/src/rolling-text/index.ts @@ -3,7 +3,13 @@ import _RollingText from './RollingText'; export const RollingText = withInstall(_RollingText); export default RollingText; +export { rollingTextProps } from './RollingText'; export type { RollingTextProps } from './RollingText'; +export type { + RollingTextDirection, + RollingTextInstance, + RollingTextStopOrder, +} from './types'; declare module 'vue' { export interface GlobalComponents { diff --git a/packages/vant/src/rolling-text/types.ts b/packages/vant/src/rolling-text/types.ts index e69de29bb..bee3c012c 100644 --- a/packages/vant/src/rolling-text/types.ts +++ b/packages/vant/src/rolling-text/types.ts @@ -0,0 +1,15 @@ +import type { ComponentPublicInstance } from 'vue'; +import type { RollingTextProps } from './RollingText'; + +export type RollingTextDirection = 'up' | 'down'; +export type RollingTextStopOrder = 'ltr' | 'rtl'; + +export type RollingTextExpose = { + start: () => void; + reset: () => void; +}; + +export type RollingTextInstance = ComponentPublicInstance< + RollingTextProps, + RollingTextExpose +>;