乐趣区

Angular-CDK-Overlay-弹出覆盖物

jiezi

为什么使用 Overlay？

Overlay 中文翻译过来意思是覆盖物，它是 Material Design components for Angular 中针对弹出动态内容这一场景的封装，功能强大、使用方便，尤其在开发自己的组件库时，可以让你少写许多代码，可以说只要是弹出内容的场景基本都可以使用 Overlay.
我们自己的组件库中弹出场景基本都已经使用 Overlay，如自定义 Select、Cascader、Tree Select、Tooltip、Dialog 等，总结最重要的的两点好处：

  1. 让使用者不再进行繁琐的位置计算，而简单通过参数配置就实现内容的定位，而且关于位置的各种情况都有考虑到.
  2. 组件的弹出内容都是用 Overlay 实现，避免了各自实现的产生的不兼容，如相互遮盖问题.

简单示例 – 连结位置源的弹出

下面通过一个示例代码来展示 Overlay 的使用，这种弹出场景类似于 Tooltip，弹出的 overlay 内容是基于一个参照的位置源 origin 元素.

安装并且导入模块

项目中如果没有安装 CDK，要先安装

  npm install @angular/cdk
导入 OverlayModule
import {OverlayModule} from '@angular/cdk/overlay';

@NgModule({
  imports: [
    OverlayModule,
    // ...
  ]
})
export class AppModule {}
示例模板内容
<div class="demo-trigger">
  <!-- 触发位置源 -->
  <button mat-raised-button
      cdkOverlayOrigin
      type="button"
      [disabled]="overlayRef"
      (click)="openWithConfig()">Open</button>
</div>

<!-- 弹出动态内容模板 -->
<ng-template #overlay>
  <div class="demo-overlay">
    <div style="overflow: auto;">
      <ul><li *ngFor="let item of itemArray; index as i">{{itemText}} {{i}}</li></ul>
    </div>
  </div>
</ng-template>

除了弹出模板，上面模板中还有一个 Open 按钮，后面要用到它作为位置源 origin

注入 Overlay 服务

在组件的 constructor 构造函数中注入 Overlay 服务，下面代码包括组件的定义

@Component({
  selector: 'overlay-demo',
  templateUrl: 'connected-overlay-demo.html'
})
export class ConnectedOverlayDemo {@ViewChild(CdkOverlayOrigin, {static: false}) _overlayOrigin: CdkOverlayOrigin;
  @ViewChild('overlay', {static: false}) overlayTemplate: TemplateRef<any>;
  /**
   * 注入 Overlay 服务
   */
  constructor(public overlay: Overlay) { }  

  openWithConfig() {}
}

处理注入服务，上面代码还通过 ViewChild 取到模板中的两个对象，后面用到的时候再解释.

构建位置策略

首先创建一个位置策略，这里使用的是 FlexibleConnectedPositionStrategy 策略，先看代码

const positionStrategy = this.overlay.position()
        .flexibleConnectedTo(this._overlayOrigin.elementRef)
        .withPositions([
        {
          originX: 'start',
          originY: 'bottom',
          overlayX: 'start',
          overlayY: 'top',
        }
      ]);

创建 FlexibleConnectedPositionStrategy 策略的方法 flexibleConnectedTo 必须要提供一个位置源参数，这里使用的是
this._overlayOrigin.elementRef，弹出内容的位置是基于这个位置源的，this._overlayOrigin 其实就是通过 ViewChild 取的模板中的 Open 按钮.

调用创建方法
 this.overlayRef = this.overlay.create({
      positionStrategy, // 位置策略
      scrollStrategy: this.overlay.scrollStrategies.reposition(), // 滚动策略
      direction: this.dir.value, // 可用性方面的设置，不用太关注
      minWidth: 200, // overlay 层的最小宽度
      minHeight: 50 // overlay 层的最小高度
      hasBackdrop: false // 是否显示遮罩层
    });

方法会生成一个 OverlayRef 类型的对象 overlayRef，用 overlayRef 来管理 Overlay。

通过 overlayRef 附加模板

一切准备就绪后，这里就是需要告诉 Overlay 弹出层要显示的内容，直接弹出模板，在模板中定义，这里用到的是 overlayRef 的 attach 方法，代码如下

 this.overlayRef.attach(new TemplatePortal(this.overlayTemplate, this.viewContainerRef));

代码中用到了 this.overlayTemplate，通过 ViewChild 取到的显示弹出内容的模板定义.

注：attach 方法用到了 CDK 里面的 Protals，attach 方法接收的参数类型其实是 TemplatePortal，因为这个说到底是动态创建组件，除此之外它还支持组件类型的 ComponentPortal，关于 Portals 可以参考我前面的文章 https://zhuanlan.zhihu.com/p/…

通过以上简单的几个步骤就实现动态内容的弹出，效果图如下所示

简单示例 – 全局弹出

与上面的完全不同，现在介绍下通过 Overlay 直接弹出内容在窗口上，不连结任何位置源，非常简单只需要更改下位置策略，看下使用的新位置策略的代码

 const positionStrategy = this.overlay.position()
      .global()
      .height('300px')
      .centerHorizontally()
      .top('70px');

