UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载本文基于 ng-zorro-antd 仓库中的下拉菜单官方文档与对应源码讲解nz-dropdown指令的完整 API、nz-dropdown-menu容器组件以及NzContextMenuService右键菜单服务的用法与实现原理。读完本文你不仅能直接使用下拉菜单收纳页面操作命令还能理解其触发机制、浮层定位、显隐双向绑定与滚动跟随背后的 CDK Overlay 实现细节并解决「滚动时浮层不跟随」这一常见坑点。何时使用当页面上的操作命令过多时用 Dropdown 组件可以收纳操作元素。点击或移入触点会出现一个下拉菜单可在列表中进行选择并执行相应的命令。组件构成与模块依赖Dropdown 模块位于 components/dropdown/ 目录对外 API 由 public-api.ts 统一导出核心构件有四个构件文件职责NzDropdownDirectivenz-dropdowndropdown.directive.ts触点指令监听触发事件、管理浮层显隐与定位NzDropdownADirectivedropdown-a.directive.ts为a[nz-dropdown]触点自动添加ant-dropdown-link样式类NzDropdownMenuComponentnz-dropdown-menudropdown-menu.component.ts菜单容器包裹nz-menu作为浮层模板NzContextMenuServicecontext-menu.service.ts右键弹出下拉菜单的服务从 dropdown.module.ts 的模块定义可以看到NzDropdownModule的exports中包含NzMenuModule——也就是说引入 Dropdown 模块后nz-menu、nz-menu-item、nz-menu-divider等菜单组件可直接使用无需单独引入。关键设计菜单项不占页面布局NzDropdownMenuComponent内部只声明了一个ng-template包裹ant-dropdown根节点与投影内容并持有对它的静态ViewChild引用。更值得注意的是该组件在ngAfterContentInit中执行renderer.removeChild(...)把自身元素从文档中移除。这意味着nz-dropdown-menu在页面上不渲染任何实际 DOM菜单内容只在浮层被打开时才通过TemplatePortal挂载到 CDK Overlay 中。这正是「触点 菜单容器」必须分离书写、且菜单可以随意放在模板任意位置的原因。基本用法最简示例触点上挂nz-dropdown指令并通过[nzDropdownMenu]绑定菜单组件菜单内容用nz-dropdown-menu包裹。仓库内置示例 basic.ts 展示了标准写法a nz-dropdown [nzDropdownMenu]menu Hover me nz-icon nzTypedown / /a nz-dropdown-menu #menunzDropdownMenu ul nz-menu nzSelectable li nz-menu-item1st menu item/li li nz-menu-item2nd menu item/li li nz-menu-item3rd menu item/li li nz-menu-item nzDanger4th danger item/li /ul /nz-dropdown-menu模板变量#menunzDropdownMenu导出的是NzDropdownMenuComponent实例可传给[nzDropdownMenu]输入也可以传给NzContextMenuService的create方法见下文。注意每个nz-dropdown-menu只能作为一个nz-dropdown的输入项不要将同一个菜单实例同时绑给多个触点。触发方式[nzTrigger]支持hover默认与click两种触发行为完整菜单能力分割线、禁用项、子菜单参见 trigger.ts 示例a nz-dropdown nzTriggerclick [nzDropdownMenu]menu Click me nz-icon nzTypedown / /a nz-dropdown-menu #menunzDropdownMenu ul nz-menu li nz-menu-item1st menu item/li li nz-menu-divider/li li nz-menu-item nzDisableddisabled menu item/li li nz-submenu nzTitlesub menu ul li nz-menu-item3rd menu item/li li nz-menu-item4th menu item/li /ul /li /ul /nz-dropdown-menu菜单选中态与模式约束菜单使用 nz-menu 组件还包括菜单项[nz-menu-item]、分割线[nz-menu-divider]、子菜单[nz-submenu]。官方文档给出两条重要约束nz-dropdown下的[nz-menu]默认不可选中。如果需要菜单可选中指定ul nz-menu nzSelectable。从源码结构看这一约束是通过依赖注入 Token 实现的NzDropdownMenuComponent在providers中提供了NzIsMenuInsideDropdownToken值为true而 menu 模块中的菜单指令、菜单项、子菜单等组件都注入该 Token 来感知「自己是否位于下拉菜单内部」从而调整选中行为与展开方式相关实现见 menu.directive.ts 与 menu.token.ts。nz-dropdown-menu内[nz-menu]的nzMode只可以是默认值vertical。下拉浮层的宽度、定位都按纵向垂直菜单设计不要在其中使用 horizontal 模式。nz-dropdown 指令 API以下是[nz-dropdown]的完整参数表继承自官方文档并结合源码 dropdown.directive.ts 的默认值补充参数说明类型默认值版本[nzDropdownMenu]Dropdown 下拉菜单组件NzDropdownMenuComponent-[nzDisabled]菜单是否禁用booleanfalse[nzPlacement]菜单弹出位置bottomLeft \| bottomCenter \| bottomRight \| topLeft \| topCenter \| topRightbottomLeft[nzTrigger]触发下拉的行为click \| hoverhover[nzClickHide]点击菜单项后是否隐藏菜单booleantrue[nzVisible]菜单是否显示可双向绑定booleanfalse[nzOverlayClassName]下拉根元素的类名称string[nzOverlayStyle]下拉根元素的样式object{}(nzVisibleChange)菜单显示状态改变时调用参数为 nzVisibleEventEmitterboolean-[nzArrow]下拉框箭头是否显示booleanfalse20.2.0此外源码中还提供了一个未在 API 表中列出的输入[nzMatchWidthElement]ElementRef默认为null浮层minWidth默认匹配触点的宽度若希望浮层宽度匹配其他元素例如更宽的输入框可将该元素的ElementRef传入。[nzBackdrop]默认为false带WithConfig装饰器可通过全局配置dropdown模块名统一设置则控制在click触发时是否渲染遮罩层。显隐控制nzVisible 与 nzClickHide[nzVisible]支持双向绑定。从源码可见其显隐逻辑是两路信号合并inputVisible$来自[nzVisible]输入的BehaviorSubject与domTriggerVisible$由 hover/click 触发事件、菜单项点击、浮层关闭事件合并而成即外部受控状态与内部触发状态共同参与判定。参考 overlay-visible.ts 示例a nz-dropdown [nzDropdownMenu]menu [nzClickHide]false [(nzVisible)]visible Hover me nz-icon nzTypedown / /a nz-dropdown-menu #menunzDropdownMenu ul nz-menu li nz-menu-itemClicking me will not close the menu./li li nz-menu-item (click)close()Clicking me will close the menu/li /ul /nz-dropdown-menureadonly visible signal(false); close(): void { this.visible.set(false); }[nzClickHide]false使点击菜单项后菜单不再自动收起结合[nzVisible]绑定你可以在菜单项回调中显式调用visible.set(false)实现「点击指定项才关闭」的交互对应 contextmenu 事件示例 中的(click)log(1st menu item)监听方式。弹出位置与箭头[nzPlacement]六种取值可参考 placement.ts 与 arrow.ts 示例button nz-button nz-dropdown [nzDropdownMenu]menu [nzPlacement]position nzArrow {{ position }} /button其中nzArrow自 20.2.0 版本起可用。从源码看开启箭头后浮层在指定位置会额外叠加一套偏移量setConnectedPositionOffset配合TOOLTIP_OFFSET_MAP为箭头预留空间并通过placement信号把实际落位回写给nz-dropdown-menu在其根节点上切换ant-dropdown-placement-*与ant-dropdown-show-arrow类保证箭头始终指向触点。浮层实现原理CDK Overlay 与显隐时序打开NzDropdownDirective的ngAfterViewInit可以看到整个显隐链路dropdown.directive.ts触发源归一化hover触发时合并「触点 mouseenter/mouseleave」与「菜单自身 mouseenter/mouseleave」两路鼠标状态——这样鼠标从触点移到菜单过程中菜单不会闪退click触发时只监听触点 click。状态合并与防抖受控输入、DOM 触发事件、浮层关闭事件三路信号经combineLatest与auditTime(150)防抖后统一决定nzVisible并在状态变化时发出nzVisibleChange。浮层创建首次打开时调用createOverlayRef关键配置包括minWidth匹配触点或nzMatchWidthElement宽度、hasBackdropnzBackdrop nzTrigger click、scrollStrategy为 reposition 策略滚动时重新定位而非关闭以及disposeOnNavigation: true。位置回退withPositions传入的顺序是「nzPlacement[bottomLeft, bottomRight, topRight, topLeft]兜底列表」首选位置放不下时自动回退避免浮层溢出视口。自动关闭事件backdrop 点击、浮层 detach、浮层外指针事件、以及不带修饰键的ESCAPE按键都会将状态置为关闭关闭时先detach()浮层动画animationend后再dispose()释放引用见animationStateChange$订阅dropdown.directive.ts。NzContextMenuService右键菜单NzContextMenuService用于在页面任意位置右键弹出下拉菜单context-menu.service.ts。其方法/属性如下方法/属性说明参数返回create创建右键菜单($event: MouseEvent \| {x:number, y:number}, menu: NzDropdownMenuComponent)EmbeddedViewRefanyclose关闭右键菜单--参考 context-menu.ts 示例div classcontext-area (contextmenu)contextMenu($event, menu)Right Click on here/div nz-dropdown-menu #menunzDropdownMenu ul nz-menu li nz-menu-item1st menu item/li li nz-menu-item nzDisableddisabled menu item/li li nz-submenu nzTitlesub menu ul li nz-menu-item3rd menu item/li li nz-menu-item4th menu item/li /ul /li /ul /nz-dropdown-menuprivate readonly nzContextMenuService inject(NzContextMenuService); contextMenu($event: MouseEvent, menu: NzDropdownMenuComponent): void { this.nzContextMenuService.create($event, menu); }create接受MouseEvent或{x, y}坐标对象作为弹出位置。从源码实现看context-menu.service.ts它有几个值得注意的细节传入MouseEvent时会主动preventDefault()屏蔽浏览器原生右键菜单位置策略使用四组ConnectionPositionPair兜底起点在坐标右上、左下、右下、左上保证菜单不超出视口滚动策略是createCloseScrollStrategy——页面滚动时右键菜单会直接关闭区别于nz-dropdown的 reposition 策略监听document级别的事件完成自动关闭点击浮层之外且排除鼠标右键按钮button 2以兼容 Firefox 的 contextmenu 行为或按下Escape键均触发close()菜单项点击后也会关闭。FAQQ滚动时浮层元素没有跟随滚动位置默认情况下浮层元素使用body作为滚动容器如果使用了其他滚动容器在自定义滚动容器元素上添加CdkScrollable指令。注意需要从angular/cdk/scrolling导入CdkScrollable指令或ScrollingModule模块。从源码结构看nz-dropdown的scrollStrategy由createRepositionScrollStrategy创建dropdown.directive.ts其重新定位依赖 CDK 识别触点所在的滚动祖先若页面使用了虚拟滚动容器或未声明的滚动容器CDK 找不到对应Scrollable实例浮层自然不会跟随。添加CdkScrollable指令正是为了让该容器纳入 CDK 的滚动识别范围。相关代码路径内容路径官方文档components/dropdown/doc/index.zh-CN.md触发指令实现components/dropdown/dropdown.directive.ts菜单容器组件components/dropdown/dropdown-menu.component.ts右键菜单服务components/dropdown/context-menu.service.ts模块定义components/dropdown/dropdown.module.ts内置示例基础/触发/位置/箭头/右键/事件/显隐components/dropdown/demo/指令与服务的测试用例components/dropdown/dropdown.directive.spec.ts、components/dropdown/context-menu.service.spec.ts菜单组件文档components/menu/doc/index.zh-CN.md赞分享UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载相关推荐ng-zorro-antd 右键菜单实战用 NzContextMenuService 与 nz-dropdown-menu 构建 Context Menung zorro antd 右键菜单实战用 NzContextMenuService 与 nz dropdown menu 构建 Context Menu nUI组件前端ng-zorro-antd 实现下拉多级菜单nz-dropdown 嵌套 nz-submenu 的模板与源码机制ng zorro antd 实现下拉多级菜单nz dropdown 嵌套 nz submenu 的模板与源码机制 本文基于 ng zorro antd 下拉菜UI组件前端ng-zorro-antd Dropdown 下拉菜单nzClickHide 关闭自动隐藏与 nzVisible 双向绑定控制菜单显隐ng zorro antd Dropdown 下拉菜单nzClickHide 关闭自动隐藏与 nzVisible 双向绑定控制菜单显隐 本文围绕 ng zorUI组件前端上一篇jonathandinu/face-parsing开源生态依赖库与工具链全解析下一篇如何快速上手FLUX.1-dev5分钟完成环境搭建与图像生成创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
