CefSharp使用ProgressBar展示页面加载进度失效问题

问题根因 #

初始IDownloadHandler方案失效原因 #

• IDownloadHandler 仅在用户主动触发文件下载（点击下载链接、请求附件类资源）时才会触发回调，普通页面导航、页面静态资源（JS/CSS/图片）加载的流程完全不会触发该Handler的方法，因此你在CanDownload、OnBeforeDownload、OnDownloadUpdated上打的断点永远不会命中，这个Handler从设计上就不是用来监听页面加载进度的。
• 初始代码中CanDownload方法直接抛出NotImplementedException，即使真的触发文件下载逻辑，也会直接抛出异常中断流程，根本走不到后续进度计算逻辑。

改用DisplayHandler后仍失效原因 #

选择DisplayHandler监听OnLoadingProgressChange回调的方向是正确的，这是CefSharp官方提供的专门用于监听页面整体加载进度的接口，但代码存在三个致命问题导致进度条无法正常工作：

• 进度值换算错误：OnLoadingProgressChange返回的progress参数是取值范围为0~1的双精度浮点数（加载50%时值为0.5，加载完成时值为1），直接将该值强转为int赋值给ProgressBar，会因为浮点转整型的截断逻辑，在进度未达到100%时始终得到0，加载完成时直接跳为1，完全看不到进度渐变过程。
• Cef初始化时序错误：WinForms版本的CefSharp中，ChromiumWebBrowser控件会在自身句柄创建完成后自动触发Cef初始化，在窗体构造函数中手动调用Cef.Initialize很容易出现初始化时序冲突，导致自定义Handler没有正确绑定到浏览器实例，回调根本不触发。
• 缺少控件更新边界校验：没有对进度值做范围校验，也没有做跨线程更新的异常兜底，部分场景下会因为跨线程访问控件、进度值超出ProgressBar的最大最小值范围抛出异常，导致进度回调中断。

正确实现方案 #

1. 修正进度监听Handler实现 #

将Handler重命名为符合语义的PageLoadProgressHandler，修正进度值换算逻辑，增加边界校验：

using System.Windows.Forms;
using CefSharp;
using CefSharp.Handler;

namespace CefSharpWinFormQuestion.ProgressBarQS.f01Create
{
    public class PageLoadProgressHandler : DisplayHandler
    {
        private readonly ProgressBar _progressBar;

        public PageLoadProgressHandler(ProgressBar progressBar)
        {
            _progressBar = progressBar;
            // 初始化进度条范围为0-100，对应百分比进度
            _progressBar.Minimum = 0;
            _progressBar.Maximum = 100;
            _progressBar.Value = 0;
        }

        protected override void OnLoadingProgressChange(IWebBrowser chromiumWebBrowser, IBrowser browser, double progress)
        {
            // 将0-1的浮点进度换算为0-100的百分比值
            int progressPercent = (int)(progress * 100);
            
            // 跨线程安全更新UI控件
            _progressBar.Invoke(new Action(() =>
            {
                // 校验进度值范围，防止越界触发控件异常
                if (progressPercent < _progressBar.Minimum) progressPercent = _progressBar.Minimum;
                if (progressPercent > _progressBar.Maximum) progressPercent = _progressBar.Maximum;
                
                _progressBar.Value = progressPercent;

                // 加载完成后可自定义后续逻辑，比如隐藏进度条、触发加载完成事件
                if (progressPercent == 100)
                {
                    // 自定义加载完成逻辑
                }
            }));
        }
    }
}

2. 修正Cef初始化逻辑 #

Cef全局初始化必须在整个应用启动时执行一次，不要在单个窗体构造函数中初始化，也不要在单个窗体关闭时执行Shutdown，避免多窗体场景下其他浏览器实例崩溃。
首先修改Program.cs做全局初始化：

using CefSharp;
using CefSharp.WinForms;

namespace CefSharpWinFormQuestion
{
    static class Program
    {
        [STAThread]
        static void Main()
        {
            // 应用启动时全局初始化Cef，整个应用生命周期仅执行一次
            Cef.Initialize(new CefSettings());
            
            ApplicationConfiguration.Initialize();
            Application.Run(new frmProgressBar());
            
            // 应用完全退出时再执行Cef资源回收
            Cef.Shutdown();
        }
    }
}

再修正窗体代码，移除错误的初始化、Shutdown逻辑：

using CefSharp.WinForms;

namespace CefSharpWinFormQuestion.ProgressBarQS.f01Create
{
    public partial class frmProgressBar : Form
    {        
        public frmProgressBar()
        {
            InitializeComponent();
            // 绑定修正后的进度监听Handler
            chromiumWebBrowser1.DisplayHandler = new PageLoadProgressHandler(progressBar1);
            textBox1.Text = @"https://github.com/";
        }

        private void frmProgressBar_FormClosing(object sender, FormClosingEventArgs e)
        {
            // 释放当前浏览器实例即可，不要在此处调用Cef.Shutdown
            chromiumWebBrowser1.Dispose();
        }

        private void button1_Click(object sender, EventArgs e)
        {
            string url = textBox1.Text;
            // 跳转页面前重置进度条
            progressBar1.Value = 0;
            chromiumWebBrowser1.LoadUrlAsync(url);
        }
    }
}

优化建议 #

• 如果需要监听页面加载开始、加载失败、加载完成的全生命周期状态，可以额外实现ILoadHandler绑定到浏览器的LoadHandler属性，和进度条逻辑配合可以实现更完整的加载状态提示。
• OnLoadingProgressChange返回的进度是页面整体导航进度，包含主文档、所有嵌入静态资源的加载过程，和主流浏览器地址栏的进度条行为完全一致。

内容的提问来源于stack exchange，提问作者eusataf