调用 global() 返回的是全局的位置策略 GlobalPositionStrategy，基于浏览器窗口绝对定位的位置策略。
以上代码实现：水平居中，距离顶部 70px，效果图如下

Overlay 位置策略

Overlay 通过 OverlayPositionBuilder 服务提供了三个方法分别对应三种位置策略，OverlayPositionBuilder 通过构造函数注入到了 Overlay 服务中，前面代码 this.overlay.position() 返回的就是 OverlayPositionBuilder 类型的对象

ConnectedPositionStrategy – 连结点位置策略

注：该策略已被弃用，使用 FlexibleConnectedPositionStrategy 策略代替，但是这里的讨论可以继续，用以说明连接点的位置关系

connectedTo方法返回 ConnectedPositionStrategy 策略实例，该策略实现基于一个操作源上的位置点到 Overlay 弹出层的位置点连接关系的位置策略，创建策略的代码如下

  connectedTo(
      elementRef: ElementRef,
      originPos: OriginConnectionPosition,
      overlayPos: OverlayConnectionPosition): ConnectedPositionStrategy {
    return new ConnectedPositionStrategy(
        originPos, overlayPos, elementRef, this._viewportRuler, this._document, this._platform,
        this._overlayContainer);
  }

参数分别是：

  1. elementRef 要连接的元素，一般是触发弹出的元素
  2. originPos 连接元素的位置点
  3. overlayPos overlay 的位置点

用图表达它所维系的位置关系

上图所示的位置点组合只是其中一种情况（左下点 – 左上点），位置配置代码如下

 {
  "originX": "start",
  "originY": "bottom",
  "overlayX": "start",
  "overlayY": "top"
}

在 x 方向上可枚举值定义如下

 export type HorizontalConnectionPos = 'start' | 'center' | 'end';

在 y 方向上可枚举值定义

 export type VerticalConnectionPos = 'top' | 'center' | 'bottom';

基于以上枚举值可以实现各种位置组合。

FlexibleConnectedPositionStrategy – 灵活的连接点位置策略

注：现在的源代码 ConnectedPositionStrategy 策略最终也是通过关联 FlexibleConnectedPositionStrategy 策略实现的，所以推荐直接使用该策略

通过 flexibleConnectedTo 方法返回 FlexibleConnectedPositionStrategy 策略实例，这是 Overlay 最复杂的一个位置策略，所以能称上 Flexible，通过指令方式使用 Overlay 时就是使用的这个策略，它在位置策略上有更多的控制，特性如下：

  1. withDefaultOffsetX、withDefaultOffsetY设置相对基础位置的偏移。
  2. withPositions参数为 ConnectionPositionPair 类型的数组，提供多种位置组合，当某一种位置组合的弹出内容超出窗口，就会应用对应其它的位置组合来避免内容不可见。
  3. withFlexibleDimensions 控制 Overlay 弹出层宽度和高度是否被限制在浏览器窗口内，参数设置为 ture 时，宽度和高度会自适应到浏览器边界，以滚动条形式展现内容。
  4. 等等位置方面其它可预见的细节的处理

创建策略的代码如下

   /**
   * Creates a flexible position strategy.
   * @param origin Origin relative to which to position the overlay.
   */
  flexibleConnectedTo(origin: FlexibleConnectedPositionStrategyOrigin):
    FlexibleConnectedPositionStrategy {
    return new FlexibleConnectedPositionStrategy(origin, this._viewportRuler, this._document,
        this._platform, this._overlayContainer);
  }

只有一个 origin 参数，提供了要连结的位置源元素引用。

GlobalPositionStrategy

全局位置策略，global方法返回 GlobalPositionStrategy 策略实例，无任何参数，创建策略的代码如下

  /**
   * Creates a global position strategy.
   */
  global(): GlobalPositionStrategy {return new GlobalPositionStrategy();
  }

GlobalPositionStrategy 提供了全局定位的各种方法，并且可以通过链式的方式调用，如下代码

const strategy = this.overlay
  .position()
  .global()
  .width('500px')
  .height('100px')
  .centerHorizontally()
  .centerVertically();

还有 top、left、bottom、right 方法提供各个方位的绝对定位，参数是在这个方位上的偏移值，如居上 10px 参数就是'10px'，这是这个偏移值会打破水平或者垂直方向上的居中。

PositionStrategy 位置策略接口

位置策略接口定义如下

 import {OverlayReference} from '../overlay-reference';

/** Strategy for setting the position on an overlay. */
export interface PositionStrategy {
  /** 附加位置策略到 overlay */
  attach(overlayRef: OverlayReference): void;

  /** 更新 overlay element 元素的位置. */
  apply(): void;

  /** 当 overlay 调用 detach 时调用 */
  detach?(): void;

  /** Cleans up any DOM modifications made by the position strategy, if necessary. */
  dispose(): void;}

