From 16db9c3e923d807b767cdd01e8bd786efe1c6a32 Mon Sep 17 00:00:00 2001 From: Joost Kersjes Date: Mon, 27 Jan 2025 20:49:51 +0100 Subject: [PATCH 1/2] docs: add advanced offsets content for scrollBehavoir --- .../docs/guide/advanced/scroll-behavior.md | 32 +++++++++++++++++- .../docs/zh/guide/advanced/scroll-behavior.md | 33 ++++++++++++++++++- 2 files changed, 63 insertions(+), 2 deletions(-) diff --git a/packages/docs/guide/advanced/scroll-behavior.md b/packages/docs/guide/advanced/scroll-behavior.md index b4f766409..7110f1312 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,33 @@ 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 + +Depending on the layout of the page, for example if there is a fixed-positioned navbar, an offset might be needed to make sure the target element is not obscured by other content. + +When a static offset value doesn't quite do the trick, one might reach for CSS to create an offset when scrolling to an element, only to discover that this doesn't work. For reference, the following styles can result in such edge cases: + +- `scroll-margin` or `scroll-padding` values +- `::before` and `::after` pseudo elements + +In these scenarios, the offset needs to be manually computed. One simple solution is to leverage CSS with `getComputedStyle()`. This allows each element to define its own offset value with all the desired flexibility. Here is 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 f0d77b19a..b653278c1 100644 --- a/packages/docs/zh/guide/advanced/scroll-behavior.md +++ b/packages/docs/zh/guide/advanced/scroll-behavior.md @@ -1,4 +1,5 @@ # 滚动行为 + Date: Fri, 25 Apr 2025 14:54:20 +0200 Subject: [PATCH 2/2] chore: reword --- packages/docs/guide/advanced/scroll-behavior.md | 10 +++------- packages/docs/zh/guide/advanced/scroll-behavior.md | 12 ++++-------- 2 files changed, 7 insertions(+), 15 deletions(-) diff --git a/packages/docs/guide/advanced/scroll-behavior.md b/packages/docs/guide/advanced/scroll-behavior.md index 7110f1312..2bc2b2608 100644 --- a/packages/docs/guide/advanced/scroll-behavior.md +++ b/packages/docs/guide/advanced/scroll-behavior.md @@ -116,14 +116,10 @@ It's possible to hook this up with events from a page-level transition component ## Advanced offsets -Depending on the layout of the page, for example if there is a fixed-positioned navbar, an offset might be needed to make sure the target element is not obscured by other content. +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. -When a static offset value doesn't quite do the trick, one might reach for CSS to create an offset when scrolling to an element, only to discover that this doesn't work. For reference, the following styles can result in such edge cases: - -- `scroll-margin` or `scroll-padding` values -- `::before` and `::after` pseudo elements - -In these scenarios, the offset needs to be manually computed. One simple solution is to leverage CSS with `getComputedStyle()`. This allows each element to define its own offset value with all the desired flexibility. Here is an example: +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({ diff --git a/packages/docs/zh/guide/advanced/scroll-behavior.md b/packages/docs/zh/guide/advanced/scroll-behavior.md index b653278c1..86a3d4452 100644 --- a/packages/docs/zh/guide/advanced/scroll-behavior.md +++ b/packages/docs/zh/guide/advanced/scroll-behavior.md @@ -21,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) 位置对象: @@ -116,14 +116,10 @@ const router = createRouter({ ## 高级偏移量 -根据页面的布局，比如如果有一个固定定位的导航栏，可能需要一个偏移量，确保目标元素不会被其他内容遮挡。 +如果你的页面中有固定的导航栏或类似的元素，你可能需要设置偏移量，以确保目标元素不会被其他内容遮挡。 +使用静态偏移值并不总是有效。你可以尝试一些基于 CSS 的解决方案，比如使用 `scroll-margin` 或 `scroll-padding` 添加偏移，或者使用 `::before` 和 `::after` 伪元素。然而，这些方法有时会导致意想不到的行为。 -当一个静态的偏移值无法满足需求时，可能会尝试使用 CSS 来创建滚动到元素时的偏移量，但这往往不起作用。以下样式可能会导致这种边界情况： - -- `scroll-margin` 或 `scroll-padding` 值 -- `::before` 和 `::after` 伪元素 - -在这些情况下，需要手动计算偏移量。一个简单的解决方案是利用 getComputedStyle() 来计算偏移量。这允许每个元素根据其自身的需求定义偏移值，并提供所需的灵活性。以下是一个示例： +在这种情况下，更好的做法是手动计算偏移量。一种简单的方法是结合 CSS 和 JavaScript 的 `getComputedStyle()`。这样每个元素都可以动态定义自己的偏移量。以下是一个示例： ```js const router = createRouter({