Documentation
Home GitHub

API Reference

Complete API reference for go-browser — all exported functions, types, and constants.

Functions

Fetch

func Fetch(ctx context.Context, href string, timeout time.Duration, opt *Option) (*Result, error)

Fetches a page and returns its content as Markdown, HTML, or JSON. Automatically selects headless or session mode based on the domain and options. Retries with headed mode if headless fetch encounters 403/429/503.

Parameter Type Description
ctx context.Context Context for cancellation and timeout
href string Target URL
timeout time.Duration Per-request timeout; 0 for no timeout
opt *Option Configuration options; nil for defaults

SetMaxConcurrency

func SetMaxConcurrency(n int)

Sets the maximum number of concurrent page loads. Default is 8.

Close

func Close()

Closes all browser instances — both the singleton headless browser and the interactive tab browser. Releases all resources.

CreateTab

func CreateTab(ctx context.Context, href string, opt *Option) (string, error)

Creates an interactive browser tab, navigates to the URL, and returns a tab ID for subsequent operations.

CloseTab

func CloseTab(tabID string) error

Closes an interactive tab and releases its semaphore. If no tabs remain, shuts down the interactive browser.

TabSnapshot

func TabSnapshot(tabID string) (*Result, error)

Captures the current state of an interactive tab as Markdown, HTML, or JSON (based on the tab's Option.Type).

TabClick

func TabClick(tabID, selector string) error

Clicks an element matching the CSS selector in the specified tab.

TabType

func TabType(tabID, selector, text string) error

Types text into an input field matching the CSS selector. Dispatches input and change events.

TabScroll

func TabScroll(tabID string, count int) error

Scrolls the tab page. If count is 0, uses the tab's Option.ScrollCount.

TabNavigate

func TabNavigate(tabID, href string) error

Navigates the tab to a new URL. Waits for load and DOM stabilization.

TabEval

func TabEval(tabID, js string) (string, error)

Executes JavaScript in the tab context and returns the result as a string.

Merge

func Merge(snapshots []string) (string, error)

Merges multiple HTML snapshots by appending body children from subsequent snapshots to the base document body.

DedupTree

func DedupTree(nodes []*Node)

Removes duplicate nodes from a []*Node tree using FNV-64a hash comparison.

DedupMarkdownParagraphs

func DedupMarkdownParagraphs(md string) string

Removes duplicate paragraphs from Markdown content by hash.

InlineTimeElements

func InlineTimeElements(htmlSrc string) (string, error)

Replaces <time> elements with their datetime attribute and inner text.

HTMLToNode

func HTMLToNode(content, baseURL string, keepLinks bool) ([]*Node, error)

Converts HTML content to a structured []*Node tree for JSON output.

HTMLToMarkdown

func HTMLToMarkdown(content, baseURL string, keepLinks bool) (string, error)

Converts HTML content to Markdown syntax.

Types

Viewport

type Viewport struct {
    Width             int
    Height            int
    DeviceScaleFactor float64
}

Browser viewport dimensions and scale factor.

Option

type Option struct {
    IdleWait    time.Duration
    MaxLength   int
    UserAgent   string
    KeepLinks   bool
    StealthJS   string
    SettleJS    string
    Viewport    *Viewport
    SameSession bool
    Headless    bool
    Profile     string
    Type        int
    ScrollCount int
}

Configuration options for fetch and tab operations. See Configuration for field details.

Result

type Result struct {
    Href        string
    FinalURL    string
    Content     string
    ContentType string `json:",omitempty"`
    Title       string
    Author      string
    PublishedAt string
    Excerpt     string
    Status      int
    Tree        []*Node `json:",omitempty"`
}

Fetch result containing the extracted content and metadata.

Error

type Error struct {
    Status int
    Href   string
}

HTTP error with status code and failing URL. Implements the error interface.

Browser

type Browser struct {
    browser  *goRod.Browser
    lastUsed time.Time
}

Internal browser wrapper with idle tracking. Not exported for direct use.

Node

type Node struct {
    Type     string  `json:"type"`
    Text     string  `json:"text,omitempty"`
    Level    int     `json:"level,omitempty"`
    Datetime string  `json:"datetime,omitempty"`
    Href     string  `json:"href,omitempty"`
    Src      string  `json:"src,omitempty"`
    Alt      string  `json:"alt,omitempty"`
    Children []*Node `json:"children,omitempty"`
}

A node in the structured JSON tree output. Type values include: text, heading, paragraph, link, image, list, list_item, ordered_list, code, code_block, blockquote, bold, italic, linebreak, time, container.

Constants

Output Format Types

const (
    TypeMarkdown = iota // 0 — Markdown output (default)
    TypeHTML            // 1 — HTML output
    TypeJSON            // 2 — JSON tree output
)

Default Values

const DefaultUserAgent = "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36"
中文