Angular 操作面板 | ng-hub-ui-action-sheet

由服务打开的 Angular 操作面板:带角色的操作、平铺或分组、可拒绝关闭的处理函数,以及通过背景、键盘或拖动关闭。

最后更新 2026年9月21日

概览

团队为何搜索这个库

当某一行或工具栏按钮需要在当前界面之上提供几个操作时,就用 ng-hub-ui-action-sheet,不必为一个还没人打开的面板在页面里留一个菜单组件。

安装

npm install ng-hub-ui-action-sheet

跳转到

适用于

关于 action-sheet

ng-hub-ui-action-sheet 是一个 Angular 独立库,它从服务中打开面板,并以读者的选择只解析一次。操作带有角色:`cancel` 无论在哪里声明都会排到最后,`destructive` 使用危险色。操作可以平铺,也可以放在分组标题下;handler 可以拒绝关闭,这样确认步骤能在面板消失之前执行。退出方式有三种 — 背景、`Escape` 和向下拖动面板 — 每一种都会报告自己的角色,并先执行取消操作的 handler。面板是带 `aria-modal` 的 `role="dialog"`,由它的标题命名,打开时焦点会移入其中。

功能指南

打开操作面板

面板由服务打开并只应答一次,因此关闭时页面上不会留下它的任何内容。

示例:
打开操作面板

一个标题、三个操作和一个出口;调用以选择结束。

Nothing chosen yet
代码
导入:
模板:
组件:

角色与处理函数

角色决定每个操作的位置与语气;处理函数决定面板是否可以关闭。

示例:
角色与会拒绝的处理函数

破坏性操作首次失败,并让面板保持打开。

The first attempt always fails, on purpose
代码
导入:
模板:
组件:

分组操作

带自有标题的分块,适用于长到平铺列表已难以阅读的面板。

示例:
分组操作

带标题的分块、标记当前格式,以及一个禁用项。

Export format: pdf
代码
导入:
模板:
组件:

强调色与令牌

整个面板一个语义强调色,其下每个视觉决定各有一个 CSS 变量。

示例:
强调色与令牌

同一个面板,先用语义强调色,再用品牌令牌。

The accent colours the selected action; the branded sheet also changes its radius, its touch targets and the width it is allowed to take.

代码
导入:
模板:
组件:

核心特性

最近更改

Version 22.3.0 - 9/21/26, 12:00 AM

added: The sheet animates out, which the animation option already promised. Only the entry had keyframes, so the sheet vanished the instant it settled. The closing pass replays the same keyframes in reverse and the view is destroyed once they finish; with the option off or reduced motion asked for, it leaves at once as before.

Version 22.2.2 - 9/20/26, 12:00 AM

changed: The npm keywords name what the package does — sheet, dialog, menu, overlay, focus-trap, swipe-to-close, accessibility — instead of stopping at the generic ones. Keywords are what npm ranks a search on. Metadata only: no code, types or styles change.

Version 22.2.1 - 9/16/26, 12:00 AM

changed: Repository, issue and README links follow the move to the hub-env organization. Issues for every Hub UI package are now gathered in hub-env/hub-ui, and the repository and bugs fields of the manifest point at the new addresses. No code, types or styles change.

Version 22.2.0 - 9/8/26, 12:00 AM

deprecated: `HubActionSheetComponent` is announced for removal in 23.0.0. The entry point exported it while this page said the library has no template API; the page was the true half. The class cannot be used from a template — `sheetRef` demands a `HubActionSheetRef` whose closing half is `@internal` and wired by `HubActionSheet.open()`, so a hand-mounted sheet resolves its promise and then stays on screen behind a fixed backdrop that traps `Tab` across the document. Nothing changes at runtime; this release is the notice. See `BREAKING_CHANGES.md`.

changed: `public-api.ts` lists the component by name instead of re-exporting its whole file, so the symbol on its way out is named where it is exported. `HubResolvedActionSheetOptions` is unaffected and stays exported.

Version 22.1.0 - 9/7/26, 12:00 AM

fixed: A `:root` in the application now reaches the sheet. The `--hub-action-sheet-*` defaults were declared in a `:root, :host` block, and the encapsulation shim turns the `:root` half into a selector nothing matches — so what survived declared every token straight on the `<hub-action-sheet>` element, and a declaration on an element beats an inherited value whatever its specificity. Every `:root` an application wrote for this library was dead, `!important` included. Each token is now read where it is painted, `var(--hub-action-sheet-x, <default>)`, with the same component → design-system → literal chain as before. See `BREAKING_CHANGES.md`: a `:root` block that never did anything starts doing it.

fixed: A `panelClass` that re-bases `--hub-action-sheet-accent` now recolours the selected action. The accent roles were derived on the host, above the element the class lands on, so the derived value was already fixed by the time the branded class changed the slot. They are derived where the colour is painted, so `:root`, `panelClass` and `variant` all recompute the selection.

changed: `--hub-action-sheet-accent-emphasis` is declared on the sheet element rather than on the host. Nothing in the component paints with it — it is the accent family's third role, there for a consumer dressing the sheet — and declaring it beside the accent means a `panelClass` re-basing the slot recomputes it.

changed: The two READMEs and `docs/css-variables-reference.md` say why both entry points work. Setting a token on `:root` and setting it through `panelClass` were documented side by side without saying which wins, and one of the two did not work at all.

