angular-cdk

@angular/cdk（Component Dev Kit）

版本： 21.0.3（2026 年 2 月） 标签： 无障碍、拖放、Overlay、虚拟滚动、Portal

参考资料： 文档 — 官方 CDK 文档 • GitHub • API

API 变更

本节介绍近期特定版本的 API 变更。

• 新增：CDK overlays 现在使用浏览器内置的 popovers，以提升无障碍性 来源

• 新增：Angular 19 基于 signal 的 API — 为 CDK 组件提供现代化的 signal 集成

• 新增：改进焦点管理 — 更好地支持 cdkTrapFocus 和 cdkFocusRegion

• 新增：拖放改进 — 增强列表间的项目复制功能

• 已弃用：旧版 overlay 策略 — 建议使用滚动策略配置，而非已弃用的方案

最佳实践

• 使用 CDK 构建自定义 UI 组件 — 构建不带 Material 样式的自有组件

import { OverlayModule } from '@angular/cdk/overlay';
import { PortalModule } from '@angular/cdk/portal';

@Component({
  standalone: true,
  imports: [OverlayModule, PortalModule],
  // ...
})
export class CustomDropdownComponent {}

• 使用 Overlay 创建浮动面板 — 工具提示、下拉菜单、模态框

import { OverlayRef, Overlay } from '@angular/cdk/overlay';

export class TooltipService {
  private overlayRef: OverlayRef;

  constructor(private overlay: Overlay) {
    this.overlayRef = this.overlay.create({
      hasBackdrop: true,
      positionStrategy: this.overlay.position()
        .connectedTo(origin, { originX: 'center', originY: 'bottom' })
        .withOffsetX(0)
        .withOffsetY(8)
    });
  }
}

• 使用 Drag & Drop 创建可排序列表

import { CdkDragDrop, moveItemInArray, transferArrayItem } from '@angular/cdk/drag-drop';

drop(event: CdkDragDrop<string[]>) {
  if (event.previousContainer === event.container) {
    moveItemInArray(event.container.data, event.previousIndex, event.currentIndex);
  } else {
    transferArrayItem(
      event.previousContainer.data,
      event.container.data,
      event.previousIndex,
      event.currentIndex
    );
  }
}

• 使用 Virtual Scroll 处理大型列表

import { ScrollingModule } from '@angular/cdk/scrolling';

@Component({
  standalone: true,
  imports: [ScrollingModule],
  template: `
    <cdk-virtual-scroll-viewport itemSize="50" class="viewport">
      <div *cdkVirtualFor="let item of items">{{item.name}}</div>
    </cdk-virtual-scroll-viewport>
  `
})
export class ListComponent {}

• 使用 Portal 插入动态内容

import { DomPortalOutlet, TemplatePortal } from '@angular/cdk/portal';

@Component({ template: `<ng-template #dialogTemplate>Content</ng-template>` })
export class DialogComponent {
  @ViewChild('dialogTemplate') dialogTemplate!: TemplatePortal;

  attach() {
    const portalOutlet = new DomPortalOutlet(this.document.body);
    portalOutlet.attach(this.dialogTemplate);
  }
}

• 使用 A11y 实用工具提升无障碍性

import { A11yModule, CdkTrapFocus, LiveAnnouncer } from '@angular/cdk/a11y';

@Component({
  standalone: true,
  imports: [A11yModule],
  template: `
    <div cdkTrapFocus>
      <button cdkFocusInitial>First</button>
      <button>Second</button>
    </div>
  `
})
export class AccessibleComponent {
  constructor(private liveAnnouncer: LiveAnnouncer) {
    this.liveAnnouncer.announce('Message for screen readers');
  }
}

• 使用 Layout 处理响应式断点

import { LayoutModule } from '@angular/cdk/layout';

@Component({
  standalone: true,
  imports: [LayoutModule],
  template: `
    <div *ngIf="isHandset$ | async">
      Mobile content
    </div>
  `
})
export class ResponsiveComponent {
  isHandset$ = this.breakpointObserver.observe('(max-width: 599px)');
}