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

@@ -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
 <van-rolling-text
-  class="my-roll-number"
+  class="my-rolling-text"
   :start-num="12345"
   :target-num="54321"
   :duration="2"
@@ -107,14 +108,14 @@ export default {
 ```css
 .my-rolling-text {
   gap: 6px;
+}
 
-  .van-roll-single {
-    color: white;
-    background: deepskyblue;
-    border-radius: 5px;
-    width: 25px;
-    font-size: 20px;
-  }
+.my-rolling-text .van-roll-single {
+  color: white;
+  background: deepskyblue;
+  border-radius: 5px;
+  width: 25px;
+  font-size: 20px;
 }
 ```
 
@@ -124,7 +125,7 @@ After getting the component instance through `ref`, you can call the `start` and
 
 ```html
 <van-rolling-text
-  ref="rollTextEl"
+  ref="rollingTextRef"
   :start-num="0"
   :target-num="54321"
   :duration="2"
@@ -143,14 +144,14 @@ import { ref } from 'vue';
 
 export default {
   setup() {
-    const rollTextEl = ref(null);
+    const rollingTextRef = ref(null);
     const start = () => {
-      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<RollingTextInstance>();
+
+rollingTextRef.value?.start();
 ```
 
 ## Theming

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
 <van-rolling-text
-  class="my-roll-number"
+  class="my-rolling-text"
   :start-num="12345"
   :target-num="54321"
   :duration="2"
@@ -107,14 +108,14 @@ export default {
 ```css
 .my-rolling-text {
   gap: 6px;
+}
 
-  .van-roll-single {
-    color: white;
-    background: deepskyblue;
-    border-radius: 5px;
-    width: 25px;
-    font-size: 20px;
-  }
+.my-rolling-text .van-roll-single {
+  color: white;
+  background: deepskyblue;
+  border-radius: 5px;
+  width: 25px;
+  font-size: 20px;
 }
 ```
 
@@ -124,7 +125,7 @@ export default {
 
 ```html
 <van-rolling-text
-  ref="rollTextEl"
+  ref="rollingTextRef"
   :start-num="0"
   :target-num="54321"
   :duration="2"
@@ -143,14 +144,14 @@ import { ref } from 'vue';
 
 export default {
   setup() {
-    const rollTextEl = ref(null);
+    const rollingTextRef = ref(null);
     const start = () => {
-      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<RollingTextInstance>();
+
+rollingTextRef.value?.start();
 ```
 
 ## 主题定制

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<RollingTextExpose>({
       start,
       reset,
     });

packages/vant/src/rolling-text/demo/index.vue

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import VanRollingText from '..';
+import VanRollingText, { type RollingTextInstance } from '..';
 import Button from '../../button';
 import { ref } from 'vue';
 import { useTranslate } from '../../../docs/site';
@@ -20,16 +20,16 @@ const t = useTranslate({
     reset: '重置',
   },
   'en-US': {
-    direction: 'Set Roll Direction',
-    stopOrder: 'Set StopOrder',
-    rollDown: 'rollDown',
-    rollUp: 'rollUp',
-    stopFrom: 'right-side stop first',
+    direction: 'Set Rolling Direction',
+    stopOrder: 'Set Stop Order',
+    rollDown: 'Roll Down',
+    rollUp: 'Roll Up',
+    stopFrom: 'Right Side Stop First',
     manualControl: 'Manual Control',
     customStyle: 'Custom Style',
-    noNumberType: 'Roll non-number type text',
+    noNumberType: 'Roll Non-numeric Text',
     start: 'Start',
-    rest: 'Reset',
+    reset: 'Reset',
   },
 });
 
@@ -49,12 +49,12 @@ const textArray = ref([
   'ggggg',
 ]);
 
-const rollingTextEl = ref(null);
+const rollingTextRef = ref<RollingTextInstance>();
 const start = () => {
-  rollingTextEl.value.start();
+  rollingTextRef.value?.start();
 };
 const reset = () => {
-  rollingTextEl.value.reset();
+  rollingTextRef.value?.reset();
 };
 </script>
 
@@ -131,7 +131,7 @@ const reset = () => {
   <demo-block :title="t('customStyle')">
     <div>
       <VanRollingText
-        class="my-rolling-te11xt"
+        class="my-rolling-text"
         :start-num="12345"
         :target-num="54321"
         :duration="2"
@@ -145,8 +145,8 @@ const reset = () => {
   <demo-block :title="t('manualControl')">
     <div>
       <VanRollingText
-        class="my-rolling-te11xt"
-        ref="rollingTextEl"
+        class="my-rolling-text"
+        ref="rollingTextRef"
         :start-num="0"
         :target-num="54321"
         :duration="2"
@@ -166,15 +166,18 @@ 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;

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 {

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
+>;