接口定义了位置策略必须包含的方法签名，这是面向对象编程中的常用的抽象方式。
OverlayRef 在实现时只依赖 PositionStrategy 接口而不具体依赖某一个策略的实现，在创建 OverlayRef 需要提供一个具体的位置策略的实例（一般是在创建 Overlay 时配置），如果有需要还可以实现自己的位置策略，实现自己的位置策略只需要实现这个接口并且定义接口签名的具体实现。
符合面向对象的三大特性 封装 、 继承 、 多态 ，符合五大原则中的 单一职责原则 、 开放封闭原则，这种抽象思想非常值得学习

滚动策略

Overlay 提供了全局服务ScrollStrategyOptions，用它提供处理 overlay 滚动时的处理策略。

NoopScrollStrategy – 不提供任何处理

在滚动不做任何事情，调用 scrollStrategies 的noop方法

  noop = () => new NoopScrollStrategy();
CloseScrollStrategy – 关闭滚动策略

一旦用户有滚动行为，立即关闭 overlay 弹层，调用 scrollStrategies 的close方法

  close = (config?: CloseScrollStrategyConfig) => new CloseScrollStrategy(this._scrollDispatcher,
      this._ngZone, this._viewportRuler, config)

可以配置 config 中的参数threshold，设置一个滚动像素的临界点，只有当滚动距离大于此参数时才会关闭 overlay.

BlockScrollStrategy – 阻止滚动策略

该策略会阻止页面级的滚动，调用 scrollStrategies 的block方法

   block = () => new BlockScrollStrategy(this._viewportRuler, this._document);

通过给页面的 html 标签增加样式 cdk-global-scrollblock 来阻止页面级别的滚动，样式定义如下

position: fixed;
width: 100%;
overflow-y: scroll;

RepositionScrollStrategy – 重定位滚动策略

一旦用户有滚动行为，该策略会根据滚动的位置更新弹出层的位置，效果就是弹出层会跟随滚动而滚动，相对于位置源的位置不变，调用 scrollStrategies 的reposition方法

   reposition = (config?: RepositionScrollStrategyConfig) => new RepositionScrollStrategy(this._scrollDispatcher, this._viewportRuler, this._ngZone, config)

config 可以配置两个参数，scrollThrottle参数控制滚动事件触发重新更新位置的抖动频率，autoClose参数配置当滚动事件发生时是否关闭 overlay 弹层（实现 关闭滚动策略 的功能）

滚动的触发

无论是关闭 Overlay 还是更新 Overlay 位置，都需要检测滚动事件的触发，这里要用到 CDK 提供的处理滚动的服务（cdk/scrolling 目录下），主要用到 ScrollDispatcher，一个处理全局滚动事件的触发器.
关闭滚动策略 和 重定位滚动策略 都是订阅 ScrollDispatcher 的scrolled 方法返回的流（后面统一叫 scrolled 流），有几点要明确

  1. 全局页面文档的滚动定会触发 scrolled 流
  2. overlay 是否显示 backdrop（遮罩层）对 重定位滚动策略 有影响，显示 backdrop 会阻止页面局部元素的滚动，对全局页面文档滚动没有影响，所以可以看到的效果是，官方的 overlay 示例即使显示 backdrop 层，reposition 仍然起作用，但自己在实现 overlay 跟随滚动的时候可能会失败，因为根本触发不了局部滚动事件。
  3. scrolled 流是一个全局的滚动监听，任何注入的 CdkScrollable 所关联的元素滚动都会触发 scrolled 流（如果滚动跟 overlay 没有关系，那重新计算位置也没有影响，计算后还是原来的位置，不过这块感觉有待优化）
实现局部元素滚动 Overlay 层重定位

因为国内的软件大部分是把整个窗口固定，然后再通过局部元素设置样式 overflow:scroll 实现内容滚动，这里仅提供思路

  1. 关闭 backdrop，至于点击 backdrop 后 overlay 关闭，就需自己实现了
  2. 根据滚动区域构造 CdkScrollable 示例，可以用代码遍历 origin 元素的可滚动父元素

这块理解起来并没有那么容易，很抽象，又是由 overlay、scroll、position 策略、scroll 策略组合起来的，现在可以先做了解，需要了解细节时再翻看源代码。

总结

文字首先介绍了使用 Overlay 的好处，以及在我们的组件库中都有那些组件使用了 Overlay，然后通过简单的示例代码带大家了解 Overlay 的使用，后面又介绍了 Overlay 的位置策略和滚动策略，希望看到最后的各位有些帮助。
Overlay 需要说的内容非常的多，而且整体封装的思想也很值得学习，这里就简单介绍这么多，有任何建议或者疑问欢迎留言讨论。
另外文中的示例基本是在 Material Design Components for angular 中针对 Overlay 的 Demo，有需要可以自行 clone 代码学习

示例运行命令
git clone https://github.com/angular/co…
cd components
yarn install // 如果提示没有 yarn 需要全局装下 yarn，node 版本要求 10.x
npm run dev-app

本文作者：Worktile 工程师 杨振兴

文章来源：Worktile 技术博客

欢迎访问交流更多关于技术及协作的问题。

文章转载请注明出处。

退出移动版