mirror of
https://github.com/XiaoDaiGua-Ray/ray-template.git
synced 2026-11-17 16:13:36 +08:00
80 lines
3.9 KiB
Markdown
80 lines
3.9 KiB
Markdown
# 布局与滚动 Hooks
|
||
|
||
<script setup>
|
||
import AdminExample from '../../examples/AdminExample.vue'
|
||
</script>
|
||
|
||
本页 API 操作模板默认布局。替换布局内容或侧栏前,先确认[插槽和布局实例](../../guide/layout)仍在预期位置。
|
||
|
||
## 交互示例
|
||
|
||
<AdminExample path="/template-hooks" title="内容加载、最大化和滚动" focus="useMaximize,useSpinning,useContentScroll,useSiderScroll" layout />
|
||
|
||
::: details 查看示例源码
|
||
<<< @/../admin/src/views/demo/template-hooks/index.tsx
|
||
:::
|
||
|
||
## useMaximize
|
||
|
||
`useMaximize(defaults?)` 返回 `isLayoutContentMaximized`(`isFullscreen` 是同一状态的别名)、`maximize(full, options?)`、`toggleFullscreen()`。页面、标签菜单和退出按钮共享同一个 Pinia 状态。需要单独放大一个 DOM 元素时,使用 [useElementFullscreen](./browser#useelementfullscreen)。
|
||
|
||
每次调用的 `options` 覆盖 `defaults`。支持 `zIndex`(默认 999)、`backgroundColor`、`transition`、`scrollToOptions: { left?, top?, behavior? }`,以及 `beforeEnter`、`enter`、`beforeExit`、`exit`。前置回调先执行,完成回调在下一次 Vue 更新后执行,并非 CSS 动画完成事件。进入时可以调整滚动位置。连续切换只执行最新状态的完成回调;切到当前状态时直接返回。
|
||
|
||
```ts
|
||
import { useMaximize } from '@/hooks'
|
||
|
||
export function useReportLayout() {
|
||
const { isLayoutContentMaximized, maximize } = useMaximize()
|
||
const expand = () => maximize(true, { scrollToOptions: { top: 0 } })
|
||
return { expand, collapse: () => maximize(false), isLayoutContentMaximized }
|
||
}
|
||
```
|
||
|
||
## useSpinning
|
||
|
||
| 返回方法 | 用途 |
|
||
| ---------------------------- | ----------------------------------------------- |
|
||
| `openSpin()` / `closeSpin()` | 开关布局内容区的加载动画,不改变应用全局 Spin。 |
|
||
| `reload(wait?)` | 卸载当前内容后重新挂载,缺省等待 800ms。 |
|
||
|
||
内容区用细线进度与普通文本提示呈现加载;`openSpin` 持续超过 120ms 才显示,短操作不会闪烁,`reload` 则立即显示。只想表示请求未完成时调用 `openSpin`,并在 `finally` 用 `closeSpin` 关闭。`reload` 会丢失当前页面未持久化的本地状态;多次重载时,Runtime Store 只保留最后一次恢复计时。
|
||
|
||
```ts
|
||
import { useSpinning } from '@/hooks'
|
||
|
||
export function useLoadWithSpinner() {
|
||
const { openSpin, closeSpin } = useSpinning()
|
||
return async <T>(load: () => Promise<T>) => {
|
||
openSpin()
|
||
try {
|
||
return await load()
|
||
} finally {
|
||
closeSpin()
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## useContentScroll
|
||
|
||
`useContentScroll()` 直接返回 `scrollTo` 函数。可传 `(x, y?)` 或 `{ top, left, behavior }`,例如 `scrollContent({ top: 0, behavior: 'smooth' })`。调用时读取 `LAYOUT_CONTENT_REF`,所以可以在 `setup` 创建,在事件触发时使用。没有挂载布局实例时不执行。
|
||
|
||
## useSiderScroll
|
||
|
||
`useSiderScroll()` 返回同签名的函数,操作 `LAYOUT_SIDER_REF`。顶部模式、未挂载或侧栏已卸载时安全忽略。它滚动侧栏容器,不改变菜单选中项。
|
||
|
||
```ts
|
||
import { useContentScroll, useSiderScroll } from '@/hooks'
|
||
|
||
export function useScrollShortcuts() {
|
||
const scrollContent = useContentScroll()
|
||
const scrollSider = useSiderScroll()
|
||
return {
|
||
toTop: () => scrollContent(0, 0),
|
||
toMenuTop: () => scrollSider(0, 0),
|
||
}
|
||
}
|
||
```
|
||
|
||
源码:[useMaximize](https://github.com/XiaoDaiGua-Ray/ray-template/blob/main/apps/admin/src/hooks/template/useMaximize.ts) · [useSpinning](https://github.com/XiaoDaiGua-Ray/ray-template/blob/main/apps/admin/src/hooks/template/useSpinning.ts) · [useContentScroll](https://github.com/XiaoDaiGua-Ray/ray-template/blob/main/apps/admin/src/hooks/template/useContentScroll.ts) · [useSiderScroll](https://github.com/XiaoDaiGua-Ray/ray-template/blob/main/apps/admin/src/hooks/template/useSiderScroll.ts)
|