【亲测免费】NJKWebViewProgress 项目常见问题解决方案

2026-01-29 11:43:46作者：廉彬冶Miranda

还在为 iOS UIWebView 进度条显示问题而烦恼吗？作为 iOS 开发中处理 WebView 加载进度的经典库，NJKWebViewProgress 在实际使用中确实会遇到各种问题。本文基于深度源码分析和实际项目经验，为你提供一整套解决方案。

📋 问题速查表

问题类型	症状表现	解决方案
代理冲突	进度回调不触发	正确设置代理链
进度条闪烁	进度反复跳动	检查 readyState 判断逻辑
内存泄漏	页面不释放	使用 weak 引用
导航栏适配	进度条位置错误	自动布局适配
WKWebView 兼容	无法使用	桥接方案

🔧 核心问题深度解析

1. 代理设置冲突问题

问题现象：进度回调完全不触发，或者部分回调失效

根本原因：NJKWebViewProgress 采用代理转发机制，如果设置顺序不当会导致代理链断裂。

// ❌ 错误写法 - 会导致代理链断裂
_webView.delegate = self;
_progressProxy = [[NJKWebViewProgress alloc] init];

// ✅ 正确写法 - 建立完整的代理链
_progressProxy = [[NJKWebViewProgress alloc] init];
_webView.delegate = _progressProxy;  // 第一步：设置主代理
_progressProxy.webViewProxyDelegate = self;  // 第二步：设置转发代理
_progressProxy.progressDelegate = self;  // 第三步：设置进度代理

解决方案流程图：

flowchart TD
    A[UIWebView 事件] --> B[NJKWebViewProgress]
    B --> C{事件类型判断}
    C -->|进度相关| D[进度回调处理]
    C -->|其他代理| E[转发给 webViewProxyDelegate]
    D --> F[调用 progressDelegate]
    E --> G[原始代理对象]

2. 进度条闪烁问题

问题现象：进度条在加载过程中反复跳动，用户体验差

技术原理分析：NJKWebViewProgress 通过监控 document.readyState 状态来判断加载阶段：

const float NJKInitialProgressValue = 0.1f;    // 初始进度
const float NJKInteractiveProgressValue = 0.5f; // 文档解析完成
const float NJKFinalProgressValue = 0.9f;      // 资源加载中

解决方案：重写进度更新逻辑，添加平滑过渡

// 平滑进度更新实现
- (void)webViewProgress:(NJKWebViewProgress *)webViewProgress 
         updateProgress:(float)progress 
{
    // 添加进度平滑过渡
    [UIView animateWithDuration:0.3 delay:0 options:UIViewAnimationOptionCurveEaseOut animations:^{
        [_progressView setProgress:progress animated:YES];
    } completion:nil];
    
    // 根据进度阶段显示不同状态
    if (progress >= NJKFinalProgressValue) {
        self.title = @"加载中...";
    } else if (progress >= NJKInteractiveProgressValue) {
        self.title = @"解析完成";
    }
}

3. 内存泄漏问题

问题现象：ViewController 无法正常释放，内存持续增长

根本原因：代理循环引用，特别是使用 block 时的强引用

// ❌ 危险写法 - 可能造成循环引用
__weak typeof(self) weakSelf = self;
progressProxy.progressBlock = ^(float progress) {
    // 这里直接使用 self 会造成循环引用
    [weakSelf.progressView setProgress:progress animated:YES];
};

// ✅ 安全写法 - 使用 weak-strong dance
__weak typeof(self) weakSelf = self;
progressProxy.progressBlock = ^(float progress) {
    __strong typeof(weakSelf) strongSelf = weakSelf;
    if (strongSelf) {
        [strongSelf.progressView setProgress:progress animated:YES];
    }
};

4. 导航栏适配问题

问题现象：进度条位置不正确，在不同设备上显示异常

解决方案：使用自动布局适配各种导航栏

- (void)setupProgressView {
    CGFloat progressBarHeight = 2.0f;
    CGRect navigationBarBounds = self.navigationController.navigationBar.bounds;
    
    // 使用自动布局约束
    _progressView = [[NJKWebViewProgressView alloc] init];
    _progressView.translatesAutoresizingMaskIntoConstraints = NO;
    [self.navigationController.navigationBar addSubview:_progressView];
    
    // 添加约束
    NSLayoutConstraint *bottomConstraint = [_progressView.bottomAnchor 
        constraintEqualToAnchor:self.navigationController.navigationBar.bottomAnchor];
    NSLayoutConstraint *leadingConstraint = [_progressView.leadingAnchor 
        constraintEqualToAnchor:self.navigationController.navigationBar.leadingAnchor];
    NSLayoutConstraint *trailingConstraint = [_progressView.trailingAnchor 
        constraintEqualToAnchor:self.navigationController.navigationBar.trailingAnchor];
    NSLayoutConstraint *heightConstraint = [_progressView.heightAnchor 
        constraintEqualToConstant:progressBarHeight];
    
    [NSLayoutConstraint activateConstraints:@[
        bottomConstraint, leadingConstraint, 
        trailingConstraint, heightConstraint
    ]];
}

5. WKWebView 兼容方案

问题背景：UIWebView 已被废弃，但 NJKWebViewProgress 仅支持 UIWebView

桥接方案：通过 KVO 监听 WKWebView 的 estimatedProgress

// WKWebView 进度监听桥接
@interface WKWebViewProgressBridge : NSObject
@property (nonatomic, weak) WKWebView *webView;
@property (nonatomic, copy) void (^progressBlock)(float progress);
@end

@implementation WKWebViewProgressBridge

- (instancetype)initWithWebView:(WKWebView *)webView {
    self = [super init];
    if (self) {
        _webView = webView;
        [webView addObserver:self forKeyPath:@"estimatedProgress" 
                    options:NSKeyValueObservingOptionNew context:nil];
    }
    return self;
}

- (void)observeValueForKeyPath:(NSString *)keyPath 
                      ofObject:(id)object 
                        change:(NSDictionary *)change 
                       context:(void *)context 
{
    if ([keyPath isEqualToString:@"estimatedProgress"]) {
        float progress = [change[NSKeyValueChangeNewKey] floatValue];
        if (self.progressBlock) {
            self.progressBlock(progress);
        }
    }
}

- (void)dealloc {
    [_webView removeObserver:self forKeyPath:@"estimatedProgress"];
}

@end

🚀 高级优化技巧

自定义进度动画

// 自定义进度条动画效果
- (void)setCustomProgressAnimation:(float)progress {
    // 非线性动画曲线
    CGFloat animationDuration = 0.25 * (1.0 - _progressView.progress);
    
    [UIView animateWithDuration:animationDuration 
                          delay:0 
         usingSpringWithDamping:0.7 
          initialSpringVelocity:0.2 
                        options:UIViewAnimationOptionCurveEaseOut 
                     animations:^{
        [_progressView setProgress:progress animated:YES];
    } completion:nil];
}

多页面进度管理

// 多 WebView 进度统一管理
@interface WebViewProgressManager : NSObject
+ (instancetype)sharedManager;
- (void)addProgressView:(NJKWebViewProgressView *)view forKey:(NSString *)key;
- (void)removeProgressViewForKey:(NSString *)key;
- (void)updateProgress:(float)progress forKey:(NSString *)key;
@end