Merge pull request #147 from LostElkByte/main

feat: add scroll-cache demo

Author: CharleeWa

.gitignore

@@ -23,3 +23,4 @@ stats.html
 
 # Misc
 .DS_Store
+.history

postcss.config.ts

@@ -8,8 +8,11 @@ export default {
       appSelector: '#app',
       viewportWidth: 375,
       maxDisplayWidth: 600,
-      appContainingBlock: 'auto',
       border: true,
+      rootContainingBlockSelectorList: [
+        'van-tabbar',
+        'van-popup',
+      ],
     },
   },
 }

src/locales/en-US.json

@@ -10,6 +10,7 @@
     "persistPiniaState": "🍍 Persistent Pinia state",
     "unocssExample": "🎨 Unocss example",
     "keepAlive": "🧡 KeepAlive Demo",
+    "scrollCache": "📜 Scroll Cache Demo",
     "login": "🔒 Login",
     "register": "Register",
     "settings": "Settings",
@@ -43,6 +44,9 @@
   "keepAlive": {
     "label": "The current component will be cached"
   },
+  "scrollCache": {
+    "listItem": "Slide freely. When you get back, the roll position will still be there"
+  },
   "login": {
     "login": "Sign In",
     "logout": "Sign Out",

src/locales/zh-CN.json

@@ -10,6 +10,7 @@
     "404Demo": "🙅 404页 演示",
     "unocssExample": "🎨 Unocss 示例",
     "keepAlive": "🧡 KeepAlive 演示",
+    "scrollCache": "📜 滚动缓存 演示",
     "login": "🔒 用户登录",
     "register": "用户注册",
     "settings": "设置",
@@ -43,6 +44,9 @@
   "keepAlive": {
     "label": "当前组件将会被缓存"
   },
+  "scrollCache": {
+    "listItem": "随便滑滑,离开再回来时位置会保留不变哦"
+  },
   "login": {
     "login": "登录",
     "logout": "退出",

src/pages/index.vue

@@ -10,6 +10,7 @@ const menuItems = computed(() => ([
   { title: t('menus.unocssExample'), route: 'unocss' },
   { title: t('menus.persistPiniaState'), route: 'counter' },
   { title: t('menus.keepAlive'), route: 'keepalive' },
+  { title: t('menus.scrollCache'), route: 'scroll-cache' },
   { title: t('menus.404Demo'), route: 'unknown' },
 ]))
 

src/pages/scroll-cache/README.md

@@ -0,0 +1,79 @@
+# Page Scroll Position Save and Restore Guide
+
+If you want to save the current scroll position when leaving a page and restore it upon return, you can follow the approach outlined below.
+
+## Basic Approach
+
+1. **Cache the Component**:
+   Set `keepAlive` to `true` to cache the component.
+
+2. **Save Scroll Position**:
+   Use the `onBeforeRouteLeave` hook to save the current scroll position when leaving the page.
+
+3. **Restore Scroll Position**:
+   Use the `onActivated` hook to restore the last saved scroll position when the page is activated.
+
+## Example Code
+
+```js
+// Define a ref to store the scroll position
+const scrollTop = ref(0)
+
+// When a component with keepAlive set to true is activated, scroll to the saved position
+onActivated(() => {
+  window.scrollTo(0, scrollTop.value)
+})
+
+// Before leaving the route, save the current scroll position
+onBeforeRouteLeave(() => {
+  scrollTop.value
+    = window.scrollY
+      || document.documentElement.scrollTop
+      || document.body.scrollTop
+})
+```
+
+# Handling a Specific Scroll Container
+
+If you need to save and restore the scroll position for a specific element (instead of the entire window), follow these steps:
+
+## 1. Add a ref in the Template
+
+In your template, add a `ref` attribute to the scroll container element. For example:
+
+```html
+<div ref="scrollContainer" class="...">...</div>
+
+```
+
+## 2. In the setup Function
+
+Use a ref to obtain the element's reference:
+
+```js
+const scrollContainer = ref(null)
+```
+
+## 3. In the onBeforeRouteLeave Hook
+
+Save the scroll container's scroll position:
+
+```js
+onBeforeRouteLeave(() => {
+  if (scrollContainer.value) {
+    scrollTop.value = scrollContainer.value.scrollTop
+  }
+})
+```
+
+## 3. In the onActivated Hook
+
+Restore the scroll container's scroll position:
+
+```js
+onActivated(() => {
+  if (scrollContainer.value) {
+    scrollContainer.value.scrollTop = scrollTop.value
+  }
+})
+```

src/pages/scroll-cache/README.zh-CN.md

@@ -0,0 +1,80 @@
+# 页面滚动位置保存与恢复指南
+
+如果你希望在离开页面时保存当前的滚动位置，并在返回时恢复它，可以参考下面的实现思路：
+
+## 基本思路
+
+1. **缓存组件**：
+   设置 `keepAlive` 为 `true` 以缓存组件。
+
+2. **保存滚动位置**：
+   在页面离开时，使用 `onBeforeRouteLeave` 钩子保存当前滚动位置。
+
+3. **恢复滚动位置**：
+   在页面激活时，使用 `onActivated` 钩子恢复上次的滚动位置。
+
+## 示例代码
+
+```js
+// 定义一个 ref 用于存储滚动位置
+const scrollTop = ref(0)
+
+// 当 keepAlive 为 true 的组件被激活时，滚动到保存的位置
+onActivated(() => {
+  window.scrollTo(0, scrollTop.value)
+})
+
+// 在路由离开前，保存当前的滚动位置
+onBeforeRouteLeave(() => {
+  scrollTop.value
+    = window.scrollY
+      || document.documentElement.scrollTop
+      || document.body.scrollTop
+})
+```
+
+# 针对指定滚动容器的处理
+
+如果你需要对特定元素（而非整个窗口）进行滚动位置的保存和恢复，可按以下步骤操作：
+
+## 1. 在 Template 中添加 ref
+
+在模板中，给滚动容器元素添加 `ref` 属性。例如：
+
+```html
+<div ref="scrollContainer" class="...">...</div>
+```
+
+## 2. 在 setup 中：
+
+使用 ref 获取该元素的引用：
+
+```js
+const scrollContainer = ref(null)
+```
+
+## 3. 在 onBeforeRouteLeave 钩子中：
+
+保存滚动容器的滚动位置：
+
+```js
+onBeforeRouteLeave(() => {
+  if (scrollContainer.value) {
+    scrollTop.value = scrollContainer.value.scrollTop
+  }
+})
+```
+
+## 3. 在 onActivated 钩子中：
+
+恢复滚动容器的滚动位置：
+
+```js
+onActivated(() => {
+  if (scrollContainer.value) {
+    scrollContainer.value.scrollTop = scrollTop.value
+  }
+})
+```
+
+万事 OK 👌🏻

src/pages/scroll-cache/index.vue

@@ -0,0 +1,73 @@
+<script setup lang="ts">
+defineOptions({
+  name: 'ScrollCache',
+})
+
+const list = ref([])
+const loading = ref(false)
+const finished = ref(false)
+const { t } = useI18n()
+
+function onLoad() {
+  setTimeout(() => {
+    for (let i = 0; i < 10; i++) {
+      list.value.push(`${list.value.length + 1}`)
+    }
+
+    loading.value = false
+
+    if (list.value.length >= 40) {
+      finished.value = true
+    }
+  }, 1000)
+}
+
+const scrollTop = ref(0)
+
+onActivated(() => {
+  window.scrollTo(0, scrollTop.value)
+})
+
+onBeforeRouteLeave(() => {
+  scrollTop.value
+    = window.scrollY
+      || document.documentElement.scrollTop
+      || document.body.scrollTop
+})
+</script>
+
+<template>
+  <van-list
+    v-model:loading="loading"
+    :finished="finished"
+    finished-text="已经到底啦 ~"
+    loading-text="加载中..."
+    @load="onLoad"
+  >
+    <van-cell
+      v-for="(item, index) in list"
+      :key="index"
+      :border="false"
+      class="mb-8 rounded-12"
+    >
+      <template #title>
+        {{ t('scrollCache.listItem') }}
+      </template>
+
+      <template #value>
+        {{ item }}
+      </template>
+    </van-cell>
+  </van-list>
+</template>
+
+<route lang="json5">
+{
+  name: 'ScrollCache',
+  meta: {
+    title: '📜 ScrollCache',
+    i18n: 'menus.scrollCache',
+    keepAlive: true
+  },
+}
+</route>

src/types/components.d.ts

@@ -23,6 +23,7 @@ declare module 'vue' {
     VanForm: typeof import('vant/es')['Form']
     VanIcon: typeof import('vant/es')['Icon']
     VanImage: typeof import('vant/es')['Image']
+    VanList: typeof import('vant/es')['List']
     VanNavBar: typeof import('vant/es')['NavBar']
     VanPicker: typeof import('vant/es')['Picker']
     VanPopup: typeof import('vant/es')['Popup']

src/types/typed-router.d.ts

@@ -28,6 +28,7 @@ declare module 'vue-router/auto-routes' {
     'mock': RouteRecordInfo<'mock', '/mock', Record<never, never>, Record<never, never>>,
     'profile': RouteRecordInfo<'profile', '/profile', Record<never, never>, Record<never, never>>,
     'register': RouteRecordInfo<'register', '/register', Record<never, never>, Record<never, never>>,
+    'ScrollCache': RouteRecordInfo<'ScrollCache', '/scroll-cache', Record<never, never>, Record<never, never>>,
     'settings': RouteRecordInfo<'settings', '/settings', Record<never, never>, Record<never, never>>,
     'unocss': RouteRecordInfo<'unocss', '/unocss', Record<never, never>, Record<never, never>>,
   }