API 参考

这里是 loading 的完整契约：你可以绑定、监听、投影和设置主题的一切，都集中在一处。接入你需要的部分，自定义你想要的样式——它是 standalone 的，且对 signal 友好。

输入

通过 17 个输入项精细调校 loading。像绑定任意 Angular @Input 一样绑定它们。

名称	类型	默认值	描述
`hub-loading · mode`	`'inline' \| 'overlay' \| 'fullscreen'`	`'inline'`	块所处的位置。`inline` 参与正常文档流并预留自身空间；`overlay` 采用绝对定位并覆盖最近的已定位祖先；`fullscreen` 固定于 viewport。
`hub-loading · variant`	`'spinner' \| 'dots' \| 'bars' \| 'pulse' \| 'ring'`	`'spinner'`	渲染哪一种纯 CSS 指示器。设置了 `image` 时会被忽略，因为图像会替换内置指示器。
`hub-loading · image`	`string \| null`	`null`	用于替代内置指示器渲染的 URL 或 data URI，通常是品牌标识。其盒子尺寸由 `--hub-loading-image-size` 决定。
`hub-loading · imageAnimation`	`'none' \| 'spin' \| 'pulse'`	`'none'`	施加于 `image` 的动效；未设置图像时不起作用。`spin` 适合径向对称的标识，`pulse` 让文字标识保持端正易读，`none` 则令其静止。
`hub-loading · message`	`string \| null`	`null`	渲染在指示器下方的文本，也是块出现时实时区域所播报的内容。为 `null` 时不渲染消息。
`hub-loading · size`	`'sm' \| 'md' \| 'lg'`	`'md'`	输入 `--hub-loading-size` 的尺寸档位。当布局需要这三档之外的尺寸时，该令牌本身仍可单独覆盖。
`hub-loading · color`	`string \| null`	`null`	指示器的强调色，由 `resolveHubAccent()` 归一化到唯一的 `--hub-loading-accent` 槽位。`primary` 这样的裸名称会解析为 `--hub-sys-color-*` 令牌并跟随主题；hex、`oklch()` 字面量或 `var(...)` 引用则原样使用。为 `null` 时保留该令牌自身的层叠默认值。
`hub-loading · backdrop`	`boolean`	`true`	在被覆盖的内容之上绘制半透明遮罩。在什么都不覆盖的 `inline` 模式下会被忽略。
`hub-loading · ariaLabel`	`string`	`'Loading'`	由宿主元素的 `role="status"` 实时区域播报的无障碍名称。
`hub-loading · appendTo`	`string \| null`	`'body'`	`fullscreen` 指示器要改挂到的元素的 CSS 选择器；为 `null` 或选不到任何元素时，它留在模板声明的位置。`inline` 与 `overlay` 永远不会被移动。
`hub-loading-bar · mode`	`'inline' \| 'overlay' \| 'fixed'`	`'inline'`	细带所处的位置。`inline` 参与正常文档流并预留自己的一行，出现时不会顶动任何内容；`overlay` 采用绝对定位，相对最近的已定位祖先——你设过 `position: relative` 的那个导航栏；`fixed` 则按 `--hub-loading-bar-offset` 固定到 viewport。
`hub-loading-bar · placement`	`'top' \| 'bottom'`	`'top'`	`overlay` 与 `fixed` 贴附的边。`bottom` 就是把进度条挂在导航栏下缘的那个值；`inline` 会忽略它。
`hub-loading-bar · progress`	`number \| null \| undefined`	`undefined`	接管进度条。不绑定时跟随 `HubLoadingBarService`；0 到 100 的数值直接驱动它并作为 `aria-valuenow` 公开；`null` 将其隐藏。
`hub-loading-bar · indeterminate`	`boolean`	`false`	不再填充，而是让一段来回扫动，适用于没有可度量进度的工作。此时不公布数值，而这正是 ARIA 标记位置未知的进度条的方式。
`hub-loading-bar · glow`	`boolean`	`true`	跟在前缘之后的柔光——即使在两次自动推进之间，它也仍读得出运动。
`hub-loading-bar · color`	`string \| null`	`null`	填充的强调色。单独的名称会解析为 `--hub-sys-color-*` 令牌并跟随主题；十六进制、`oklch()` 或 `var(...)` 则原样使用。
`hub-loading-bar · ariaLabel`	`string`	`'Loading'`	宿主 `role="progressbar"` 的无障碍名称。

输出

尚未记录任何输出项。

方法

通过代码驱动 loading——其编程接口提供 14 个方法。

