# ChromeBrowClass **Repository Path**: kid0/ChromeBrowClass ## Basic Information - **Project Name**: ChromeBrowClass - **Description**: 基于selenium对chrome内核的浏览器控制二次包装 - **Primary Language**: Python - **License**: EPL-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 2 - **Forks**: 0 - **Created**: 2022-08-29 - **Last Updated**: 2026-02-28 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # ChromeBrowClass ## 简介 基于selenium对chrome内核的浏览器控制的二次包装（内核需要80+版本以上，python应该3.7以上版本）。 兼容旧版本selenium3.7+和新版本selenium4.13+，并自行包装chromedriver.exe下载逻辑 。 （解决chrome116+版本官方无法自动下载对应driver问题[国内无法下载]）。 使用方法demo请参考： https://gitee.com/kid0/ChromeBrowClassDemo 本项目地址： https://gitee.com/kid0/ChromeBrowClass ## 版本 ### last version：3.3.1.0 ### last update: 2026-2-27 ## pip - requests - selenium>=4.30.0 - pillow - pyscreeze - numpy - loguru - packaging - undetected_chromedriver - pathlib ## 使用 ### 1、初始化 使用ChromeBrowClass类初始化浏览器配置 #### 参数： - chromepath > str类型，默认'auto' > chrome的路径[不填则使用系统配置,'auto'则尝试自动探寻,其他直接作为参数] - driverpath > str，默认'chromedriver{版本号}.exe' > chromedriver的路径[默认是运行目录下] - __\*__ > __*为了更好兼容后续版本，参数不再允许匿名传递，请使用参数名传递*__ - proxy > str，默认 '' > 代理 username:password@123.123.123.123:6666 或 123.123.123.123:6666 - ua > str，默认 '' > 自定义ua - img > int,默认 0 > 是否加载图片，0默认 1加载 2不加载 - headers > dist，默认 {} > 请求头 - use_user_data > bool，默认 False > 是否使用用户数据，若开启则用户数据文件夹不可在占用状态。如果无法启用，可以先调用 - user_data_path > str，默认 '' > 用户数据路径，use_user_data为True才有效 - chrome_arguments > list，默认 [] > chrome其他配置参数 - chrome_experimental_options > dict，默认 {} > chrome实验性配置参数 - crx_extensions > list，默认 [] > 插件路径列表 - sandbox > bool，默认 True > 使用沙盒环境，linux无法启动chrome时应该禁止 - gpu > bool，默认 True > 硬件加速，禁用后能减少chrome的内存占用，和加快加载速度 - handless > bool，默认 False > 隐藏窗口，使用无窗口模式记得kill掉chrome或者使用driver.close() - slink > bool，默认 False > 【不建议开启】不提示“正在自动测试”，默认为False。能降低被检测为driver的风险 > **注意:在部分机器启用会导致浏览器崩溃** - mask > bool，默认 False > 【建议开启】简易伪装不是driver。能绕过部分driver检测 - debugger_address > str，默认 '' > 连接chrome的调试接口地址。如"localhost:9222"。 > chrome启动时需要参数"--remote-debugging-port=9222"指定调试端口 - optimize_setting > bool，默认 True > 优化chrome的配置，默认开启。非原生chrome浏览器,或使用debugger_address时建议禁止 - log_path > str，默认 None > server日志目录，默认没有 **其他参数** - custom_chrome_options > object，默认 None > 自定义配置对象。此项非None时，除路径外其他参数无效。 - auto_update_chromedriver > bool，默认 False > 自动更新driver - chrome_version > str，默认 '' > 指定chrome版本,其他基于chrome底层的浏览器需要指定 **特殊参数** - my_update > bool，默认 False > 是否使用自定义函数更新driver文件，仅对selenium4.7+版本生效自定义。默认使用自带，chrome115+建议使用自定义函数。 - chromedriver_download_proxy > dict，默认 None > 下载chromedriver时使用的代理。建议翻墙代理，否者可能下载driver失败。 ### 2、启动webdriver > 初始完后使用init_web函数启动webdriver。 > 也可以使用set_driver接管其他方法初始化好的webdriver ## 可用函数 ### 1、基础函数 ``` init_web 启动web(启动driver) _init_web_runner 启动web具体逻辑 set_driver 设置driver以控制外部driver _make_chrome_options 制作配置类object set_pg_timeout 设置超时 get_capabe 获取浏览器能力表 get_debug_addr 获取debug调试地址 get_version_message 获取浏览器和driver版本[仅成功连接后可用,建议使用get_chrome_version和get_driver_version代替] scroll 滑条下拉 close 关闭页面 quit 关闭浏览器 wait_elm 尝试查找元素 kill_other_windows 关闭其他窗口 get 尝试跳转url get_cookies 获取所有cookies set_cookies 设置cookies clear_cookies 清空cookies get_in_new_window 在新窗口中打开 wait_for_visible 等待元素出现，超时停止加载返回None wait_for_visible_any 等待多个元素出现，超时停止加载返回None wait_for_invisible 等待元素消失，超时停止加载返回None wait_for_clickable 等待元素可点击，超时停止加载返回None wait_for_presence 等待元素存在，超时停止加载返回None wait_for_presence_all 等待多个元素存在，超时停止加载返回None chrome_devtools_order 执行CDT命令 save_as_png 截图，可用自带函数，也可利用CDT截图，截图可以定义窗口大小，默认可视区域 save_as_png_2 【3.1新增】截图，支持元素/窗口/全页截图 fullweb_show 全页显示 execute_script 执行js语句 expand_shadow_element shadow-root之下的定位 js_click_by_xpath 根据xpath,用js执行点击，点击click无法点击的元素 js_click_by_element 将elemen用js执行点击，点击click无法点击的元素 scroll_into_view_by_xpath 根据xpath显示元素到当前可视区域 scroll_into_view_by_element 将element显示到当前可视区域 order_to_xpath 根据xpath识别元素，并发送命令 order_to_element 向element发送命令 order_to_web 向浏览器页面发送命令 scroll_by 视图偏移 post 在页面post数据[不推荐使用] post2 在页面post数据[可以使用,暂时实现了json的形式发送] ``` ### 2、配置类函数 BrowSettings.BrowInfoFetch ``` get_chrome_path 【3.0新增】获取chrome路径 get_chrome_version 【3.0新增】获取chrome版本 guess_chrome_auto_down_path 猜测chrome自动下载路径 fetch_user_data_dir 获取用户数据目录 get_driver_version 【3.1迁移】获取driver文件的版本信息 ``` ### 3、系统级功能 BrowSettings.SystemCommand ``` update_chromedriver 自动更新对应版本的driver check_chrome_open_port 检测chrome开放的调试端口，一般是随机的，不太准确，建议启动时指定好端口 check_open_port 检测端口开放情况，对非chrome原生浏览器使用此函数检测 startup_chrome_no_driver 指定调试端口的启动本地chrome浏览器 kill_chrome 关闭所有chrome浏览器 kill_chrome_driver 关闭所有driver clear_appdata 删除所有缓存，注意包括登录cookies和历史数据 not_show_session_recovery 不显示“恢复页面”窗口 ``` ### 4、图像定位 BrowTools.png_location_element ``` png_location_element 定位指定图片的位置，支持"灰度""全彩""投影"3种模式的匹配。可指定匹配区域 png_location_element2 定位指定图片的位置，仅支持全图匹配，但效率更高。可指定匹配区域 ``` ### 5、扩展函数 BrowSettings.BrowProFunction ``` setting_popups 在页面模式设置重定向配置 ``` ## 更新日志 ``` v3.3.2.0 2026-2-28 【优化】当注册列表的chrome文件失效时，尝试自定义获取路径。 v3.3.1.0 2026-2-27 【优化】查询driver映射请求禁用代理，且不可配置代理（在国内时可以访问的，无需代理，反而使用代理会无法访问）。 【优化】下载driver改为默认禁用代理，可配置，建议使用代理工具加速下载（国内大部分ip无法下载）。 【删除】删除弃用函数wait_elm。 v3.3.0.0 2026-2-26 【重构】重写了selenium版本号判定方法，以兼容未来版本的判断。 【新增】新增对chrome test浏览器的支持，支持控制和识别浏览器版本。 【调整】chromedriver的命名不再默认，将自动以chromedriver{版本号}.exe命名。 【调整】调整日志输出方式。 【优化】优化一些参数和函数的描述。 【优化】优化了使用样例。但复杂样例依然使用ChromeBrowClassDemo。 【优化】优化了自动下载driver的配置，并允许指定下载目录。 【删除】删除一些弃用函数。 v3.2.1.0 2024年11月11日 【优化】对浏览器命令，兼容4.26.1版本selenium。 v3.2.0.0 2024年10月17日 【新增】新增post2函数，支持json形式的post数据。 v3.1.0.1 2024年10月11日 【修复】修复浏览器有使用ip6时检测端口会崩溃的问题。 v3.1.0.0 2024年9月23日 【新增】新增save_as_png_2适用于新版selenium的截图。 【调整】调整浏览器和driver的版本检测的函数位置。 v3.0.1.0 2024年9月23日 【重构】重构了部分功能框架。 【新增】新增chrome_experimental_options参数用于配置chrome实验性参数。 【新增】新增项目ChromeBrowClassDemo作为本项目的示例。 【调整】重写了浏览器版本和路径的检测逻辑。 【调整】不再允许匿名参数传递启动参数，请使用参数名传递。 【修复】修复指定端口启动浏览器时无法自动下载driver的问题。 【优化】优化readme文档和文件声明。 【优化】初始化参数不再匿名，以支持编码工具的使用。 v2.7.0.0 2024年2月29日 【新增】新增参数chromedriver_download_proxy用于配置下载driver时的代理配置。 v2.6.2.1 2023年12月13日 【修复】修复启动器不能不传的问题。 【优化】兼容新版selenium对没有driver时的异常捕获处理。 【优化】当import *时现在仅引入重要函数。 v2.6.1.0 2023年10月9日 【新增】新增扩展版控件。 【调整】使用官方自动更新driver能力最低selenium版本限制调整4.7->4.13。 4.7版本对chrome114+版本支持存在无法更新driver的bug。 【更新】同步新版selenium更新了driver自动更新逻辑。 v2.5.1.0 2023年9月26日 【调整】截图保存的最小尺寸默认改为900*1600。 v2.5.0.0 2023年9月18日 【新增】新增scroll_by函数用于浏览器视图偏移。 【新增】scroll_into_view类函数允许设置视图相对偏移量。 v2.4.3.0 2023年9月14日 【修复】修复自定义driver更新在自定义目录下出现异常问题。 v2.4.2.2 2023年9月7日 【新增】增加对114+test版chrome的driver匹配下载支持。 【调整】允许driver初始化在指定调试端口同时设置GPU是否开启。 【调整】调整截图逻辑。不再完全依赖cdt。 【优化】自动更新函数运行使用my_update设置使用官方函数还是自定义函数。 chrome115+版本建议使用自定义函数。 【优化】调试地址的driver不再直接关闭浏览器。 【优化】自定义driver允许设置null清空设置。 v2.3.5.0 2023年7月17日 【调整】默认解除"禁止弹窗"。 v2.3.4.3 2023年7月14日 【优化】允许指定自动更新driver说使用的方式。 v2.3.4.0 2023年6月28日 【优化】优化参数和返回值提示。 v2.3.3.0 2023年5月15日 【新增】新增支持使用原生manager管理driver文件。 【优化】优化chrome配置的设置方式。 v2.3.1.0 2023年5月3日 【修复】修复在多线程下optimize_setting配置可能导致浏览器崩溃的问题。 v2.3.0.0 2023年4月24日 【新增】新增函数检测开放端口，以兼容非chrome原生的浏览器检测。 【新增】新增配置参数optimize_setting，默认开启，关闭其可解决新版110+chrome使用调试地址时报错的问题。 【优化】非chrome浏览器端口未启动时不再错误的结束chrome进程。 【优化】添加cookies新增参数，以解决selenium无法跨区域添加cookies问题。 v2.2.0.0 2023年2月20日 【新增】允许等待元素获取批量结果。 【新增】新增公共外网工具，新增获取外网IP函数。 【优化】优化所有等待元素逻辑。 v2.1.4.3 2023年1月29日 【修复】修复windows下driver在子目录下无法检测版本号问题。 v2.1.4.2 2022年9月22日 【新增】新增端口被占用应对方案。 v2.1.4.1 2022年9月14日 【新增】新增猜测自动下载目录函数。 v2.1.3.0 2022年9月5日 【新增】自动更新driver模式下能根据实际异常信息重新更新chrome版本。 【优化】部分异常新增重试机制。 v2.1.2.1 2022年9月2日 【新增】新增新的图像定位方法，新方法仅可全图匹配，但效率更好。 v2.1.1.0 2022年9月1日 【新增】新增图像定位增加"投影"匹配功能，与"全彩"相斥，允许通过影子匹对图像形状。 v2.1.0.0 2022年8月31日 【新增】新增图像定位坐标功能，支持"灰度""全彩"两种模式匹配。 【优化】优化代码格式。 v2.0.1.0 2022年8月29日 【修复】修复在python3.9下shadow-root定位报错问题。 v2.0.0.0 2022年7月8日 【重构】重构BrowClass类，拆分功能与配置。 ```