feat(BackTop): add immediate prop (#11515)

* feat(BackTop): add immediate prop

* chore: update

packages/vant/src/back-top/BackTop.tsx

@@ -35,6 +35,7 @@ export const backTopProps = {
   bottom: numericProp,
   target: [String, Object] as PropType<TeleportProps['to']>,
   offset: makeNumericProp(200),
+  immediate: Boolean,
   teleport: {
     type: [String, Object] as PropType<TeleportProps['to']>,
     default: 'body',
@@ -66,7 +67,7 @@ export default defineComponent({
       emit('click', event);
       scrollParent.value?.scrollTo({
         top: 0,
-        behavior: 'smooth',
+        behavior: props.immediate ? 'auto' : 'smooth',
       });
     };
 

packages/vant/src/back-top/README.md

@@ -23,7 +23,9 @@ app.use(BackTop);
 Please scroll the demo page to display the back top button.
 
 ```html
-<van-cell v-for="item in list" :key="item" :title="item" /> <van-back-top />
+<van-cell v-for="item in list" :key="item" :title="item" />
+
+<van-back-top />
 ```
 
 ```js
@@ -104,6 +106,14 @@ export default {
 };
 ```
 
+### Immediate Scroll
+
+Add `immediate` prop to scroll to top immediately.
+
+```html
+<van-back-top immediate />
+```
+
 ## API
 
 ### Props
@@ -115,6 +125,7 @@ export default {
 | bottom | Bottom distance of the page, the default unit is px | _number \| string_ | `40` |
 | offset | The component will not display until the scroll offset reaches this value | _number_ | `200` |
 | teleport | Specifies a target element where BackTop will be mounted | _string \| Element_ | `body` |
+| immediate `v4.0.9` | Whether to scroll to top immediately | _boolean_ | `false` |
 
 ### Events
 

packages/vant/src/back-top/README.zh-CN.md

@@ -23,7 +23,9 @@ app.use(BackTop);
 请滚动右侧的示例页面，当页面滚动 `200px` 时，右下角会出现返回顶部按钮。
 
 ```html
-<van-cell v-for="item in list" :key="item" :title="item" /> <van-back-top />
+<van-cell v-for="item in list" :key="item" :title="item" />
+
+<van-back-top />
 ```
 
 ```js
@@ -106,6 +108,14 @@ export default {
 };
 ```
 
+### 瞬间滚动
+
+当设置 `immediate` 属性后，页面滚动的过程不再有过渡效果，而是瞬间滚动到顶部。
+
+```html
+<van-back-top immediate />
+```
+
 ## API
 
 ### Props
@@ -117,6 +127,7 @@ export default {
 | bottom | 距离页面底部的距离，默认单位为 `px` | _number \| string_ | `40` |
 | offset | 滚动高度达到此参数值时才显示组件 | _number_ | `200` |
 | teleport | 指定挂载的节点，等同于 Teleport 组件的 [to 属性](https://v3.cn.vuejs.org/api/built-in-components.html#teleport) | _string \| Element_ | `body` |
+| immediate `v4.0.9` | 是否瞬间滚动到顶部 | _boolean_ | `false` |
 
 ### Events
 

packages/vant/src/back-top/demo/index.vue

@@ -11,12 +11,14 @@ const t = useTranslate({
     backTop: '返回顶部',
     customContent: '自定义内容',
     customPosition: '自定义位置',
+    immediateScroll: '瞬间滚动',
     setScrollTarget: '设置滚动目标',
   },
   'en-US': {
     backTop: 'Back Top',
     customContent: 'Custom Content',
     customPosition: 'Custom Position',
+    immediateScroll: 'Immediate Scroll',
     setScrollTarget: 'Set Scroll Target',
   },
 });
@@ -51,6 +53,11 @@ const targetEl = ref<HTMLElement>();
         <van-back-top v-if="activeTab === 3" :target="targetEl" bottom="30vh" />
       </div>
     </van-tab>
+
+    <van-tab :title="t('immediateScroll')">
+      <van-cell v-for="item in list" :key="item" :title="item" />
+      <van-back-top v-if="activeTab === 4" immediate />
+    </van-tab>
   </van-tabs>
 </template>
 

packages/vant/src/back-top/test/__snapshots__/demo.spec.ts.snap

@@ -51,6 +51,17 @@ exports[`should render demo and match snapshot 1`] = `
           Set Scroll Target
         </span>
       </div>
+      <div id="van-tabs-4"
+           role="tab"
+           class="van-tab van-tab--line van-tab--grow"
+           tabindex="-1"
+           aria-selected="false"
+           aria-controls="van-tab"
+      >
+        <span class="van-tab__text">
+          Immediate Scroll
+        </span>
+      </div>
       <div class="van-tabs__line"
            style="transform: translateX(50px) translateX(-50%);"
       >
@@ -440,6 +451,14 @@ exports[`should render demo and match snapshot 1`] = `
          style="display: none;"
     >
     </div>
+    <div id="van-tab"
+         role="tabpanel"
+         class="van-tab__panel"
+         tabindex="-1"
+         aria-labelledby="van-tabs-4"
+         style="display: none;"
+    >
+    </div>
   </div>
 </div>
 `;