feat(tree): adds multiple scrollTo configurations (#5198)

Co-authored-by: 07akioni <07akioni2@gmail.com>

CHANGELOG.en-US.md

@@ -32,6 +32,7 @@
 - `n-input-number` adds `input-props` prop, closes [#5450](https://github.com/tusen-ai/naive-ui/issues/5450).
 - Update `ruRU` locale.
 - `n-drawer` adds `content-class` `body-class` `body-content-class` `footer-class` `header-class` prop.
+- `n-tree` adds multiple `scrollTo` configurations.
 
 ## 2.36.0
 

CHANGELOG.zh-CN.md

@@ -33,6 +33,7 @@
 - `n-input-number` adds `input-props` prop, closes [#5450](https://github.com/tusen-ai/naive-ui/issues/5450)
 - 更新 ruRU locale
 - `n-drawer` 新增 `content-class` `body-class` `body-content-class` `footer-class` `header-class` 属性
+- `n-tree` 新增多种 `scrollTo` 配置
 
 ## 2.36.0
 

src/tree/demos/enUS/index.demo-entry.md

@@ -101,11 +101,40 @@ checkbox-placement.vue
 
 ## Methods
 
+#### ScrollTo Type
+
+```ts
+interface ScrollTo {
+  (x: number, y: number): void
+  (
+    options: {
+      left?: number
+      top?: number
+    } & CommonScrollToOptions
+  ): void
+  (
+    options: {
+      index: number
+    } & CommonScrollToOptions
+  ): void
+  (
+    options: {
+      key: string | number
+    } & CommonScrollToOptions
+  ): void
+  (
+    options: {
+      position: 'top' | 'bottom'
+    } & CommonScrollToOptions
+  ): void
+}
+```
+
 ### Tree Methods
 
 | Name | Paramaters | Description | Version |
 | --- | --- | --- | --- |
-| scrollTo | `(options: { key: string \| number })` | Scroll to some node in virtual scroll mode. | 2.32.2 |
+| scrollTo | `ScrollTo` | Scroll to some node in virtual scroll mode. | 2.32.2 |
 | getCheckedData | `() => { keys: Array<string \| number>, options: Array<TreeOption \| null> }` | Get checked data. | 2.34.1 |
 | getIndeterminateData | `() => { keys: Array<string \| number>, options: Array<TreeOption \| null> }` | Get indeterminate data. | 2.34.1 |
 

src/tree/demos/enUS/virtual.demo.vue

@@ -6,9 +6,20 @@ Set `virtual-scroll` to use virtual scroll. Note that you should set the height
 
 <template>
   <n-space vertical>
-    <n-button @click="handleClick">
-      Scroll
-    </n-button>
+    <n-space>
+      <n-button @click="handleScrollToKey">
+        Scroll
+      </n-button>
+      <n-button @click="handleScrollToPosition">
+        Scroll to position
+      </n-button>
+      <n-button @click="handleScrollToIndex">
+        Scroll to index
+      </n-button>
+      <n-button @click="handleScrollToDistance">
+        Scroll to distance
+      </n-button>
+    </n-space>
     <n-tree
       ref="treeInstRef"
       block-line
@@ -51,8 +62,17 @@ export default defineComponent({
     return {
       treeInstRef,
       data: createData(),
-      handleClick: () => {
+      handleScrollToKey: () => {
         treeInstRef.value?.scrollTo({ key: '45362710' })
+      },
+      handleScrollToPosition: () => {
+        treeInstRef.value?.scrollTo({ position: 'bottom' })
+      },
+      handleScrollToIndex: () => {
+        treeInstRef.value?.scrollTo({ index: 100 })
+      },
+      handleScrollToDistance: () => {
+        treeInstRef.value?.scrollTo({ top: 400 })
       }
     }
   }

src/tree/demos/zhCN/index.demo-entry.md

@@ -109,10 +109,40 @@ expand-debug.vue
 
 | 名称 | 参数 | 说明 | 版本 |
 | --- | --- | --- | --- |
-| scrollTo | `(options: { key: string \| number })` | 在虚拟滚动模式下滚动到某个节点 | 2.32.2 |
+| scrollTo | `ScrollTo` | 在虚拟滚动模式下滚动到某个节点 | 2.32.2 |
 | getCheckedData | `() => { keys: Array<string \| number>, options: Array<TreeOption \| null> }` | 获取选中的数据 | 2.34.1 |
 | getIndeterminateData | `() => { keys: Array<string \| number>, options: Array<TreeOption \| null> }` | 获取半选的数据 | 2.34.1 |
 
+
+#### ScrollTo Type
+
+```ts
+interface ScrollTo {
+  (x: number, y: number): void
+  (
+    options: {
+      left?: number
+      top?: number
+    } & CommonScrollToOptions
+  ): void
+  (
+    options: {
+      index: number
+    } & CommonScrollToOptions
+  ): void
+  (
+    options: {
+      key: string | number
+    } & CommonScrollToOptions
+  ): void
+  (
+    options: {
+      position: 'top' | 'bottom'
+    } & CommonScrollToOptions
+  ): void
+}
+```
+
 ### Others
 
 1. `treeGetClickTarget: (e: MouseEvent) => ('checkbox' | 'switcher' | 'node')`：获取点击位置，可以用于 `nodeProps.onClick`

src/tree/demos/zhCN/virtual.demo.vue

@@ -6,9 +6,20 @@
 
 <template>
   <n-space vertical>
-    <n-button @click="handleClick">
-      滚动
-    </n-button>
+    <n-space>
+      <n-button @click="handleScrollToKey">
+        滚动
+      </n-button>
+      <n-button @click="handleScrollToPosition">
+        滚动到指定位置
+      </n-button>
+      <n-button @click="handleScrollToIndex">
+        滚动到指定Index
+      </n-button>
+      <n-button @click="handleScrollToDistance">
+        滚动到指定距离
+      </n-button>
+    </n-space>
     <n-tree
       ref="treeInstRef"
       block-line
@@ -51,8 +62,17 @@ export default defineComponent({
     return {
       treeInstRef,
       data: createData(),
-      handleClick: () => {
+      handleScrollToKey: () => {
         treeInstRef.value?.scrollTo({ key: '45362710' })
+      },
+      handleScrollToPosition: () => {
+        treeInstRef.value?.scrollTo({ position: 'bottom' })
+      },
+      handleScrollToIndex: () => {
+        treeInstRef.value?.scrollTo({ index: 100 })
+      },
+      handleScrollToDistance: () => {
+        treeInstRef.value?.scrollTo({ top: 400 })
       }
     }
   }

src/tree/src/Tree.tsx

@@ -72,6 +72,7 @@ import MotionWrapper from './MotionWrapper'
 import { defaultAllowDrop } from './dnd'
 import style from './styles/index.cssr'
 import { type ScrollbarProps } from '../../scrollbar/src/Scrollbar'
+import { type VScrollToOptions } from 'vueuc/lib/virtual-list/src/type'
 
 export function createTreeMateOptions<T> (
   keyField: string,
@@ -1543,8 +1544,12 @@ export default defineComponent({
       handleSelect,
       handleCheck
     })
-    function scrollTo (options: { key: Key }): void {
-      virtualListInstRef.value?.scrollTo(options)
+    function scrollTo (options: VScrollToOptions | number, y?: number): void {
+      if (typeof options === 'number') {
+        virtualListInstRef.value?.scrollTo(options, y ?? 0)
+      } else {
+        virtualListInstRef.value?.scrollTo(options)
+      }
     }
     const exposedMethods: InternalTreeInst & TreeInst = {
       handleKeydown,

src/tree/src/interface.ts

@@ -3,6 +3,7 @@ import { type HTMLAttributes, type Ref, type VNodeChild } from 'vue'
 import type { MergedTheme } from '../../_mixins'
 import { createInjectionKey } from '../../_utils'
 import type { TreeTheme } from '../styles'
+import type { ScrollTo } from 'vueuc/lib/virtual-list/src/VirtualList'
 
 export type Key = string | number
 
@@ -150,7 +151,7 @@ export interface InternalTreeInst {
 }
 
 export interface TreeInst {
-  scrollTo: (options: { key: Key }) => void
+  scrollTo: ScrollTo
   getCheckedData: () => { keys: Key[], options: Array<TreeOption | null> }
   getIndeterminateData: () => { keys: Key[], options: Array<TreeOption | null> }
 }