添加guard 蒙层

keyBoard/Class/Guard/V/KBKeyboardMaskView.h

@@ -0,0 +1,29 @@
+//
+//  KBKeyboardMaskView.h
+//  keyBoard
+//
+//  Created by Mac on 2025/11/27.
+//
+
+#import <UIKit/UIKit.h>
+#import <FLAnimatedImage/FLAnimatedImage.h>
+
+NS_ASSUME_NONNULL_BEGIN
+/// 覆盖在 KBGuideVC 上方的“请选择自家键盘”蒙层
+/// - 左上角：返回箭头
+/// - 中间：播放 GIF 的区域（宽=屏幕宽，高=300）
+/// - 点击任意空白区域：回调给外部（用于激活输入框）
+@interface KBKeyboardMaskView : UIView
+@property (nonatomic, strong, readonly) UIButton *backButton;
+@property (nonatomic, strong, readonly) FLAnimatedImageView *gifView;
+
+/// 点击蒙层空白时回调（不包括 backButton）
+@property (nonatomic, copy) void (^tapHandler)(void);
+
+/// 更新内部 GIF 与键盘的相对位置，保证不被遮挡
+- (void)updateForKeyboardHeight:(CGFloat)kbHeight
+                       duration:(NSTimeInterval)duration
+                          curve:(UIViewAnimationOptions)curve;
+@end
+
+NS_ASSUME_NONNULL_END

keyBoard/Class/Guard/V/KBKeyboardMaskView.m

@@ -0,0 +1,125 @@
+//
+//  KBKeyboardMaskView.m
+//  keyBoard
+//
+//  Created by Mac on 2025/11/27.
+//
+
+#import "KBKeyboardMaskView.h"
+
+@interface KBKeyboardMaskView ()
+@property (nonatomic, strong) UIButton *backButton;
+@property (nonatomic, strong) FLAnimatedImageView *gifView;
+@property (nonatomic, assign) CGFloat keyboardHeight;
+@end
+
+@implementation KBKeyboardMaskView
+
+- (instancetype)initWithFrame:(CGRect)frame {
+    self = [super initWithFrame:frame];
+    if (!self) return nil;
+    self.backgroundColor = [[UIColor blackColor] colorWithAlphaComponent:0.55];
+    self.userInteractionEnabled = YES;
+
+    // 返回按钮
+    _backButton = [UIButton buttonWithType:UIButtonTypeCustom];
+    UIImage *backImg = [UIImage imageNamed:@"close_white2_icon"];
+    [_backButton setImage:backImg forState:UIControlStateNormal];
+    [self addSubview:_backButton];
+
+    [_backButton mas_makeConstraints:^(MASConstraintMaker *make) {
+        make.left.equalTo(self).offset(9);
+        if (@available(iOS 11.0, *)) {
+            make.top.equalTo(self.mas_safeAreaLayoutGuideTop).offset(4);
+        } else {
+            make.top.equalTo(self).offset(40);
+        }
+        make.width.height.mas_equalTo(40);
+    }];
+
+    // GIF 区域
+    _gifView = [FLAnimatedImageView new];
+    _gifView.contentMode = UIViewContentModeScaleAspectFit;
+    _gifView.clipsToBounds = YES;
+    [self addSubview:_gifView];
+
+    // 尺寸固定：宽=屏幕宽，高=300；位置在 layoutSubviews 里根据键盘高度动态计算
+    CGFloat screenW = UIScreen.mainScreen.bounds.size.width;
+    [_gifView mas_makeConstraints:^(MASConstraintMaker *make) {
+        make.centerX.equalTo(self);
+        make.width.mas_equalTo(screenW);
+        make.height.mas_equalTo(300);
+        // 竖直方向不在这里约束，由 layoutSubviews 手动布局
+    }];
+
+    // 整个蒙层点击：激活输入框
+    UITapGestureRecognizer *tap = [[UITapGestureRecognizer alloc] initWithTarget:self action:@selector(onTapMask:)];
+    [self addGestureRecognizer:tap];
+
+    // 加载 GIF 资源（占位名，可按需更换为实际文件名）
+    NSString *gifPath = [[NSBundle mainBundle] pathForResource:@"kb_guide_keyboard" ofType:@"gif"];
+    if (gifPath.length > 0) {
+        NSData *data = [NSData dataWithContentsOfFile:gifPath];
+        if (data.length > 0) {
+            FLAnimatedImage *img = [FLAnimatedImage animatedImageWithGIFData:data];
+            _gifView.animatedImage = img;
+        }
+    }
+
+    return self;
+}
+
+- (void)layoutSubviews {
+    [super layoutSubviews];
+
+    // 根据键盘高度，保证 GIF 不被遮挡：
+    // - 无键盘：居中显示；
+    // - 有键盘：底部距离键盘上方 20pt，若空间不足则向上顶到顶部预留的 safe 区域。
+    CGFloat viewH = CGRectGetHeight(self.bounds);
+    CGFloat gifH = 300.0;
+    CGFloat topMargin = 80.0; // 预留给返回按钮和标题等
+    CGFloat bottomMargin = 20.0;
+
+    CGFloat y = 0;
+    if (self.keyboardHeight <= 0) {
+        // 无键盘：垂直居中
+        y = (viewH - gifH) * 0.5;
+        if (y < topMargin) y = topMargin;
+    } else {
+        CGFloat maxBottom = viewH - self.keyboardHeight - bottomMargin;
+        y = maxBottom - gifH;
+        if (y < topMargin) y = topMargin;
+    }
+
+    CGRect frame = self.gifView.frame;
+    frame.origin.y = y;
+    self.gifView.frame = frame;
+}
+
+- (void)onTapMask:(UITapGestureRecognizer *)gr {
+    CGPoint p = [gr locationInView:self];
+    // 如果点在返回按钮区域内，则不走 tapHandler（交由按钮自己的事件处理）
+    if (CGRectContainsPoint(self.backButton.frame, p)) {
+        return;
+    }
+    if (self.tapHandler) {
+        self.tapHandler();
+    }
+}
+
+- (void)updateForKeyboardHeight:(CGFloat)kbHeight
+                       duration:(NSTimeInterval)duration
+                          curve:(UIViewAnimationOptions)curve {
+    self.keyboardHeight = MAX(kbHeight, 0);
+    // 触发布局刷新，以便在 layoutSubviews 里根据最新键盘高度重算 gifView 的 Y 值
+    [self setNeedsLayout];
+    [UIView animateWithDuration:duration
+                          delay:0
+                        options:curve
+                     animations:^{
+                         [self layoutIfNeeded];
+                     }
+                     completion:nil];
+}
+
+@end

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 {