customer-chat-sdk 1.1.12 → 1.1.15

package/dist/customer-sdk.esm.js

@@ -1,7 +1,7 @@
 // 直接使用base64字符串，避免打包后路径问题
 const iconImage = 'data:image/png;base64,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';
 class IconManager {
-    constructor(position, debug = false, target) {
+    constructor(position, debug = false, target, options) {
         this.iconElement = null;
         this.badgeElement = null;
         this.onClickCallback = null;
@@ -42,10 +42,32 @@ class IconManager {
         this.pointerLeaveHandler = null;
         this.blurHandler = null;
         this.dragTimeoutId = null; // 拖动超时定时器
+        this.mouseLeaveTimeout = null; // 鼠标离开防抖定时器
+        this.pointerLeaveTimeout = null; // 指针离开防抖定时器
+        this.isStoppingDrag = false; // 防止 stopDrag 重复调用
+        // 侧边吸附相关状态
+        this.sideAttach = true; // 是否启用侧边吸附（默认 true）
+        this.sideHideRatio = 0.5; // 侧边吸附时的隐藏比例（默认 0.5，显示一半）
+        this.magnetic = true; // 是否启用磁性吸附（默认 true）
+        this.magneticDirection = 'x'; // 磁性吸附方向（默认 'x'）
+        this.margin = 10; // 边距（默认 10px）
+        this.isAttachedToSide = false; // 是否吸附到侧边
+        this.attachedSide = ''; // 吸附到哪一边
+        this.autoAttachDelay = 3000; // 自动吸附延迟时间（默认 3000ms，3秒）
+        this.autoAttachTimer = null; // 自动吸附定时器
         this.iconPosition = position || null;
         this.debug = debug;
         // 保存 target（可以是 HTMLElement 或字符串选择器）
         this.target = target || null;
+        // 侧边吸附配置
+        if (options) {
+            this.sideAttach = options.sideAttach !== undefined ? options.sideAttach : true;
+            this.sideHideRatio = options.sideHideRatio !== undefined ? options.sideHideRatio : 0.5;
+            this.magnetic = options.magnetic !== undefined ? options.magnetic : true;
+            this.magneticDirection = options.magneticDirection || 'x';
+            this.margin = options.margin !== undefined ? options.margin : 10;
+            this.autoAttachDelay = options.autoAttachDelay !== undefined ? options.autoAttachDelay : 3000;
+        }
     }
     /**
      * 显示悬浮图标
@@ -99,8 +121,42 @@ class IconManager {
         }
         else {
             // 默认位置：右下角
-            defaultStyle.bottom = '80px';
-            defaultStyle.right = '20px';
+            // 如果启用侧边吸附且没有指定位置，初始化时直接应用右边吸附样式
+            if (this.sideAttach && this.magnetic) {
+                const iconWidth = 30; // 图标宽度
+                const hideDistance = iconWidth * this.sideHideRatio; // 隐藏部分（在容器外）
+                // 右边吸附：图标右边缘对齐容器右边缘，隐藏部分在容器外
+                // right = -hideDistance，让图标向右移动 hideDistance，这样隐藏部分在容器外
+                defaultStyle.right = `-${hideDistance}px`; // 负值，让图标超出容器右边缘
+                defaultStyle.left = 'auto';
+                defaultStyle.bottom = '80px';
+                defaultStyle.transform = 'translateX(0)';
+                // 标记为已吸附到右边
+                this.isAttachedToSide = true;
+                this.attachedSide = 'right';
+            }
+            else {
+                defaultStyle.bottom = '80px';
+                defaultStyle.right = '20px';
+            }
+        }
+        // 如果侧边吸附已启用且已吸附，应用侧边吸附样式
+        if (this.sideAttach && this.isAttachedToSide && this.attachedSide) {
+            const iconWidth = 30; // 图标宽度
+            const hideDistance = iconWidth * this.sideHideRatio; // 隐藏部分（在容器外）
+            if (this.attachedSide === 'left') {
+                // 左边吸附：图标左边缘对齐容器左边缘，隐藏部分在容器外
+                defaultStyle.left = `-${hideDistance}px`; // 负值，让图标超出容器左边缘
+                defaultStyle.right = 'auto';
+                defaultStyle.transform = 'translateX(0)';
+            }
+            else if (this.attachedSide === 'right') {
+                // 右边吸附：图标右边缘对齐容器右边缘，隐藏部分在容器外
+                // right = -hideDistance，让图标向右移动 hideDistance，这样隐藏部分在容器外
+                defaultStyle.right = `-${hideDistance}px`; // 负值，让图标超出容器右边缘
+                defaultStyle.left = 'auto';
+                defaultStyle.transform = 'translateX(0)';
+            }
         }
         Object.assign(this.iconElement.style, defaultStyle);
         // 添加图标图片（直接使用base64字符串，避免打包后路径问题）
@@ -144,6 +200,36 @@ class IconManager {
         this.iconElement.appendChild(imgContainer);
         // 添加到目标元素（如果 target 是字符串，需要重新查找，因为可能在初始化时元素还不存在）
         const targetElement = this.getTargetElement();
+        // 确保目标容器有 overflow-x: hidden，防止图标超出边界时出现横向滚动条
+        // 注意：只在启用侧边吸附时才设置，避免影响其他场景
+        if (this.sideAttach && targetElement !== document.body) {
+            const computedStyle = window.getComputedStyle(targetElement);
+            const currentOverflowX = computedStyle.overflowX;
+            const currentOverflowY = computedStyle.overflowY;
+            // 如果当前 overflow-x 不是 hidden，设置 overflow-x: hidden
+            // 同时设置 overflow-y: hidden 或 auto，避免纵向滚动条
+            if (currentOverflowX !== 'hidden') {
+                // 保存原始 overflow 值（如果还没有保存）
+                if (!targetElement.dataset.originalOverflowX) {
+                    targetElement.dataset.originalOverflowX = currentOverflowX || 'visible';
+                    targetElement.dataset.originalOverflowY = currentOverflowY || 'visible';
+                }
+                // 设置 overflow-x: hidden，防止横向滚动条
+                targetElement.style.overflowX = 'hidden';
+                // 如果当前 overflow-y 是 visible，设置为 auto，避免纵向滚动条
+                // 如果已经是 auto 或 scroll，保持不变
+                if (currentOverflowY === 'visible') {
+                    targetElement.style.overflowY = 'auto';
+                }
+                if (this.debug) {
+                    console.log('[IconManager] Set overflow-x: hidden on target container', {
+                        target: this.target,
+                        originalOverflowX: currentOverflowX,
+                        originalOverflowY: currentOverflowY
+                    });
+                }
+            }
+        }
         if (targetElement) {
             targetElement.appendChild(this.iconElement);
         }
@@ -156,6 +242,72 @@ class IconManager {
         }
         // 设置拖动事件
         this.setupDragEvents();
+        // 如果启用磁性吸附且没有指定位置，初始化后自动吸附到右边（默认显示一半）
+        if (this.magnetic && !this.iconPosition) {
+            // 等待图标渲染完成后再执行吸附
+            setTimeout(() => {
+                if (this.iconElement) {
+                    // 先转换位置（从 right/bottom 到 left/top）
+                    const container = this.getTargetElement();
+                    if (container) {
+                        const containerRect = container.getBoundingClientRect();
+                        const iconWidth = this.iconElement.offsetWidth || 30;
+                        const iconHeight = this.iconElement.offsetHeight || 30;
+                        // 计算默认右下角位置对应的 left/top
+                        const defaultRight = 20; // 默认 right: 20px
+                        const defaultBottom = 80; // 默认 bottom: 80px
+                        // 转换为 left/top（相对于容器）
+                        const initialLeft = containerRect.width - iconWidth - defaultRight;
+                        const initialTop = containerRect.height - iconHeight - defaultBottom;
+                        // 临时设置位置，用于磁性吸附计算
+                        this.iconElement.style.left = `${initialLeft}px`;
+                        this.iconElement.style.top = `${initialTop}px`;
+                        this.iconElement.style.right = 'auto';
+                        this.iconElement.style.bottom = 'auto';
+                        // 如果启用侧边吸附，强制吸附到右边并显示一半
+                        if (this.sideAttach) {
+                            this.isAttachedToSide = true;
+                            this.attachedSide = 'right';
+                            const hideDistance = iconWidth * this.sideHideRatio; // 隐藏部分（在容器外）
+                            // right = -hideDistance，让图标向右移动 hideDistance，这样隐藏部分在容器外
+                            this.iconElement.style.right = `-${hideDistance}px`; // 负值，让图标超出容器右边缘
+                            this.iconElement.style.left = 'auto';
+                            this.iconElement.style.bottom = `${defaultBottom}px`; // 保持底部位置
+                            this.iconElement.style.top = 'auto';
+                            this.iconElement.style.transform = 'translateX(0)';
+                            this.iconElement.style.transition = 'all 0.3s ease';
+                            if (this.debug) {
+                                console.log('[IconManager] Auto side attach on init', {
+                                    isAttachedToSide: this.isAttachedToSide,
+                                    attachedSide: this.attachedSide,
+                                    hideDistance,
+                                    right: `-${hideDistance}px`
+                                });
+                            }
+                        }
+                        else {
+                            // 执行磁性吸附（不侧边吸附，只磁性吸附）
+                            this.magneticSnap();
+                            if (this.debug) {
+                                console.log('[IconManager] Auto magnetic snap on init', {
+                                    isAttachedToSide: this.isAttachedToSide,
+                                    attachedSide: this.attachedSide
+                                });
+                            }
+                        }
+                    }
+                }
+            }, 200); // 延迟 200ms，确保容器和图标都已渲染完成
+        }
+        // 启动自动吸附定时器（如果启用侧边吸附且当前未吸附）
+        // 注意：初始化时如果已经吸附到侧边，不会启动定时器
+        // 但如果图标从隐藏状态恢复显示，且未吸附，应该启动定时器
+        if (this.sideAttach && this.autoAttachDelay > 0 && !this.isAttachedToSide) {
+            // 延迟启动，确保图标已经完全渲染
+            setTimeout(() => {
+                this.startAutoAttachTimer();
+            }, 300); // 延迟 300ms，确保初始化吸附逻辑已完成
+        }
         if (this.debug) {
             console.log('CustomerSDK icon displayed');
         }
@@ -172,6 +324,8 @@ class IconManager {
     hide() {
         // 清理拖动事件
         this.cleanupDragEvents();
+        // 清除自动吸附定时器
+        this.clearAutoAttachTimer();
         if (this.iconElement) {
             // 在隐藏前保存当前位置（如果图标已经被拖动过）
             const computedStyle = window.getComputedStyle(this.iconElement);
@@ -233,6 +387,110 @@ class IconManager {
     setStyle(style) {
         // 现在样式写死，不做处理
     }
+    /**
+     * 启动自动吸附定时器
+     */
+    startAutoAttachTimer() {
+        // 清除之前的定时器
+        this.clearAutoAttachTimer();
+        // 如果已经吸附到侧边，不需要启动定时器
+        if (this.isAttachedToSide) {
+            return;
+        }
+        this.autoAttachTimer = window.setTimeout(() => {
+            if (this.iconElement && !this.isDragging && !this.dragStarted) {
+                // 执行自动吸附到侧边
+                this.autoAttachToSide();
+            }
+            this.autoAttachTimer = null;
+        }, this.autoAttachDelay);
+        if (this.debug) {
+            console.log(`[IconManager] Auto attach timer started, will attach in ${this.autoAttachDelay}ms`);
+        }
+    }
+    /**
+     * 清除自动吸附定时器
+     */
+    clearAutoAttachTimer() {
+        if (this.autoAttachTimer !== null) {
+            window.clearTimeout(this.autoAttachTimer);
+            this.autoAttachTimer = null;
+            if (this.debug) {
+                console.log('[IconManager] Auto attach timer cleared');
+            }
+        }
+    }
+    /**
+     * 自动吸附到侧边
+     */
+    autoAttachToSide() {
+        if (!this.iconElement || !this.sideAttach)
+            return;
+        try {
+            const container = this.getTargetElement();
+            if (!container)
+                return;
+            const containerRect = container.getBoundingClientRect();
+            const iconWidth = this.iconElement.offsetWidth || 30;
+            // 获取当前图标位置
+            const computedStyle = window.getComputedStyle(this.iconElement);
+            const currentLeft = parseFloat(computedStyle.left) || 0;
+            const currentRight = computedStyle.right;
+            // 判断应该吸附到哪一边（根据当前位置）
+            const containerWidth = containerRect.width;
+            let shouldAttachToRight = true;
+            // 如果使用 right 定位，计算实际 left 位置
+            if (currentRight !== 'auto' && currentRight !== '') {
+                const rightValue = parseFloat(currentRight);
+                if (!isNaN(rightValue)) {
+                    const actualLeft = containerWidth - iconWidth - rightValue;
+                    shouldAttachToRight = actualLeft >= containerWidth / 2;
+                }
+            }
+            else {
+                shouldAttachToRight = currentLeft >= containerWidth / 2;
+            }
+            if (shouldAttachToRight) {
+                // 吸附到右边
+                this.isAttachedToSide = true;
+                this.attachedSide = 'right';
+                const hideDistance = iconWidth * this.sideHideRatio;
+                this.iconElement.style.right = `-${hideDistance}px`;
+                this.iconElement.style.left = 'auto';
+            }
+            else {
+                // 吸附到左边
+                this.isAttachedToSide = true;
+                this.attachedSide = 'left';
+                const hideDistance = iconWidth * this.sideHideRatio;
+                this.iconElement.style.left = `-${hideDistance}px`;
+                this.iconElement.style.right = 'auto';
+            }
+            // 保持 Y 轴位置不变
+            const computedStyleAfter = window.getComputedStyle(this.iconElement);
+            if (computedStyleAfter.top !== 'auto' && computedStyleAfter.top !== '') {
+                this.iconElement.style.top = computedStyleAfter.top;
+                this.iconElement.style.bottom = 'auto';
+            }
+            else if (computedStyleAfter.bottom !== 'auto' && computedStyleAfter.bottom !== '') {
+                this.iconElement.style.bottom = computedStyleAfter.bottom;
+                this.iconElement.style.top = 'auto';
+            }
+            this.iconElement.style.transform = 'translateX(0)';
+            this.iconElement.style.transition = 'all 0.3s ease';
+            if (this.debug) {
+                console.log('[IconManager] Auto attached to side', {
+                    attachedSide: this.attachedSide,
+                    hideDistance: iconWidth * this.sideHideRatio
+                });
+            }
+        }
+        catch (error) {
+            if (this.debug) {
+                console.error('[IconManager] Error in autoAttachToSide:', error);
+            }
+        }
+    }
     /**
      * 设置点击回调
      */
@@ -300,6 +558,37 @@ class IconManager {
     startDrag(e) {
         if (!this.iconElement || !this.isClickEnabled)
             return;
+        // 清除自动吸附定时器（用户开始拖动）
+        this.clearAutoAttachTimer();
+        // 如果正在停止拖动，等待完成后再允许新的拖动
+        if (this.isStoppingDrag) {
+            if (this.debug) {
+                console.warn('[IconManager] startDrag called while stopping, ignoring');
+            }
+            return;
+        }
+        // 如果已经在拖动中，忽略新的拖动开始事件（防止重复调用）
+        // 注意：只检查实际的拖动状态，不检查可能残留的资源（这些应该在 cleanup 中清理）
+        if (this.isDragging || this.dragStarted) {
+            if (this.debug) {
+                console.warn('[IconManager] startDrag called but already dragging, ignoring', {
+                    isDragging: this.isDragging,
+                    dragStarted: this.dragStarted
+                });
+            }
+            return;
+        }
+        // 如果发现残留的资源，先清理它们（防御性编程）
+        if (this.dragTimeoutId !== null || this.activeDetectionRafId !== null || this.rafId !== null) {
+            if (this.debug) {
+                console.warn('[IconManager] startDrag found leftover resources, cleaning up', {
+                    hasTimeout: this.dragTimeoutId !== null,
+                    hasActiveDetection: this.activeDetectionRafId !== null,
+                    hasRaf: this.rafId !== null
+                });
+            }
+            this.cleanupDragEvents();
+        }
         // 检查事件目标：如果是 iframe 相关元素，不处理
         const target = e.target;
         if (target && (target.tagName === 'IFRAME' ||
@@ -364,32 +653,59 @@ class IconManager {
             }
             // 添加处理 iframe 上事件丢失的机制
             // 1. 监听 mouseleave 和 pointerleave 事件（鼠标离开窗口时停止拖动）
+            // 注意：这些事件可能会在拖动过程中多次触发，需要添加防抖机制
             this.mouseLeaveHandler = (e) => {
                 // 只有当鼠标真正离开窗口时才停止拖动
                 if (!e.relatedTarget && (e.clientY <= 0 || e.clientX <= 0 ||
                     e.clientX >= window.innerWidth || e.clientY >= window.innerHeight)) {
-                    if (this.debug) {
-                        console.log('Mouse left window, stopping drag');
+                    // 添加防抖，避免重复触发
+                    if (this.mouseLeaveTimeout) {
+                        clearTimeout(this.mouseLeaveTimeout);
                     }
-                    this.stopDrag();
+                    this.mouseLeaveTimeout = window.setTimeout(() => {
+                        if ((this.isDragging || this.dragStarted) && !this.isStoppingDrag) {
+                            if (this.debug) {
+                                console.log('[IconManager] Mouse left window, stopping drag');
+                            }
+                            this.stopDrag();
+                        }
+                        this.mouseLeaveTimeout = null;
+                    }, 50); // 50ms 防抖
                 }
             };
             this.pointerLeaveHandler = (e) => {
                 // 只有当指针真正离开窗口时才停止拖动
                 if (!e.relatedTarget && (e.clientY <= 0 || e.clientX <= 0 ||
                     e.clientX >= window.innerWidth || e.clientY >= window.innerHeight)) {
-                    if (this.debug) {
-                        console.log('Pointer left window, stopping drag');
+                    // 添加防抖，避免重复触发
+                    if (this.pointerLeaveTimeout) {
+                        clearTimeout(this.pointerLeaveTimeout);
                     }
-                    this.stopDrag();
+                    this.pointerLeaveTimeout = window.setTimeout(() => {
+                        if ((this.isDragging || this.dragStarted) && !this.isStoppingDrag) {
+                            if (this.debug) {
+                                console.log('[IconManager] Pointer left window, stopping drag');
+                            }
+                            this.stopDrag();
+                        }
+                        this.pointerLeaveTimeout = null;
+                    }, 50); // 50ms 防抖
                 }
             };
             document.addEventListener('mouseleave', this.mouseLeaveHandler);
             document.addEventListener('pointerleave', this.pointerLeaveHandler);
             // 2. 监听 blur 事件（窗口失去焦点时停止拖动）
             this.blurHandler = () => {
+                // 如果已经在停止拖动，直接返回
+                if (this.isStoppingDrag) {
+                    return;
+                }
+                // 检查是否真的在拖动中
+                if (!this.isDragging && !this.dragStarted) {
+                    return;
+                }
                 if (this.debug) {
-                    console.log('Window lost focus, stopping drag');
+                    console.log('[IconManager] Window lost focus, stopping drag');
                 }
                 this.stopDrag();
             };
@@ -529,6 +845,14 @@ class IconManager {
                 // 开始真正的拖拽
                 this.dragStarted = true;
                 this.isDragging = true;
+                // 拖拽开始时重置侧边吸附状态
+                if (this.isAttachedToSide) {
+                    this.isAttachedToSide = false;
+                    this.attachedSide = '';
+                    if (this.iconElement) {
+                        this.iconElement.style.transform = '';
+                    }
+                }
                 // 如果是第一次拖动，需要转换位置（从 right/bottom 到 left/top）
                 const computedStyle = window.getComputedStyle(this.iconElement);
                 if (computedStyle.right !== 'auto' || computedStyle.bottom !== 'auto') {
@@ -629,6 +953,21 @@ class IconManager {
      * 停止拖动
      */
     stopDrag(_e) {
+        // 防止重复调用
+        if (this.isStoppingDrag) {
+            if (this.debug) {
+                console.warn('[IconManager] stopDrag already in progress, ignoring duplicate call');
+            }
+            return;
+        }
+        // 如果已经停止且没有相关资源，直接返回
+        if (!this.isDragging && !this.dragStarted && !this.dragTimeoutId && !this.activeDetectionRafId) {
+            if (this.debug) {
+                console.warn('[IconManager] stopDrag called but not dragging, ignoring');
+            }
+            return;
+        }
+        this.isStoppingDrag = true;
         const stopReason = this.isDragging ? 'drag_stopped' : 'not_dragging';
         const finalPosition = this.iconElement ? {
             left: this.iconElement.style.left,
@@ -637,9 +976,16 @@ class IconManager {
                 ? { left: window.getComputedStyle(this.iconElement).left, top: window.getComputedStyle(this.iconElement).top }
                 : null
         } : null;
+        // 立即清理事件监听器，防止后续事件触发
         this.cleanupDragEvents();
-        if (!this.iconElement)
+        if (!this.iconElement) {
+            // 即使没有 iconElement，也要重置状态，确保可以再次拖动
+            this.hasMoved = false;
+            this.isDragging = false;
+            this.dragStarted = false;
+            this.isStoppingDrag = false;
             return;
+        }
         // 恢复样式
         this.iconElement.style.transition = 'transform 0.2s ease';
         this.iconElement.style.cursor = 'pointer';
@@ -659,6 +1005,10 @@ class IconManager {
         }
         // 先保存点击状态，然后重置拖动状态
         const wasClick = isValidClick;
+        // 如果真正拖动过，执行磁性吸附
+        if (this.dragStarted && this.magnetic && this.iconElement) {
+            this.magneticSnap();
+        }
         // 如果真正拖动过，保存当前位置到 iconPosition
         if (this.dragStarted && this.isDragging && this.iconElement) {
             const computedStyle = window.getComputedStyle(this.iconElement);
@@ -683,6 +1033,11 @@ class IconManager {
         this.hasMoved = false;
         this.isDragging = false;
         this.dragStarted = false;
+        this.isStoppingDrag = false; // 重置停止标志
+        // 如果拖动后没有吸附到侧边，启动自动吸附定时器
+        if (!this.isAttachedToSide && this.sideAttach && this.autoAttachDelay > 0) {
+            this.startAutoAttachTimer();
+        }
         if (wasClick) {
             // 是点击，触发点击事件
             // 延迟触发，确保拖动状态已完全重置，并且没有新的拖动开始
@@ -709,9 +1064,10 @@ class IconManager {
             console.log('[IconManager] Starting active detection mechanism');
         }
         const checkMousePosition = () => {
-            if (!this.isDragging) {
+            // 检查是否还在拖动中，如果不在拖动中或正在停止，则停止检测
+            if (!this.isDragging || this.isStoppingDrag) {
                 if (this.debug) {
-                    console.log('[IconManager] Active detection stopped (drag ended)');
+                    console.log('[IconManager] Active detection stopped (drag ended or stopping)');
                 }
                 this.activeDetectionRafId = null;
                 return;
@@ -719,15 +1075,19 @@ class IconManager {
             // 检查是否长时间没有收到 mousemove 事件（超过 50ms）
             const now = Date.now();
             const timeSinceLastMove = now - this.lastMousePosition.timestamp;
+            // 如果超过 50ms 没有收到事件，进行检测
             if (timeSinceLastMove > 50) {
                 // 长时间没有收到事件，可能鼠标已经进入 iframe
                 // 使用最后记录的鼠标位置进行检测
                 const clientX = this.lastMousePosition.x;
                 const clientY = this.lastMousePosition.y;
-                if (this.debug) {
-                    console.log(`[IconManager] Active detection: No mousemove event for ${timeSinceLastMove}ms`, {
+                if (this.debug && timeSinceLastMove > 100) {
+                    // 只在超过 100ms 时记录警告，避免日志过多
+                    console.warn(`[IconManager] Active detection: No mousemove event for ${timeSinceLastMove}ms`, {
                         lastMousePosition: { x: clientX, y: clientY },
-                        timestamp: this.lastMousePosition.timestamp
+                        timestamp: this.lastMousePosition.timestamp,
+                        isDragging: this.isDragging,
+                        dragStarted: this.dragStarted
                     });
                 }
                 // 更新 iframe 缓存（更频繁，每帧更新）
@@ -799,6 +1159,7 @@ class IconManager {
             document.removeEventListener('touchend', this.stopDragHandler);
         }
         // 清理处理 iframe 事件丢失的监听器
+        // 注意：必须先移除监听器，再清理防抖定时器，防止事件在清理过程中触发
         if (this.mouseLeaveHandler) {
             document.removeEventListener('mouseleave', this.mouseLeaveHandler);
             this.mouseLeaveHandler = null;
@@ -811,6 +1172,15 @@ class IconManager {
             window.removeEventListener('blur', this.blurHandler);
             this.blurHandler = null;
         }
+        // 清理防抖定时器（在移除监听器之后）
+        if (this.mouseLeaveTimeout !== null) {
+            window.clearTimeout(this.mouseLeaveTimeout);
+            this.mouseLeaveTimeout = null;
+        }
+        if (this.pointerLeaveTimeout !== null) {
+            window.clearTimeout(this.pointerLeaveTimeout);
+            this.pointerLeaveTimeout = null;
+        }
         // 清理超时定时器
         if (this.dragTimeoutId !== null) {
             window.clearTimeout(this.dragTimeoutId);
@@ -821,13 +1191,31 @@ class IconManager {
             cancelAnimationFrame(this.rafId);
             this.rafId = null;
         }
-        // 清理主动检测机制
+        // 清理主动检测机制（必须在最后，确保完全清理）
         this.stopActiveDetection();
+        // 确保 activeDetectionRafId 被清理（双重保险）
+        if (this.activeDetectionRafId !== null) {
+            if (this.debug) {
+                console.warn('[IconManager] Active detection RAF ID still exists, force cleaning');
+            }
+            cancelAnimationFrame(this.activeDetectionRafId);
+            this.activeDetectionRafId = null;
+        }
         // 清理缓存
         this.cachedContainer = null;
         this.cachedContainerRect = null;
         this.cachedIframes = []; // 清理 iframe 缓存
         this.pendingPosition.needsUpdate = false;
+        if (this.debug) {
+            console.log('[IconManager] Cleanup completed', {
+                isDragging: this.isDragging,
+                dragStarted: this.dragStarted,
+                isStoppingDrag: this.isStoppingDrag,
+                hasTimeout: this.dragTimeoutId !== null,
+                hasActiveDetection: this.activeDetectionRafId !== null,
+                hasRaf: this.rafId !== null
+            });
+        }
     }
     /**
      * 处理点击事件
@@ -837,6 +1225,8 @@ class IconManager {
         if (!this.isClickEnabled) {
             return;
         }
+        // 清除自动吸附定时器（用户有操作）
+        this.clearAutoAttachTimer();
         if (this.onClickCallback) {
             this.onClickCallback();
         }
@@ -879,6 +1269,142 @@ class IconManager {
             this.iconElement.style.cursor = 'pointer';
         }
     }
+    /**
+     * 磁性吸附
+     */
+    magneticSnap() {
+        if (!this.iconElement)
+            return;
+        try {
+            const container = this.getTargetElement();
+            if (!container)
+                return;
+            const containerRect = container.getBoundingClientRect();
+            const iconWidth = this.iconElement.offsetWidth || 30;
+            const iconHeight = this.iconElement.offsetHeight || 30;
+            // 获取当前图标位置
+            const computedStyle = window.getComputedStyle(this.iconElement);
+            const currentLeft = parseFloat(computedStyle.left) || 0;
+            const currentTop = parseFloat(computedStyle.top) || 0;
+            let newX = currentLeft;
+            let newY = currentTop;
+            // X 轴磁性吸附
+            if (this.magneticDirection === 'x' || this.magneticDirection === 'both') {
+                const containerWidth = containerRect.width;
+                const centerX = containerWidth / 2;
+                if (currentLeft < centerX) {
+                    // 吸附到左边
+                    newX = this.margin;
+                    // 侧边吸附逻辑
+                    if (this.sideAttach && currentLeft < iconWidth / 2) {
+                        this.isAttachedToSide = true;
+                        this.attachedSide = 'left';
+                        // 计算隐藏部分：图标宽度 * sideHideRatio
+                        // 例如：30px * 0.5 = 15px 隐藏，15px 显示
+                        const hideDistance = iconWidth * this.sideHideRatio;
+                        // 图标左边缘对齐容器左边缘，隐藏部分在容器外
+                        newX = -hideDistance; // 负值，让图标超出容器左边缘
+                    }
+                    else {
+                        this.isAttachedToSide = false;
+                        this.attachedSide = '';
+                    }
+                }
+                else {
+                    // 吸附到右边
+                    newX = containerWidth - iconWidth - this.margin;
+                    // 侧边吸附逻辑：如果启用侧边吸附，默认吸附到右边并显示一半
+                    if (this.sideAttach) {
+                        // 如果靠近右边（距离右边 < 图标宽度的一半），或者从默认位置初始化
+                        // 默认位置（右下角）应该自动侧边吸附
+                        const distanceFromRight = containerWidth - currentLeft - iconWidth;
+                        if (distanceFromRight < iconWidth / 2 ||
+                            (isNaN(currentLeft) || currentLeft === 0) ||
+                            currentLeft >= containerWidth - iconWidth - this.margin - iconWidth / 2) {
+                            this.isAttachedToSide = true;
+                            this.attachedSide = 'right';
+                            // 计算显示部分：图标宽度 * (1 - sideHideRatio)
+                            // 例如：30px * (1 - 0.5) = 15px 显示，15px 隐藏
+                            const visibleWidth = iconWidth * (1 - this.sideHideRatio);
+                            // 图标右边缘对齐容器右边缘，但只显示 visibleWidth
+                            newX = containerWidth - visibleWidth;
+                        }
+                        else {
+                            this.isAttachedToSide = false;
+                            this.attachedSide = '';
+                        }
+                    }
+                    else {
+                        this.isAttachedToSide = false;
+                        this.attachedSide = '';
+                    }
+                }
+            }
+            // Y 轴磁性吸附
+            if (this.magneticDirection === 'y' || this.magneticDirection === 'both') {
+                const containerHeight = containerRect.height;
+                const centerY = containerHeight / 2;
+                if (currentTop < centerY) {
+                    newY = this.margin; // 吸附到上边
+                }
+                else {
+                    newY = containerHeight - iconHeight - this.margin; // 吸附到下边
+                }
+            }
+            // 应用新位置
+            // 如果侧边吸附到右边，使用 right 属性（负值），让图标超出容器右边缘
+            if (this.isAttachedToSide && this.attachedSide === 'right') {
+                const hideDistance = iconWidth * this.sideHideRatio; // 隐藏部分（在容器外）
+                this.iconElement.style.right = `-${hideDistance}px`; // 负值，让图标超出容器右边缘
+                this.iconElement.style.left = 'auto';
+            }
+            else if (this.isAttachedToSide && this.attachedSide === 'left') {
+                // 左边吸附使用 left（负值），让图标超出容器左边缘
+                const hideDistance = iconWidth * this.sideHideRatio;
+                this.iconElement.style.left = `-${hideDistance}px`;
+                this.iconElement.style.right = 'auto';
+            }
+            else {
+                // 正常位置使用 left
+                this.iconElement.style.left = `${newX}px`;
+                this.iconElement.style.right = 'auto';
+            }
+            this.iconElement.style.top = `${newY}px`;
+            this.iconElement.style.bottom = 'auto';
+            // 如果侧边吸附，应用 transform
+            if (this.isAttachedToSide && this.attachedSide) {
+                this.iconElement.style.transform = 'translateX(0)';
+                this.iconElement.style.transition = 'all 0.3s ease';
+            }
+            else {
+                this.iconElement.style.transform = '';
+            }
+            // 保存位置（如果是右边吸附，保存为 right 值，否则保存为 left 值）
+            if (this.isAttachedToSide && this.attachedSide === 'right') {
+                // 右边吸附时，不保存到 iconPosition（因为使用的是 right 属性）
+                // 或者可以保存一个特殊标记
+                this.iconPosition = null; // 清除位置，让下次显示时重新计算
+            }
+            else {
+                this.iconPosition = {
+                    x: newX,
+                    y: newY
+                };
+            }
+            if (this.debug) {
+                console.log('[IconManager] Magnetic snap applied', {
+                    newPosition: { x: newX, y: newY },
+                    isAttachedToSide: this.isAttachedToSide,
+                    attachedSide: this.attachedSide
+                });
+            }
+        }
+        catch (error) {
+            if (this.debug) {
+                console.error('[IconManager] Error in magneticSnap:', error);
+            }
+        }
+    }
     /**
      * 获取目标元素（支持动态查找）
      */
@@ -21342,7 +21868,14 @@ class CustomerServiceSDK {
                         console.log('Icon config changed, recreating icon manager');
                     }
                 }
-                this.iconManager = new IconManager(iconPosition, this.debug, iconTarget);
+                this.iconManager = new IconManager(iconPosition, this.debug, iconTarget, {
+                    sideAttach: options?.sideAttach !== undefined ? options.sideAttach : true,
+                    sideHideRatio: options?.sideHideRatio !== undefined ? options.sideHideRatio : 0.5,
+                    magnetic: options?.magnetic !== undefined ? options.magnetic : true,
+                    magneticDirection: options?.magneticDirection || 'x',
+                    margin: options?.margin !== undefined ? options.margin : 10,
+                    autoAttachDelay: options?.autoAttachDelay !== undefined ? options.autoAttachDelay : 3000
+                });
                 await this.iconManager.show();
                 // 保存新的配置
                 this.lastIconConfig = { position: iconPosition, target: iconTarget };
@@ -21351,7 +21884,14 @@ class CustomerServiceSDK {
                 // 配置没变化，保留图标管理器（避免闪烁）
                 if (!this.iconManager) {
                     // 如果不存在，创建新的
-                    this.iconManager = new IconManager(iconPosition, this.debug, iconTarget);
+                    this.iconManager = new IconManager(iconPosition, this.debug, iconTarget, {
+                        sideAttach: options?.sideAttach !== undefined ? options.sideAttach : true,
+                        sideHideRatio: options?.sideHideRatio !== undefined ? options.sideHideRatio : 0.5,
+                        magnetic: options?.magnetic !== undefined ? options.magnetic : true,
+                        magneticDirection: options?.magneticDirection || 'x',
+                        margin: options?.margin !== undefined ? options.margin : 10,
+                        autoAttachDelay: options?.autoAttachDelay !== undefined ? options.autoAttachDelay : 3000
+                    });
                     await this.iconManager.show();
                 }
                 else {