8.8 KiB

Hook examples and conventions

Shared hooks are exported through @/hooks. Internal callers should import by responsibility: template depends on the template runtime, components complements component contracts, and web handles windows, dates, screenshots, printing, and related capabilities. Legacy web/useI18n, web/useVueRouter, and web/usePagination entry points still re-export their implementations. Pages use Vue 3 Composition API + TSX. Each demo includes real interaction, reactive results, and expandable, copyable usage code.

Group Hook Example page and actions Regression
template useTheme /template-hooks: light/dark, toggle, follow system useTheme
template useSpinning /template-hooks: loading indicators and page remount useSpinning
template useMaximize /template-hooks: maximize content, shared exit button, Esc useMaximize
template useBadge /template-hooks: menu badge text, icons, and visibility useBadge
template useWatermark /template-hooks: text, show, hide, and toggle useWatermark
template useAppNavigation /template-hooks: full paths, indexes, nested menus, and query useAppNavigation
template useSiderBar /template-hooks: close tabs by path or close left/right/other/all tabs useSiderBar
template useContentScroll /template-hooks: scroll content to top or coordinates useLayoutScroll
template useSiderScroll /template-hooks: scroll sidebar to top or coordinates useLayoutScroll
web useDevice /web-hooks: update breakpoint checks with window size useDevice
components usePagination /web-hooks: paginated data, page, page size, and reset usePagination
web useDayjs /web-hooks: date formatting, day differences, open intervals, and day boundaries useDayjs
template useI18n /web-hooks: namespaces, full keys, and locale switching useI18n
template useVueRouter /web-hooks: current route, query parameters, and navigation useVueRouter
web useElementFullscreen /web-hooks: CSS fullscreen and restoration for a chosen element useElementFullscreen
web useDomToImage /web-hooks: PNG generation, preview, and failure messages useDomToImage
web usePrint /web-hooks: element print preview usePrint
components useContextmenuCoordinate /web-hooks: context-menu coordinates, selection, outside close, and listener removal; legacy /context-menu remains useContextmenuCoordinate

Lifecycle and state

  • useAppRoot is a deprecated compatibility accessor for stored preferences. It has no landing, tab protection, permission, or startup-validation effect and is no longer an interactive demo. Explicit navigation uses Router; closing the final/all business tabs opens the neutral /welcome workspace.

  • Create composables in setup or an active effect scope. Trigger DOM operations from user events or post-mount callbacks. Clean up events, subscriptions, and animation frames with the scope.

  • Pinia runtime owns global UI state, accessed through useRuntimeGetters / useRuntimeActions. It is not persisted.

  • useSpinning().reload(wait) unmounts the page. The runtime store owns the restoration timer; the latest refresh wins across repeated calls.

  • In the default layout, loading indicators stay centered in the visible content area, including long pages and maximized content. reload shows immediately; openSpin shows after lasting more than 120ms; closeSpin immediately closes manual loading indicators.

  • Both scroll hooks can be created during setup and read the layout instance only when invoked. Missing sidebars or unmounted instances are safely ignored.

  • useMaximize acts on layout content and shares state across callers. useElementFullscreen acts on one arbitrary element and owns per-instance state. Neither calls the browser Fullscreen API.

  • navigationTo indexes start at 0. Negative, fractional, non-finite, or out-of-range indexes do not navigate. Full URLs support dynamic parameters, query, and hash; additional query parameters override matching URL parameters. Successful calls return the Router navigation Promise.

  • useDomToImage return types follow the default format or the current create(format) call. Failures reject with Error. finally also runs when the target is missing, so its argument may be empty. The created callback receives results from runtime format overrides as well; its argument is a union of actual output types and must be narrowed first.

  • useI18n('hooks').t('code') and .t('hooks.code') address the same translation key. Switch application locales with useSettingActions().updateLocale to keep dates and component-library locales synchronized.

  • Development HMR reuses the internationalization instance. Translation methods created before initialization read the current instance at invocation rather than permanently retaining the fallback that returns raw keys.

  • usePagination resets to the first option in the current pagination.value.pageSizes and supports Naive UI object options. Default option arrays are isolated between instances. Calling setCallback() removes the default callback.

  • useDomToImage loads the rendering library on the first create call; import failures use the same error and cleanup callbacks as renderer failures.

  • A disposed useElementFullscreen instance cannot enter again; create a fresh instance in a live scope when a target is remounted.

  • usePrint unwraps its target when called. DOM targets print as HTML by default. Blob images and binary PDFs are converted first; callers can await the returned Promise.

Screenshots and printing depend on real browsers. Happy DOM tests verify state and error handling; they do not replace native print-dialog or physical-output acceptance.