From 56b5cbb6de8f26228cbeb23b5f77f41da3920430 Mon Sep 17 00:00:00 2001
From: Joost Kersjes <joostkersjes@live.nl>
Date: Fri, 25 Apr 2025 14:54:29 +0200
Subject: [PATCH] docs: add advanced offsets content for scrollBehavoir (#2448)

Co-authored-by: Eduardo San Martin Morote <posva13@gmail.com>
---
 .../docs/guide/advanced/scroll-behavior.md    | 28 ++++++++++++++++-
 .../docs/zh/guide/advanced/scroll-behavior.md | 31 +++++++++++++++++--
 2 files changed, 56 insertions(+), 3 deletions(-)

diff --git a/packages/docs/guide/advanced/scroll-behavior.md b/packages/docs/guide/advanced/scroll-behavior.md
index b4f76640..2bc2b260 100644
--- a/packages/docs/guide/advanced/scroll-behavior.md
+++ b/packages/docs/guide/advanced/scroll-behavior.md
@@ -92,7 +92,7 @@ const router = createRouter({
         behavior: 'smooth',
       }
     }
-  }
+  },
 })
 ```
 
@@ -113,3 +113,29 @@ const router = createRouter({
 ```
 
 It's possible to hook this up with events from a page-level transition component to make the scroll behavior play nicely with your page transitions, but due to the possible variance and complexity in use cases, we simply provide this primitive to enable specific userland implementations.
+
+## Advanced offsets
+
+If your page has a fixed navbar or similar elements, you might need an offset to ensure the target element isn't hidden behind other content.
+Using a static offset value may not always work. You might try CSS-based solutions, like adding offsets with `scroll-margin` or `scroll-padding`, or using `::before` and `::after` pseudo-elements. However, these approaches can lead to unexpected behavior.
+
+In such cases, it's better to calculate the offset manually. A simple way to do this is by combining CSS with JavaScript's `getComputedStyle()`. This lets each element define its own offset dynamically. Here's an example:
+
+```js
+const router = createRouter({
+  scrollBehavior(to, from, savedPosition) {
+    const mainElement = document.querySelector('#main')
+    if (mainElement) {
+      const marginTop = parseFloat(
+        getComputedStyle(mainElement).scrollMarginTop
+      )
+      return {
+        el: mainElement,
+        top: marginTop,
+      }
+    } else {
+      return { top: 0 }
+    }
+  },
+})
+```
diff --git a/packages/docs/zh/guide/advanced/scroll-behavior.md b/packages/docs/zh/guide/advanced/scroll-behavior.md
index f0d77b19..86a3d445 100644
--- a/packages/docs/zh/guide/advanced/scroll-behavior.md
+++ b/packages/docs/zh/guide/advanced/scroll-behavior.md
@@ -1,4 +1,5 @@
 # 滚动行为
+
 <VueSchoolLink
   href="https://vueschool.io/lessons/scroll-behavior"
   title="Learn how to customize scroll behavior"
@@ -20,7 +21,7 @@ const router = createRouter({
 })
 ```
 
-`scrollBehavior` 函数接收 `to`和` from` 路由对象，如 [Navigation Guards](./navigation-guards.md)。第三个参数 `savedPosition`，只有当这是一个 `popstate` 导航时才可用（由浏览器的后退/前进按钮触发）。
+`scrollBehavior` 函数接收 `to`和`from` 路由对象，如 [Navigation Guards](./navigation-guards.md)。第三个参数 `savedPosition`，只有当这是一个 `popstate` 导航时才可用（由浏览器的后退/前进按钮触发）。
 
 该函数可以返回一个 [`ScrollToOptions`](https://developer.mozilla.org/en-US/docs/Web/API/ScrollToOptions) 位置对象:
 
@@ -91,7 +92,7 @@ const router = createRouter({
         behavior: 'smooth',
       }
     }
-  }
+  },
 })
 ```
 
@@ -112,3 +113,29 @@ const router = createRouter({
 ```
 
 我们可以将其与页面级过渡组件的事件挂钩，以使滚动行为与你的页面过渡很好地结合起来，但由于使用场景可能存在的差异和复杂性，我们只是提供了这个基础来实现特定的用户场景。
+
+## 高级偏移量
+
+如果你的页面中有固定的导航栏或类似的元素，你可能需要设置偏移量，以确保目标元素不会被其他内容遮挡。
+使用静态偏移值并不总是有效。你可以尝试一些基于 CSS 的解决方案，比如使用 `scroll-margin` 或 `scroll-padding` 添加偏移，或者使用 `::before` 和 `::after` 伪元素。然而，这些方法有时会导致意想不到的行为。
+
+在这种情况下，更好的做法是手动计算偏移量。一种简单的方法是结合 CSS 和 JavaScript 的 `getComputedStyle()`。这样每个元素都可以动态定义自己的偏移量。以下是一个示例：
+
+```js
+const router = createRouter({
+  scrollBehavior(to, from, savedPosition) {
+    const mainElement = document.querySelector('#main')
+    if (mainElement) {
+      const marginTop = parseFloat(
+        getComputedStyle(mainElement).scrollMarginTop
+      )
+      return {
+        el: mainElement,
+        top: marginTop,
+      }
+    } else {
+      return { top: 0 }
+    }
+  },
+})
+```
-- 
2.47.2