mirror of
https://github.com/XiaoDaiGua-Ray/ray-template.git
synced 2026-11-20 02:03:35 +08:00
Hooks 示例与约定
共享 Hook 从 @/hooks 导出。内部调用优先按职责导入:template 依赖模板运行时,components 与组件契约配套,web 处理窗口、日期、截图和打印等能力。旧的 web/useI18n、web/useVueRouter、web/usePagination 入口继续转发。页面使用 Vue 3 Composition API + TSX;每个演示包含实际交互、响应式结果和可展开复制的用法代码。
| 分包 | Hook | 示例页面与操作 | 回归测试 |
|---|---|---|---|
| template | useTheme |
/template-hooks:明暗、切换、跟随系统 |
useTheme |
| template | useSpinning |
/template-hooks:加载动画、重新挂载页面 |
useSpinning |
| template | useMaximize |
/template-hooks:内容最大化、共享退出按钮、Esc |
useMaximize |
| template | useBadge |
/template-hooks:菜单标记文本、图标与显隐 |
useBadge |
| template | useWatermark |
/template-hooks:文本、显示、隐藏与切换 |
useWatermark |
| template | useAppNavigation |
/template-hooks:完整路径、索引、嵌套菜单与 query |
useAppNavigation |
| template | useAppRoot |
/template-hooks:读取首页、设置本页与恢复仪表盘 |
useAppRoot |
| template | useSiderBar |
/template-hooks:按路径关闭标签与左右/其他/全部标签 |
useSiderBar |
| template | useContentScroll |
/template-hooks:内容滚动到顶部或指定坐标 |
useLayoutScroll |
| template | useSiderScroll |
/template-hooks:侧栏滚动到顶部或指定坐标 |
useLayoutScroll |
| web | useDevice |
/web-hooks:随窗口尺寸更新断点判断 |
useDevice |
| components | usePagination |
/web-hooks:实际分页数据、页码、每页条数与重置 |
usePagination |
| web | useDayjs |
/web-hooks:日期格式化、天数差、开区间和日界限 |
useDayjs |
| template | useI18n |
/web-hooks:命名空间、完整键和语言切换 |
useI18n |
| template | useVueRouter |
/web-hooks:当前路由、查询参数与页面导航 |
useVueRouter |
| web | useElementFullscreen |
/web-hooks:指定元素 CSS 全屏与恢复 |
useElementFullscreen |
| web | useDomToImage |
/web-hooks:PNG 生成、预览和失败提示 |
useDomToImage |
| web | usePrint |
/web-hooks:元素打印预览 |
usePrint |
| components | useContextmenuCoordinate |
/web-hooks:右键坐标、选择、外部关闭和停止监听;原 /context-menu 页面也保留 |
useContextmenuCoordinate |
生命周期与状态
- 组合式函数在
setup或有效 effect scope 内创建,DOM 操作由用户事件或挂载后的回调触发。事件、订阅、动画帧随作用域清理。 - 全局 UI 状态由 Pinia
runtime管理,通过useRuntimeGetters/useRuntimeActions访问,不写入持久化缓存。 useSpinning().reload(wait)会卸载页面,恢复计时器由 runtime Store 持有;多个调用以最后一次刷新为准。- 两个滚动 Hook 可以在 setup 阶段创建,调用时才读取布局实例。无侧栏或未挂载时安全忽略。
useMaximize操作布局内容,多个调用方共享状态;useElementFullscreen操作任意单个元素,其状态属于当前实例。二者均不调用浏览器 Fullscreen API。navigationTo的索引从 0 开始;负数、小数、非有限数和越界索引不会导航。完整 URL 支持动态参数、query 和 hash;额外 query 参数可覆盖 URL 中的同名参数。成功调用返回 Router 导航 Promise。useDomToImage的返回类型跟随默认格式或本次create(format);失败通过 Error 拒绝,finally在目标缺失时也会执行,此时参数可能为空。created回调也会接收到运行时覆盖格式的结果,因此其参数为所有实际输出类型的联合,需先判断类型。useI18n('hooks').t('code')和.t('hooks.code')指向同一个翻译键。切换应用语言使用useSettingActions().updateLocale,保持日期与组件库同步。- 国际化实例在开发热更新期间复用;初始化前创建的翻译方法会在调用时读取当前实例,不会永久停留在返回原始键的回退函数上。
usePagination重置时使用首个 pageSizes 选项的数值,兼容 Naive UI 的对象选项。调用setCallback()可移除默认回调。usePrint在调用时解包目标。DOM 默认以 HTML 打印;Blob 图片与二进制 PDF 会先转换,调用方可以等待返回的 Promise。
截图和打印依赖实际浏览器。Happy DOM 测试验证状态与异常处理,不能替代原生打印界面或实际纸张输出验收。