Version 22.0.2 - 9/6/26, 12:00 AM

added: `FUNCTIONALITIES.md`, the map every other library in the family already had, so a reader can tell a feature that only lives in a code snippet from one a live example demonstrates.

changed: The configuration surface the package exports is written down: `HUB_ACTION_SHEET_CONFIG`, `HUB_ACTION_SHEET_DEFAULTS` and the `HubActionSheetConfig` interface, whose `variant` and `panelClass` settle an application's accent and sheet class once. Until now the only way to find any of it was to read the sources.

changed: `HubActionSheetRef.settled` is listed in the API tables. It is public and both READMEs already documented it, but the page a reader looks at first did not.

changed: The page's changelog is the released one. It stopped at `22.0.0`, dated before the published `22.0.1`, and its `22.0.0` entry left out `provideHubActionSheet()` and the CSS variable theming the release notes list; a changelog that lags the registry teaches the reader not to trust it.

changed: Both READMEs describe a library on the stable line rather than one in its early stages, and list the family that exists today. The Spanish one also dropped its note announcing documentation pages that have been live for a week, since two READMEs that disagree are worse than one that is merely terse.

fixed: `docs/css-variables-reference.md` gave `--hub-ref-space-1` a default of `0.5rem`, twice the `0.25rem` both readings of the token actually fall back to, so anyone sizing their own scale from that table was working from the wrong number. The two design-system tokens it omitted, `--hub-sys-color-surface-subtle` and `--hub-sys-color-ink`, are listed as well.

fixed: The hover background of an action falls back to `#f8f9fa`, the value it is declared with, instead of an `rgba(0, 0, 0, 0.05)` literal that could never be reached and contradicted the documented default.

fixed: The action with the `selected` role announces itself with `aria-current="true"` instead of `aria-checked`, which is not defined for a plain button and left the state visible only to readers who could see the sheet.

Version 22.0.1 - 9/1/26, 12:00 AM

changed: The `homepage` in the package manifest points at this library's own documentation page rather than at the site root. Metadata only — nothing a consumer imports is affected.

Version 22.0.0 - 8/30/26, 12:00 AM

added: `HubActionSheet.open()` returns a `HubActionSheetRef` whose `result` resolves once, with the role and data of the chosen action or with how the sheet was dismissed.

added: Actions with roles: `cancel` is set apart at the end wherever it was declared, `destructive` reads in the danger colour, `selected` is marked, and a handler returning `false` keeps the sheet open.

added: Grouped actions with an optional title per block, plus header and sub-header.

added: Dismissal by backdrop, `Escape` and by dragging the sheet down, each reporting its own role and running the cancel action first.

added: `role="dialog"` with `aria-modal`, focus moved in on open, trapped while the sheet lives and returned to the opener on close.

added: `provideHubActionSheet()` sets the defaults every sheet starts from — the four behaviour flags plus `variant` and `panelClass` — overridable per call.

added: CSS variable theming through the `--hub-action-sheet-*` tokens, with the semantic accent on the single-slot contract the rest of the family uses (`variant`), and motion that steps aside under `prefers-reduced-motion`.

removed: The placeholder `ActionSheet` component (selector `lib-action-sheet`) that the pre-release package shipped.

常见问题

在 Angular 里怎么打开一个 action sheet?

注入 HubActionSheet,调用 open() 并传入标题和一组按钮。模板里什么都不用放:服务会自己把面板挂到 document.body 上,并返回一个 HubActionSheetRef,它的 result 是一个 Promise,resolve 出用户所选项的 role 和 data。hub-action-sheet 组件仍然导出,但它已废弃,将在 23.0.0 中移除,因为手动挂载时,它把自己的 Promise resolve 之后还会留在屏幕上。

action sheet 的按钮怎么定义?

用普通数据来定义,而不是投影内容:buttons 接受一个对象数组,字段有 text、role、icon、disabled、data、cssClass 和 handler,还可以把它们嵌套成组来画出分隔线。role 为 cancel 的按钮会被从你声明它的位置提出来,渲染到属于它自己的底部区块里,role 为 destructive 则给危险的那一项加上相应样式。handler 返回 false 会否决这次关闭,操作失败后想让面板留着就靠这个。icon 是写在一个空元素上的 CSS class 字符串,所以图标字体要你自己提供。

action sheet 怎么关闭?

有三种方式,每一种都可以单独关掉:点击遮罩,由 backdropDismiss 控制;按 Escape 键,由 keyboard 控制;以及在手柄上向下拖动,由 swipeToClose 控制,拖动超过 64 像素或面板高度的四分之一就会关闭。选中一个操作同样会关闭它,ref.dismiss() 则让你在自己的代码里关闭它。provideHubActionSheet() 为整个应用设定这些默认值,而 cancel 按钮的 handler 在每一种关闭方式下都会执行,所以一份收尾逻辑就能覆盖所有出口。

在桌面端,action sheet 会变成 popover 或对话框吗?

不会。它的样式表里连一个断点都没有:宽屏上你看到的还是同一个贴着底部的面板,最大 34rem,水平居中。如果你想要一个锚定在触发按钮上的菜单,那就是选错组件了。动手之前还有两点值得知道:open() 会立刻访问 document,所以它必须跑在浏览器里,不能在服务端渲染时执行;另外面板会捕获 Tab,但不会把它背后的页面设为 inert,所以屏幕阅读器仍然可能游荡进去。