13 个不稳定版本 (6 个重大变更)

新功能 0.7.0	2024年8月12日
0.6.0	2024年5月28日
0.5.2	2023年9月29日
0.5.1	2023年7月24日
0.1.0	2020年12月13日

#565 in 网页开发

每月下载量 6,777
被 28 个 Crates 使用（直接使用 4 个）

MIT/Apache 协议

18KB
175 行代码

chromiumoxide

chromiumoxide 提供了一个高级和异步 API，用于通过 DevTools 协议控制 Chrome 或 Chromium。它支持所有类型的 Chrome DevTools 协议，可以启动一个无头或完整（非无头）的 Chrome 或 Chromium 实例或连接到一个已经运行的实例。

用法

use futures::StreamExt;

use chromiumoxide::browser::{Browser, BrowserConfig};

#[async_std::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    
   // create a `Browser` that spawns a `chromium` process running with UI (`with_head()`, headless is default) 
   // and the handler that drives the websocket etc.
    let (mut browser, mut handler) =
        Browser::launch(BrowserConfig::builder().with_head().build()?).await?;
    
   // spawn a new task that continuously polls the handler
    let handle = async_std::task::spawn(async move {
        while let Some(h) = handler.next().await {
            if h.is_err() {
                break;
            }
        }
    });
    
   // create a new browser page and navigate to the url
    let page = browser.new_page("https://en.wikipedia.org").await?;
    
   // find the search bar type into the search field and hit `Enter`,
   // this triggers a new navigation to the search result page
   page.find_element("input#searchInput")
           .await?
           .click()
           .await?
           .type_str("Rust programming language")
           .await?
           .press_key("Enter")
           .await?;

   let html = page.wait_for_navigation().await?.content().await?;
   
    browser.close().await?;
    handle.await;
    Ok(())
}

当前的 API 仍缺少一些功能，但 Page::execute 函数允许发送所有 chromiumoxide_types::Command 类型（参见生成的代码）。大多数 Element 和 Page 函数基本上只是简化了命令构造和组合，例如 Page::pdf

pub async fn pdf(&self, params: PrintToPdfParams) -> Result<Vec<u8>> {
     let res = self.execute(params).await?;
     Ok(base64::decode(&res.data)?)
 }

如果您需要其他功能，Page::execute 函数允许您编写自己的命令包装器。如果您认为缺少有意义的命令，我们将非常欢迎您提交 PR。

将 chromiumoxide 添加到您的项目中

chromiumoxide 支持使用 async-std 和 tokio 运行时。

默认情况下，chromiumoxide 配置为使用 async-std。

使用 chromiumoxide 和 async-std 运行时


chromiumoxide = { git = "https://github.com/mattsse/chromiumoxide", branch = "main"}

要使用 tokio 运行时，请添加 features = ["tokio-runtime"] 并将 default-features = false 设置为禁用默认运行时（async-std）
chromiumoxide = { git = "https://github.com/mattsse/chromiumoxide", features = ["tokio-runtime"], default-features = false, branch = "main"}

这种配置主要得益于选择的 websocketcrate：async-tungstenite。
生成的代码
chromiumoxide_pdl crate 包含一个 PDL 解析器，它是对 chromium 源树中的一个 python 脚本 的 rust 重新编写，以及一个 Generator，它将解析的 PDL 文件转换为 rust 代码。 chromiumoxide_cdp crate 的唯一目的是在其 构建过程 中调用生成器并在编译 crate 之前 包含生成的输出。这种分离仅仅是因为生成的输出是大约 60K 行 rust 代码（不包括所有的 proc 宏展开）。因此，预计编译需要一些时间。生成器可以独立配置和使用，请参阅 chromiumoxide_cdp/build.rs。
每个 chrome pdl 域都放在它自己的 rust 模块中，浏览器协议页面域的类型在 chromiumoxide_cdp::cdp::browser_protocol::page，js_protocol 的运行域在 chromiumoxide_cdp::cdp::js_protocol::runtime 等。
vanilla.aslushnikov.com 是浏览 pdl 文件中定义的所有类型的绝佳资源。此网站将 pdl 文件中定义的 Command 类型显示为 Method。 chromiumoxid 坚持 Command 命名法。因此，对于在 pdl 中定义为命令类型的所有内容（在 vanilla.aslushnikov.com 上标记为 Method），chromiumoxide 包含一个命令类型和一个指定的返回类型。对于每个命令都有一个 <命令名称>Params 类型，它具有构建器支持（<命令名称>Params::builder()）及其对应的返回类型：<命令名称>Returns。所有命令都共享 chromiumoxide_types::Command 特性的实现。所有事件都捆绑在单个枚举（CdpEvent）中
抓取器
默认情况下，chromiumoxide 将尝试在运行它的计算机上找到已安装的铬版本。对于某些平台，可以使用 fetcher 自动下载和安装。
由于 Cargo 的一个错误，功能目前有些混乱，一旦解决，将会进行更改。根据您的运行时和 TLS 配置，您应该启用以下之一

_fetcher-rustls-async-std
_fetcher-rusttls-tokio
_fetcher-native-async-std
_fetcher-native-tokio

use std::path::Path;

use futures::StreamExt;

use chromiumoxide::browser::{BrowserConfig};
use chromiumoxide::fetcher::{BrowserFetcher, BrowserFetcherOptions};

#[async_std::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let download_path = Path::new("./download");
    async_std::fs::create_dir_all(&download_path).await?;
    let fetcher = BrowserFetcher::new(
        BrowserFetcherOptions::builder()
            .with_path(&download_path)
            .build()?,
    );
    let info = fetcher.fetch().await?;

    let config = BrowserConfig::builder()
        .chrome_executable(info.executable_path)
        .build()?,
}

已知问题

在 chromiumoxide_cdp 中为 PDL 文件生成的 rust 文件，当手动关闭对实验类型支持时无法编译（export CDP_NO_EXPERIMENTAL=true）。这是因为 *.pdl 文件中使用了某些实验性 pdl 类型，但没有标记为实验性。

故障排除
问：正在启动一个新的铬实例，但随后超时。
答：请检查您的铬语言设置是否设置为英语。chromiumoxide 尝试从铬进程输出中解析调试端口，这仅限于英语。
许可证
以下任一许可证下授权

Apache 许可证 2.0 版（LICENSE-APACHE 或 https://apache.ac.cn/licenses/LICENSE-2.0）
MIT 许可证（LICENSE-MIT 或 https://opensource.org/licenses/MIT）

参考

chromedp
rust-headless-chrome，其中包含了启动配置、KeyDefinition 和输入支持等功能。
puppeteer



依赖关系

~0.7–1.6MB


~35K SLoC



serde+derive

serde_json