名称	签名	返回值	描述
`HubLoadingService.show`	`show(options?: HubLoadingOptions): void`	`void`	登记一个调用方，若全屏 overlay 尚未挂起则将其挂载。只有实际传入的键才会覆盖到应用默认值之上，因此嵌套调用是叠加而非互相重置。
`HubLoadingService.hide`	`hide(): void`	`void`	注销一个调用方，并在没有调用方剩下时拆除 overlay。计数器在零处被钳制，因此一次多余的 `hide()` 不会让之后的 `show()` 变成空操作。
`HubLoadingService.hideAll`	`hideAll(): void`	`void`	一次性丢弃所有待处理的调用方并立即移除 overlay。这是留给错误处理与路由切换的应急出口，不能取代成对的 `show()` / `hide()`。
`HubLoadingService.update`	`update(options: HubLoadingOptions): void`	`void`	在不触碰引用计数的前提下重新装扮正在显示的 overlay——例如操作中途变化的进度消息，或切换变体。
`HubLoadingService.isLoading`	`isLoading: Signal<boolean>`	`Signal<boolean> — true while at least one reference is held`	只要还有至少一个调用方在等待，该 signal 即为 true。在服务端渲染期间也可安全读取：此时只有计数器在运行，不会挂载 overlay。
`HubLoadingBarService.start`	`start(): void`	`void`	登记一个调用方。第一个开启一轮——在宽限期之后，而不是立即——其余的只是加入计数。
`HubLoadingBarService.complete`	`complete(): void`	`void`	撤回一个调用方。当一个都不剩时，进度条走到 100% 然后淡出；若宽限期吞掉了整个操作，它就悄无声息地消失。
`HubLoadingBarService.completeAll`	`completeAll(): void`	`void`	一次性丢弃所有待处理的调用方并结束进度条。供错误处理使用，或用于从未配平自己 `start()` 的调用方。
`HubLoadingBarService.set`	`set(value: number): void`	`void`	把进度条移到一个确切的值并立即显示，不等待宽限期。适用于百分比真实的工作；数值被限制在 0–100，但不受自动推进上限的约束。
`HubLoadingBarService.inc`	`inc(amount?: number): void`	`void`	推进并显示进度条。不给数量时由配置的推进曲线决定，正是它让一段未知的等待始终在动却永不抵达。
`HubLoadingBarService.reset`	`reset(): void`	`void`	一次性取消一切——没有结束动画，没有待处理的调用方，屏幕上什么也不剩。
`HubLoadingBarService.progress`	`progress: Signal<number>`	`Signal<number> — the current fill, 0–100`	当前填充，0–100。在服务端渲染期间读取也是安全的。
`HubLoadingBarService.isActive`	`isActive: Signal<boolean>`	`Signal<boolean> — true while at least one caller is waiting`	是否还有调用方在等待——「页面在加载吗」这个诚实的问题，与进度条是否已决定现身无关。
`HubLoadingBarService.isVisible`	`isVisible: Signal<boolean>`	`Signal<boolean> — true only while the bar is painted`	进度条是否真的被画了出来。宽限期内为假，结束余韵期间仍为真。

模板

打造你自己的样式——7 个模板插槽让你可以投影自定义标记。

名称	描述	示例
`默认内容插槽`	标签之间投影的任何内容都会渲染在消息下方——取消操作、进度说明，或提示本次操作比平时更久。	`<hub-loading message="Importing rows"><button type="button">Cancel</button></hub-loading>`
`provideHubLoading`	通过 `HUB_LOADING_CONFIG` 令牌注册应用级默认值——品牌图像、偏好变体、已翻译的标签——使 `<hub-loading>` 与 `HubLoadingService` 都以此为起点，各个调用点保持简洁。	`providers: [provideHubLoading({ variant: 'ring', size: 'lg' })]`
`导航栏下的进度条`	进度条得名的那种摆放。导航栏上的 `position: relative` 才是把 overlay 限制在它内部的原因，而 `placement="bottom"` 把它挂在下缘。	`<nav class="navbar position-relative"> <hub-loading-bar mode="overlay" placement="bottom" /> </nav>`
`provideHubLoadingBarRouter`	让进度条恰好运行一次导航的时长，包括被守卫拒绝或以错误告终的那一次——手工接线的进度条通常就卡在这两种情况上。	`providers: [provideRouter(routes), provideHubLoadingBarRouter()]`
`hubLoadingBarInterceptor`	在每个 HTTP 请求的整个生命周期内保持进度条开启。`finalize` 在成功、出错与取消时同样配平。	`provideHttpClient(withInterceptors([hubLoadingBarInterceptor]))`
`withoutHubLoadingBar`	把某个请求排除在计数之外。否则定时轮询会让进度条永远开着，而一个永不结束的进度条比没有更糟。	`this.http.get('/api/heartbeat', { context: withoutHubLoadingBar() })`
`provideHubLoadingBar`	通过 `HUB_LOADING_BAR_CONFIG` 令牌注册应用级的进度条默认值——强调色、节奏、宽限期、推进曲线与已翻译的标签。	`providers: [provideHubLoadingBar({ color: 'primary', delay: 120 })]`