feat: 控件的 position 支持自定义 DOM 容器 (#1440)

Co-authored-by: yanxiong <oujinhui.ojh@antgroup.com>

dev-demos/layer/control/position.tsx

@@ -1,7 +1,16 @@
-import { GaodeMap, Logo, PositionName, Scale, Scene, Zoom } from '@antv/l7';
-import { FunctionComponent, useEffect } from 'react';
+import {
+  GaodeMap,
+  IControlOption,
+  Logo,
+  Scale,
+  Scene,
+  Zoom,
+} from '@antv/l7';
+import React, { FunctionComponent, useEffect, useRef } from 'react';
 
 const Demo: FunctionComponent = () => {
+  const containerRef = useRef<HTMLDivElement | null>(null);
+
   useEffect(() => {
     const scene = new Scene({
       id: 'map',
@@ -15,7 +24,7 @@ const Demo: FunctionComponent = () => {
     });
 
     scene.on('loaded', () => {
-      function createTestControl(position: PositionName) {
+      function createTestControl(position: IControlOption['position']) {
         scene.addControl(
           new Zoom({
             position,
@@ -48,16 +57,27 @@ const Demo: FunctionComponent = () => {
       createTestControl('leftcenter');
       createTestControl('rightcenter');
       createTestControl('bottomcenter');
+
+      if (containerRef.current) {
+        scene.addControl(
+          new Logo({
+            position: containerRef.current,
+          }),
+        );
+      }
     });
   }, []);
   return (
-    <div
-      id="map"
-      style={{
-        height: '500px',
-        position: 'relative',
-      }}
-    />
+    <>
+      <div ref={containerRef} />
+      <div
+        id="map"
+        style={{
+          height: '500px',
+          position: 'relative',
+        }}
+      />
+    </>
   );
 };
 

packages/component/__tests__/control.spec.ts

@@ -1,6 +1,7 @@
 import { TestScene } from '@antv/l7-test-utils';
 import { DOM } from '@antv/l7-utils';
 import { Control } from '../src/control/baseControl';
+import { Zoom } from '../src/control/zoom';
 
 class TestControl extends Control {
   public onAdd(): HTMLElement {
@@ -65,4 +66,14 @@ describe('control', () => {
     expect(container.classList).toContain(className);
     expect(container.style.color).toEqual(color);
   });
+
+  // 测试自定义位置
+  it('position', () => {
+    const dom = document.createElement('div');
+    const zoom = new Zoom({
+      position: dom,
+    });
+    scene.addControl(zoom);
+    expect(dom.firstChild).toEqual(zoom.getContainer());
+  });
 });

packages/component/src/control/baseControl/control.ts

@@ -21,7 +21,7 @@ export { Control };
 
 export interface IControlOption {
   name: string;
-  position: PositionName;
+  position: PositionName | Element;
   className?: string;
   style?: string;
   [key: string]: any;
@@ -226,7 +226,7 @@ export default class Control<O extends IControlOption = IControlOption>
    * @param position
    */
   public setPosition(
-    position: PositionType | PositionName = PositionType.TOPLEFT,
+    position: PositionType | IControlOption['position'] = PositionType.TOPLEFT,
   ) {
     // 考虑组件的自动布局，需要销毁重建
     const controlService = this.controlService;
@@ -273,13 +273,18 @@ export default class Control<O extends IControlOption = IControlOption>
    * @protected
    */
   protected insertContainer() {
-    const container = this.container;
     const position = this.controlOption.position;
-    const corner = this.controlService.controlCorners[position];
-    if (position.indexOf('bottom') !== -1) {
-      corner.insertBefore(container, corner.firstChild);
+    const container = this.container;
+
+    if (position instanceof Element) {
+      position.appendChild(container);
     } else {
-      corner.appendChild(container);
+      const corner = this.controlService.controlCorners[position];
+      if (position.indexOf('bottom') !== -1) {
+        corner.insertBefore(container, corner.firstChild);
+      } else {
+        corner.appendChild(container);
+      }
     }
   }
 

packages/component/src/control/baseControl/popperControl.ts

@@ -52,7 +52,8 @@ export default class PopperControl<
     const position = option?.position ?? defaultOption.position!;
     return {
       ...super.getDefault(option),
-      popperPlacement: PopperPlacementMap[position],
+      popperPlacement:
+        position instanceof Element ? 'bottom' : PopperPlacementMap[position],
       popperTrigger: 'click',
     };
   }

packages/site/docs/api/component/control/control.zh.md

@@ -47,7 +47,7 @@ const onPositionChange = () => {
 
 ## 插槽
 
-当前 L7 中的控件支持插入到地图的**左上、左下、右上、右下、上、左、下、右**八个位置的控件插槽中，并且在同一插槽中的多个控件支持**横向**和**纵向**排列。
+当前 L7 中的控件支持插入到地图的**左上、左下、右上、右下、上、左、下、右**八个位置插槽或者用户自定义的 `DOM` 中，并且在同一地图插槽中，多个控件之间支持**横向**和**纵向**排列。
 
 在初始化所有的控件类时，可以传入 `position` 参数来设置控件对应的插槽以及排列方式。
 

packages/site/docs/common/control/api.md

@@ -19,5 +19,6 @@ export type Position =
   | 'topcenter'     // ↑ 上方中央，横向排列
   | 'bottomcenter'  // ↓ 下方中间，横向排列
   | 'leftcenter'    // ← 左边中间，纵向排列
-  | 'rightcenter';  // → 右边中间，纵向排列
+  | 'rightcenter'   // → 右边中间，纵向排列
+  | Element;        // 传入 DOM 作为当前控件的容器
 ```