添加guard 蒙层

keyBoard/Class/Guard/VC/KBGuideVC.m

@@ -11,6 +11,7 @@
 #import "KBGuideUserCell.h"
 #import "KBPermissionViewController.h"
 #import "KBKeyboardPermissionManager.h"
+#import "KBKeyboardMaskView.h"
 
 typedef NS_ENUM(NSInteger, KBGuideItemType) {
     KBGuideItemTypeTop = 0,   // 顶部固定卡片
@@ -32,6 +33,12 @@ typedef NS_ENUM(NSInteger, KBGuideItemType) {
 /// 记录上一次的输入法标识，避免重复提示
 @property (nonatomic, copy, nullable) NSString *kb_lastInputModeIdentifier;
 
+/// 当当前系统键盘不是自家键盘时展示的蒙层（带返回箭头 + GIF）
+@property (nonatomic, strong, nullable) KBKeyboardMaskView *kbKeyboardMaskView;
+
+/// 最近一次已知的键盘高度（用于初次展示蒙层时的 GIF 位置计算）
+@property (nonatomic, assign) CGFloat kb_currentKeyboardHeight;
+
 @end
 
 @implementation KBGuideVC
@@ -94,8 +101,7 @@ typedef NS_ENUM(NSInteger, KBGuideItemType) {
 
     // 提前创建并铺满权限引导页（默认隐藏），避免后续显示时出现布局进场感
     [self kb_preparePermissionOverlayIfNeeded];
-    
-   
+
 }
 
 - (void)dealloc {
@@ -194,6 +200,7 @@ typedef NS_ENUM(NSInteger, KBGuideItemType) {
     CGRect endFrame = [info[UIKeyboardFrameEndUserInfoKey] CGRectValue];
     CGFloat screenH = UIScreen.mainScreen.bounds.size.height;
     CGFloat kbHeight = MAX(0, screenH - endFrame.origin.y);
+    self.kb_currentKeyboardHeight = kbHeight;
 
     CGFloat safeBtm = 0;
     if (@available(iOS 11.0, *)) { safeBtm = self.view.safeAreaInsets.bottom; }
@@ -212,6 +219,13 @@ typedef NS_ENUM(NSInteger, KBGuideItemType) {
         // 键盘位置变化后，尝试检测是否发生了输入法切换
         [self kb_evaluateCurrentInputModeAndNotifyIfNeeded];
     }];
+
+    // 更新蒙层内部 GIF 与键盘的相对位置，保证不被遮挡
+    if (self.kbKeyboardMaskView) {
+        [self.kbKeyboardMaskView updateForKeyboardHeight:kbHeight
+                                               duration:duration
+                                                  curve:curve];
+    }
 }
 
 - (void)scrollToBottomAnimated:(BOOL)animated {
@@ -272,7 +286,9 @@ typedef NS_ENUM(NSInteger, KBGuideItemType) {
     self.kb_lastInputModeIdentifier = currId;
 
     BOOL isMine = [currId rangeOfString:KB_KEYBOARD_EXTENSION_BUNDLE_ID].location != NSNotFound;
-    [KBHUD showInfo:(isMine ? KBLocalized(@"是自己的键盘") : KBLocalized(@"❎不是自己的键盘"))];
+
+    // 根据是否为自家键盘，更新遮罩层显示/隐藏
+    [self kb_updateKeyboardMaskForIsMyKeyboard:isMine];
 }
 
 /// 当权限满足时，尽力激活输入框，从而触发键盘挂载与输入法检测
@@ -290,6 +306,76 @@ typedef NS_ENUM(NSInteger, KBGuideItemType) {
     });
 }
 
+/// 根据当前是否为自家键盘，展示/隐藏键盘指导蒙层
+- (void)kb_updateKeyboardMaskForIsMyKeyboard:(BOOL)isMine {
+    // 权限引导显示期间不再额外显示键盘蒙层
+    if (self.permVC && self.permVC.view.hidden == NO) {
+        if (self.kbKeyboardMaskView) {
+            self.kbKeyboardMaskView.hidden = YES;
+        }
+        return;
+    }
+
+    BOOL shouldShow = !isMine;
+
+    if (shouldShow) {
+        // 按需创建并添加蒙层
+        if (!self.kbKeyboardMaskView) {
+            KBKeyboardMaskView *mask = [[KBKeyboardMaskView alloc] initWithFrame:self.view.bounds];
+            __weak typeof(self) weakSelf = self;
+            mask.tapHandler = ^{
+                __strong typeof(weakSelf) self = weakSelf;
+                if (!self) return;
+                // 点击蒙层：在“激活/收起”之间切换 textField 的第一响应状态
+                if ([self.textField isFirstResponder]) {
+                    // 当前是第一响应者 -> 收起键盘
+                    [self.view endEditing:YES];
+                } else {
+                    // 当前不是第一响应者 -> 激活，弹出键盘
+                    [self.textField becomeFirstResponder];
+                }
+            };
+            // 左上角返回按钮：退出当前 KBGuideVC
+            [mask.backButton addTarget:self action:@selector(kb_onMaskBack) forControlEvents:UIControlEventTouchUpInside];
+
+            self.kbKeyboardMaskView = mask;
+
+            if (self.permVC && self.permVC.view.superview == self.view) {
+                // 确保权限页在最上层，键盘蒙层位于其下方
+                [self.view insertSubview:mask belowSubview:self.permVC.view];
+            } else {
+                [self.view addSubview:mask];
+            }
+            [mask mas_makeConstraints:^(MASConstraintMaker *make) {
+                make.edges.equalTo(self.view);
+            }];
+
+            // 创建时立即根据当前键盘高度调整 GIF 位置，避免首次展示被遮挡
+            [mask updateForKeyboardHeight:self.kb_currentKeyboardHeight
+                                 duration:0
+                                    curve:UIViewAnimationOptionCurveEaseInOut];
+        }
+    }
+
+    if (!self.kbKeyboardMaskView) return;
+
+    BOOL currentlyVisible = !self.kbKeyboardMaskView.hidden && self.kbKeyboardMaskView.alpha > 0.01;
+    if (shouldShow == currentlyVisible) return;
+
+    self.kbKeyboardMaskView.hidden = NO;
+    CGFloat targetAlpha = shouldShow ? 1.0 : 0.0;
+    [UIView animateWithDuration:0.25 animations:^{
+        self.kbKeyboardMaskView.alpha = targetAlpha;
+    } completion:^(BOOL finished) {
+        self.kbKeyboardMaskView.hidden = !shouldShow;
+    }];
+}
+
+/// 蒙层左上角返回按钮事件：让 KBGuideVC 退出
+- (void)kb_onMaskBack {
+    [self.navigationController popViewControllerAnimated:YES];
+}
+
 #pragma mark - UITableView
 
 - (NSInteger)tableView:(UITableView *)tableView numberOfRowsInSection:(NSInteger)section {