迁移与 API 参考（1/3）

Simple string pattern (glob-style) pdf_config = CrawlerRunConfig( url_matcher="*.pdf", scraping_strategy=PDFContentScrapingStrategy() )

Multiple patterns with OR logic (default) blog_config = CrawlerRunConfig( url_matcher=["/blog/", "/article/", "/news/"], match_mode=MatchMode.OR # Any pattern matches )

Function matcher api_config = CrawlerRunConfig( url_matcher=lambda url: 'api' in url or url.endswith('.json'), # Other settings like extraction_strategy )

Mixed: String + Function with AND logic complex_config = CrawlerRunConfig( url_matcher=[ lambda url: url.startswith('https://'), # Must be HTTPS ".org/", # Must be .org domain lambda url: 'docs' in url # Must contain 'docs' ], match_mode=MatchMode.AND # ALL conditions must match )

Combined patterns and functions with AND logic secure_docs = CrawlerRunConfig( url_matcher=["https://*", lambda url: '.doc' in url], match_mode=MatchMode.AND # Must be HTTPS AND contain .doc )

Default config - matches ALL URLs default_config = CrawlerRunConfig() # No url_matcher = matches everything


**UrlMatcher Types:**
- **None (default)**: When `url_matcher` is None or not set, the config matches ALL URLs
- **String patterns**: Glob-style patterns like `"*.pdf"`, `"*/api/*"`, `"https://*.example.com/*"`
- **Functions**: `lambda url: bool` - Custom logic for complex matching
- **Lists**: Mix strings and functions, combined with `MatchMode.OR` or `MatchMode.AND`

**Important Behavior:**
- When passing a list of configs to `arun_many()`, URLs are matched against each config's `url_matcher` in order. First match wins!
- If no config matches a URL and there's no default config (one without `url_matcher`), the URL will fail with "No matching configuration found"
- Always include a default config as the last item if you want to handle all URLs

---

##### L) **Advanced Crawling Features**

| **Parameter**               | **Type / Default**           | **What It Does**                                                                                                                    |
|-----------------------------|------------------------------|-------------------------------------------------------------------------------------------------------------------------------------|
| **`deep_crawl_strategy`**   | `DeepCrawlStrategy or None` (None) | Strategy for deep/recursive crawling. Enables automatic link following and multi-level site crawling.                     |
| **`link_preview_config`**   | `LinkPreviewConfig or dict or None` (None) | Configuration for link head extraction and scoring. Fetches and scores link metadata without full page loads.  |
| **`experimental`**          | `dict or None` (None)       | Dictionary for experimental/beta features not yet integrated into main parameters. Use with caution.                                |

**Deep Crawl Strategy** enables automatic site exploration by following links according to defined rules. Useful for sitemap generation or comprehensive site archiving.

**Link Preview Config** allows efficient link discovery and scoring by fetching only the `<head>` section of linked pages, enabling smart crawl prioritization without the overhead of full page loads.

**Experimental** parameters are features in beta testing. They may change or be removed in future versions. Check documentation for currently available experimental features.

---

#### 2.2 Helper Methods

Both `BrowserConfig` and `CrawlerRunConfig` provide a `clone()` method to create modified copies:

```python
#
Create a base configuration
base_config = CrawlerRunConfig(
    cache_mode=CacheMode.ENABLED,
    word_count_threshold=200
)

#
Create variations using clone()
stream_config = base_config.clone(stream=True)
no_cache_config = base_config.clone(
    cache_mode=CacheMode.BYPASS,
    stream=True
)

The clone() method is particularly useful when you need slightly different configurations for different use cases, without modifying the original config.

Class-Level Defaults (`set_defaults` / `get_defaults` / `reset_defaults`)

Both config classes support class-level default overrides. When deploying in a server or cloud context, this eliminates the need to pass the same parameters at every call site.

Resolution order: explicit arg > class-level default > hardcoded default

from crawl4ai import BrowserConfig, CrawlerRunConfig

#
Set once at application startup
BrowserConfig.set_defaults(
    cache_cdp_connection=True,
    cdp_close_delay=0,
    create_isolated_context=True,
)
CrawlerRunConfig.set_defaults(verbose=False)

#
All new instances inherit the class defaults
cfg1 = BrowserConfig(cdp_url="ws://localhost:9222")
#
→ cache_cdp_connection=True, cdp_close_delay=0

cfg2 = BrowserConfig(cdp_url="ws://localhost:9222", cache_cdp_connection=False)
#
→ cache_cdp_connection=False (explicit value wins)

#
Inspect current defaults
BrowserConfig.get_defaults()
#
→ {"cache_cdp_connection": True, "cdp_close_delay": 0, "create_isolated_context": True}

#
Remove a single default
BrowserConfig.reset_defaults("cdp_close_delay")

#
Remove all defaults
BrowserConfig.reset_defaults()

API Reference:

Method	Signature	Description
`set_defaults`	`set_defaults(**kwargs)`	Set class-level defaults for new instances. Raises `ValueError` if any key is not a valid `__init__` parameter.
`get_defaults`	`get_defaults() → dict`	Return a deep copy of the current class-level defaults.
`reset_defaults`	`reset_defaults(*names)`	With no args, clears all defaults. With args, removes only the named defaults.

Notes: - Defaults are independent per class — BrowserConfig.set_defaults() has no effect on CrawlerRunConfig. - Mutable values (lists, dicts) are deep-copied on storage and on each instance creation, so instances do not share objects. - clone(), dump()/load(), and from_kwargs() all work correctly with class defaults — serialized data is self-contained and independent of the current class defaults. - Defaults are stored in memory for the lifetime of the process. They are not persisted to disk.

2.3 Example Usage

import asyncio
from crawl4ai import AsyncWebCrawler, BrowserConfig, CrawlerRunConfig, CacheMode

async def main():
    # Configure the browser
    browser_cfg = BrowserConfig(
        headless=False,
        viewport_width=1280,
        viewport_height=720,
        proxy_config="http://user:pass@myproxy:8080",
        text_mode=True
    )

    # Configure the run
    run_cfg = CrawlerRunConfig(
        cache_mode=CacheMode.BYPASS,
        session_id="my_session",
        css_selector="main.article",
        excluded_tags=["script", "style"],
        exclude_external_links=True,
        wait_for="css:.article-loaded",
        screenshot=True,
        stream=True
    )

    async with AsyncWebCrawler(config=browser_cfg) as crawler:
        result = await crawler.arun(
            url="https://example.com/news",
            config=run_cfg
        )
        if result.success:
            print("Final cleaned_html length:", len(result.cleaned_html))
            if result.screenshot:
                print("Screenshot captured (base64, length):", len(result.screenshot))
        else:
            print("Crawl failed:", result.error_message)

if __name__ == "__main__":
    asyncio.run(main())

2.4 Compliance & Ethics

Parameter	Type / Default	What It Does
`check_robots_txt`	`bool` (False)	When True, checks and respects robots.txt rules before crawling. Uses efficient caching with SQLite backend.
`user_agent`	`str` (None)	User agent string to identify your crawler. Used for robots.txt checking when enabled.

run_config = CrawlerRunConfig(
    check_robots_txt=True,  # Enable robots.txt compliance
    user_agent="MyBot/1.0"  # Identify your crawler
)

3. LLMConfig - Setting up LLM providers

LLMConfig is useful to pass LLM provider config to strategies and functions that rely on LLMs to do extraction, filtering, schema generation etc. Currently it can be used in the following -

LLMExtractionStrategy
LLMContentFilter
JsonCssExtractionStrategy.generate_schema
JsonXPathExtractionStrategy.generate_schema
AdaptiveConfig.embedding_llm_config (embedding model for adaptive crawling)
AdaptiveConfig.query_llm_config (chat completion model for query expansion in adaptive crawling)

3.1 Parameters

Parameter	Type / Default	What It Does
`provider`	`"ollama/llama3","groq/llama3-70b-8192","groq/llama3-8b-8192", "openai/gpt-4o-mini" ,"openai/gpt-4o","openai/o1-mini","openai/o1-preview","openai/o3-mini","openai/o3-mini-high","anthropic/claude-3-haiku-20240307","anthropic/claude-3-opus-20240229","anthropic/claude-3-sonnet-20240229","anthropic/claude-3-5-sonnet-20240620","gemini/gemini-pro","gemini/gemini-1.5-pro","gemini/gemini-2.0-flash","gemini/gemini-2.0-flash-exp","gemini/gemini-2.0-flash-lite-preview-02-05","deepseek/deepseek-chat"` (default: `"openai/gpt-4o-mini"`)	Which LLM provider to use.
`api_token`	1.Optional. When not provided explicitly, api_token will be read from environment variables based on provider. For example: If a gemini model is passed as provider then,`"GEMINI_API_KEY"` will be read from environment variables 2. API token of LLM provider eg: `api_token = "gsk_1ClHGGJ7Lpn4WGybR7vNWGdyb3FY7zXEw3SCiy0BAVM9lL8CQv"` 3. Environment variable - use with prefix "env:" eg:`api_token = "env: GROQ_API_KEY"`	API token to use for the given provider
`base_url`	Optional. Custom API endpoint	If your provider has a custom endpoint
`backoff_base_delay`	Optional. `int` (default: `2`)	Seconds to wait before the first retry when the provider throttles a request.
`backoff_max_attempts`	Optional. `int` (default: `3`)	Total tries (initial call + retries) before surfacing an error.
`backoff_exponential_factor`	Optional. `int` (default: `2`)	Multiplier that increases the wait time for each retry (`delay = base_delay * factor^attempt`).

3.2 Example Usage

llm_config = LLMConfig(
    provider="openai/gpt-4o-mini",
    api_token=os.getenv("OPENAI_API_KEY"),
    backoff_base_delay=1, # optional
    backoff_max_attempts=5, # optional
    backoff_exponential_factor=3, # optional
)

4. Putting It All Together

Use BrowserConfig for global browser settings: engine, headless, proxy, user agent.
Use CrawlerRunConfig for each crawl’s context: how to filter content, handle caching, wait for dynamic elements, or run JS.
Pass both configs to AsyncWebCrawler (the BrowserConfig) and then to arun() (the CrawlerRunConfig).
Use LLMConfig for LLM provider configurations that can be used across all extraction, filtering, schema generation, and adaptive crawling tasks. Can be used in - LLMExtractionStrategy, LLMContentFilter, JsonCssExtractionStrategy.generate_schema, JsonXPathExtractionStrategy.generate_schema, and AdaptiveConfig (embedding_llm_config / query_llm_config)

#
Create a modified copy with the clone() method
stream_cfg = run_cfg.clone(
    stream=True,
    cache_mode=CacheMode.BYPASS
)

#
Or set project-wide defaults once at startup
BrowserConfig.set_defaults(headless=True, text_mode=True)
CrawlerRunConfig.set_defaults(cache_mode=CacheMode.BYPASS)

Complete reference for all C4A-Script commands, syntax, and advanced features.

Command Categories

Navigate between pages and manage browser history.

`GO <url>`

Navigate to a specific URL.

Syntax:

GO &lt;url>

Parameters: - url - Target URL (string)

Examples:

GO https://example.com
GO https://api.example.com/login
GO /relative/path

Notes: - Supports both absolute and relative URLs - Automatically handles protocol detection - Waits for page load to complete

`RELOAD`

Refresh the current page.

Syntax:

RELOAD

Examples:

RELOAD

Notes: - Equivalent to pressing F5 or clicking browser refresh - Waits for page reload to complete - Preserves current URL

`BACK`

Navigate back in browser history.

Syntax:

BACK

Examples:

BACK

Notes: - Equivalent to clicking browser back button - Does nothing if no previous page exists - Waits for navigation to complete

`FORWARD`

Navigate forward in browser history.

Syntax:

FORWARD

Examples:

FORWARD

Notes: - Equivalent to clicking browser forward button - Does nothing if no next page exists - Waits for navigation to complete

⏱️ Wait Commands

Control timing and synchronization with page elements.

`WAIT <time>`

Wait for a specified number of seconds.

Syntax:

WAIT &lt;seconds>

Parameters: - seconds - Number of seconds to wait (number)

Examples:

WAIT 3
WAIT 1.5
WAIT 10

Notes: - Accepts decimal values - Useful for giving dynamic content time to load - Non-blocking for other browser operations

`WAIT <selector> <timeout>`

Wait for an element to appear on the page.

Syntax:

WAIT `<selector>` &lt;timeout>

Parameters: - selector - CSS selector for the element (string in backticks) - timeout - Maximum seconds to wait (number)

Examples:

WAIT `#content` 10
WAIT `.loading-spinner` 5
WAIT `button[type="submit"]` 15
WAIT `.results .item:first-child` 8

Notes: - Fails if element doesn't appear within timeout - More reliable than fixed time waits - Supports complex CSS selectors

`WAIT "<text>" <timeout>`

Wait for specific text to appear anywhere on the page.

Syntax:

WAIT "&lt;text>" &lt;timeout>

Parameters: - text - Text content to wait for (string in quotes) - timeout - Maximum seconds to wait (number)

Examples:

WAIT "Loading complete" 10
WAIT "Welcome back" 5
WAIT "Search results" 15

Notes: - Case-sensitive text matching - Searches entire page content - Useful for dynamic status messages

🖱️ Mouse Commands

Simulate mouse interactions and movements.

`CLICK <selector>`

Click on an element specified by CSS selector.

Syntax:

CLICK `<selector>`

Parameters: - selector - CSS selector for the element (string in backticks)

Examples:

CLICK `#submit-button`
CLICK `.menu-item:first-child`
CLICK `button[data-action="save"]`
CLICK `a[href="/dashboard"]`

Notes: - Waits for element to be clickable - Scrolls element into view if necessary - Handles overlapping elements intelligently

`CLICK <x> <y>`

Click at specific coordinates on the page.

Syntax:

CLICK &lt;x> &lt;y>

Parameters: - x - X coordinate in pixels (number) - y - Y coordinate in pixels (number)

Examples:

CLICK 100 200
CLICK 500 300
CLICK 0 0

Notes: - Coordinates are relative to viewport - Useful when element selectors are unreliable - Consider responsive design implications

`DOUBLE_CLICK <selector>`

Double-click on an element.

Syntax:

DOUBLE_CLICK `<selector>`

Parameters: - selector - CSS selector for the element (string in backticks)

Examples:

DOUBLE_CLICK `.file-icon`
DOUBLE_CLICK `#editable-cell`
DOUBLE_CLICK `.expandable-item`

Notes: - Triggers dblclick event - Common for opening files or editing inline content - Timing between clicks is automatically handled

`RIGHT_CLICK <selector>`

Right-click on an element to open context menu.

Syntax:

RIGHT_CLICK `<selector>`

Parameters: - selector - CSS selector for the element (string in backticks)

Examples:

RIGHT_CLICK `#context-target`
RIGHT_CLICK `.menu-trigger`
RIGHT_CLICK `img.thumbnail`

Notes: - Opens browser/application context menu - Useful for testing context menu interactions - May be blocked by some applications

`SCROLL <direction> <amount>`

Scroll the page in a specified direction.

Syntax:

SCROLL &lt;direction> &lt;amount>

Parameters: - direction - Direction to scroll: UP, DOWN, LEFT, RIGHT - amount - Number of pixels to scroll (number)

Examples:

SCROLL DOWN 500
SCROLL UP 200
SCROLL LEFT 100
SCROLL RIGHT 300

Notes: - Smooth scrolling animation - Useful for infinite scroll pages - Amount can be larger than viewport

`MOVE <x> <y>`

Move mouse cursor to specific coordinates.

Syntax:

MOVE &lt;x> &lt;y>

Parameters: - x - X coordinate in pixels (number) - y - Y coordinate in pixels (number)

Examples:

MOVE 200 100
MOVE 500 400

Notes: - Triggers hover effects - Useful for testing mouseover interactions - Does not click, only moves cursor

`DRAG <x1> <y1> <x2> <y2>`

Drag from one point to another.

Syntax:

DRAG &lt;x1> &lt;y1> &lt;x2> &lt;y2>

Parameters: - x1, y1 - Starting coordinates (numbers) - x2, y2 - Ending coordinates (numbers)

Examples:

DRAG 100 100 500 300
DRAG 0 200 400 200

Notes: - Simulates click, drag, and release - Useful for sliders, resizing, reordering - Smooth drag animation

⌨️ Keyboard Commands

Simulate keyboard input and key presses.

`TYPE "<text>"`

Type text into the currently focused element.

Syntax:

TYPE "&lt;text>"

Parameters: - text - Text to type (string in quotes)

Examples:

TYPE "Hello, World!"
TYPE "user@example.com"
TYPE "Password123!"

Notes: - Requires an input element to be focused - Types character by character with realistic timing - Supports special characters and Unicode

`TYPE $<variable>`

Type the value of a variable.

Syntax:

TYPE $&lt;variable>

Parameters: - variable - Variable name (without quotes)

Examples:

SETVAR email = "user@example.com"
TYPE $email

Notes: - Variable must be defined with SETVAR first - Variable values are strings - Useful for reusable credentials or data

`PRESS <key>`

Press and release a special key.

Syntax:

PRESS &lt;key>

Parameters: - key - Key name (see supported keys below)

Supported Keys: - Tab, Enter, Escape, Space - ArrowUp, ArrowDown, ArrowLeft, ArrowRight - Delete, Backspace - Home, End, PageUp, PageDown

Examples:

PRESS Tab
PRESS Enter
PRESS Escape
PRESS ArrowDown

Notes: - Simulates actual key press and release - Useful for form navigation and shortcuts - Case-sensitive key names

`KEY_DOWN <key>`

Hold down a modifier key.

Syntax:

KEY_DOWN &lt;key>

Parameters: - key - Modifier key: Shift, Control, Alt, Meta

Examples:

KEY_DOWN Shift
KEY_DOWN Control

Notes: - Must be paired with KEY_UP - Useful for key combinations - Meta key is Cmd on Mac, Windows key on PC

`KEY_UP <key>`

Release a modifier key.

Syntax:

KEY_UP &lt;key>

Parameters: - key - Modifier key: Shift, Control, Alt, Meta

Examples:

KEY_UP Shift
KEY_UP Control

Notes: - Must be paired with KEY_DOWN - Releases the specified modifier key - Good practice to always release held keys

`CLEAR <selector>`

Clear the content of an input field.

Syntax:

CLEAR `<selector>`

Parameters: - selector - CSS selector for input element (string in backticks)

Examples:

CLEAR `#search-box`
CLEAR `input[name="email"]`
CLEAR `.form-input:first-child`

Notes: - Works with input, textarea elements - Faster than selecting all and deleting - Triggers appropriate change events

`SET <selector> "<value>"`

Set the value of an input field directly.

Syntax:

SET `<selector>` "&lt;value>"

Parameters: - selector - CSS selector for input element (string in backticks) - value - Value to set (string in quotes)

Examples:

SET `#email` "user@example.com"
SET `#age` "25"
SET `textarea#message` "Hello, this is a test message."

Notes: - Directly sets value without typing animation - Faster than TYPE for long text - Triggers change and input events

🔀 Control Flow Commands

Add conditional logic and loops to your scripts.

`IF (EXISTS <selector>) THEN <command>`

Execute command if element exists.

Syntax:

IF (EXISTS `<selector>`) THEN &lt;command>

Parameters: - selector - CSS selector to check (string in backticks) - command - Command to execute if condition is true

Examples:

IF (EXISTS `.cookie-banner`) THEN CLICK `.accept-cookies`
IF (EXISTS `#popup-modal`) THEN CLICK `.close-button`
IF (EXISTS `.error-message`) THEN RELOAD

Notes: - Checks for element existence at time of execution - Does not wait for element to appear - Can be combined with ELSE

`IF (EXISTS <selector>) THEN <command> ELSE <command>`

Execute command based on element existence.

Syntax:

IF (EXISTS `<selector>`) THEN &lt;command> ELSE &lt;command>

Parameters: - selector - CSS selector to check (string in backticks) - First command - Execute if condition is true - Second command - Execute if condition is false

Examples:

IF (EXISTS `.user-menu`) THEN CLICK `.logout` ELSE CLICK `.login`
IF (EXISTS `.loading`) THEN WAIT 5 ELSE CLICK `#continue`

Notes: - Exactly one command will be executed - Useful for handling different page states - Commands must be on same line

`IF (NOT EXISTS <selector>) THEN <command>`

Execute command if element does not exist.

Syntax:

IF (NOT EXISTS `<selector>`) THEN &lt;command>

Parameters: - selector - CSS selector to check (string in backticks) - command - Command to execute if element doesn't exist

Examples:

IF (NOT EXISTS `.logged-in`) THEN GO /login
IF (NOT EXISTS `.results`) THEN CLICK `#search-button`

Notes: - Inverse of EXISTS condition - Useful for error handling - Can check for missing required elements

`IF (<javascript>) THEN <command>`

Execute command based on JavaScript condition.

Syntax:

IF (`<javascript>`) THEN &lt;command>

Parameters: - javascript - JavaScript expression that returns boolean (string in backticks) - command - Command to execute if condition is true

Examples:

IF (`window.innerWidth < 768`) THEN CLICK `.mobile-menu`
IF (`document.readyState === "complete"`) THEN CLICK `#start`
IF (`localStorage.getItem("user")`) THEN GO /dashboard

Notes: - JavaScript executes in browser context - Must return boolean value - Access to all browser APIs and globals

`REPEAT (<command>, <count>)`

Repeat a command a specific number of times.

Syntax:

REPEAT (&lt;command>, &lt;count>)

Parameters: - command - Command to repeat - count - Number of times to repeat (number)

Examples:

REPEAT (SCROLL DOWN 300, 5)
REPEAT (PRESS Tab, 3)
REPEAT (CLICK `.load-more`, 10)

Notes: - Executes command exactly count times - Useful for pagination, scrolling, navigation - No delay between repetitions (add WAIT if needed)

`REPEAT (<command>, <condition>)`

Repeat a command while condition is true.

Syntax:

REPEAT (&lt;command>, `<condition>`)

Parameters: - command - Command to repeat - condition - JavaScript condition to check (string in backticks)

Examples:

REPEAT (SCROLL DOWN 500, `document.querySelector(".load-more")`)
REPEAT (PRESS ArrowDown, `window.scrollY < document.body.scrollHeight`)

Notes: - Condition checked before each iteration - JavaScript condition must return boolean - Be careful to avoid infinite loops

💾 Variables and Data

Store and manipulate data within scripts.

`SETVAR <name> = "<value>"`

Create or update a variable.

Syntax:

SETVAR &lt;name> = "&lt;value>"

Parameters: - name - Variable name (alphanumeric, underscore) - value - Variable value (string in quotes)

Examples:

SETVAR username = "john@example.com"
SETVAR password = "secret123"
SETVAR base_url = "https://api.example.com"
SETVAR counter = "0"

Notes: - Variables are global within script scope - Values are always strings - Can be used with TYPE command using $variable syntax

`EVAL <javascript>`

Execute arbitrary JavaScript code.

Syntax:

EVAL `<javascript>`

Parameters: - javascript - JavaScript code to execute (string in backticks)

Examples:

EVAL `console.log("Script started")`
EVAL `window.scrollTo(0, 0)`
EVAL `localStorage.setItem("test", "value")`
EVAL `document.title = "Automated Test"`

Notes: - Full access to browser JavaScript APIs - Useful for custom logic and debugging - Return values are not captured - Be careful with security implications

📝 Comments and Documentation

`# <comment>`

Add comments to scripts for documentation.

Syntax:

# &lt;comment text>

Examples:

# This script logs into the application
# Step 1: Navigate to login page
GO /login

# Step 2: Fill credentials
TYPE "user@example.com"

Notes: - Comments are ignored during execution - Useful for documentation and debugging - Can appear anywhere in script - Supports multi-line documentation blocks

🔧 Procedures (Advanced)

Define reusable command sequences.

`PROC <name> ... ENDPROC`

Define a reusable procedure.

Syntax:

PROC &lt;name>
  &lt;commands>
ENDPROC

Parameters: - name - Procedure name (alphanumeric, underscore) - commands - Commands to include in procedure

Examples:

PROC login
  CLICK `#email`
  TYPE $email
  CLICK `#password`
  TYPE $password
  CLICK `#submit`
ENDPROC

PROC handle_popups
  IF (EXISTS `.cookie-banner`) THEN CLICK `.accept`
  IF (EXISTS `.newsletter-modal`) THEN CLICK `.close`
ENDPROC

Notes: - Procedures must be defined before use - Support nested command structures - Variables are shared with main script scope

`<procedure_name>`

Call a defined procedure.

Syntax:

&lt;procedure_name>

Examples:

# Define procedure first
PROC setup
  GO /login
  WAIT `#form` 5
ENDPROC

# Call procedure
setup
login

Notes: - Procedure must be defined before calling - Can be called multiple times - No parameters supported (use variables instead)

Error Handling Best Practices

1. Always Use Waits

# Bad - element might not be ready
CLICK `#button`

# Good - wait for element first
WAIT `#button` 5
CLICK `#button`

2. Handle Optional Elements

# Check before interacting
IF (EXISTS `.popup`) THEN CLICK `.close`
IF (EXISTS `.cookie-banner`) THEN CLICK `.accept`

# Then proceed with main flow
CLICK `#main-action`

3. Use Descriptive Variables

# Set up reusable data
SETVAR admin_email = "admin@company.com"
SETVAR test_password = "TestPass123!"
SETVAR staging_url = "https://staging.example.com"

# Use throughout script
GO $staging_url
TYPE $admin_email

4. Add Debugging Information

# Log progress
EVAL `console.log("Starting login process")`
GO /login

# Verify page state
IF (`document.title.includes("Login")`) THEN EVAL `console.log("On login page")`

# Continue with login
TYPE $username

Common Patterns

# Complete login automation
SETVAR email = "user@example.com"
SETVAR password = "mypassword"

GO /login
WAIT `#login-form` 5

# Handle optional cookie banner
IF (EXISTS `.cookie-banner`) THEN CLICK `.accept-cookies`

# Fill and submit form
CLICK `#email`
TYPE $email
PRESS Tab
TYPE $password
CLICK `button[type="submit"]`

# Wait for redirect
WAIT `.dashboard` 10

Infinite Scroll

# Load all content with infinite scroll
GO /products

# Scroll and load more content
REPEAT (SCROLL DOWN 500, `document.querySelector(".load-more")`)

# Alternative: Fixed number of scrolls
REPEAT (SCROLL DOWN 800, 10)
WAIT 2

Form Validation

# Handle form with validation
SET `#email` "invalid-email"
CLICK `#submit`

# Check for validation error
IF (EXISTS `.error-email`) THEN SET `#email` "valid@example.com"

# Retry submission
CLICK `#submit`
WAIT `.success-message` 5

Multi-step Process

# Complex multi-step workflow
PROC navigate_to_step
  CLICK `.next-button`
  WAIT `.step-content` 5
ENDPROC

# Step 1
WAIT `.step-1` 5
SET `#name` "John Doe"
navigate_to_step

# Step 2
SET `#email` "john@example.com"
navigate_to_step

# Step 3
CLICK `#submit-final`
WAIT `.confirmation` 10

Integration with Crawl4AI

Use C4A-Script with Crawl4AI for dynamic content interaction:

from crawl4ai import AsyncWebCrawler, CrawlerRunConfig

# Define interaction script
script = """
# Handle dynamic content loading
WAIT `.content` 5
IF (EXISTS `.load-more-button`) THEN CLICK `.load-more-button`
WAIT `.additional-content` 5

# Accept cookies if needed
IF (EXISTS `.cookie-banner`) THEN CLICK `.accept-all`
"""

config = CrawlerRunConfig(
    c4a_script=script,
    wait_for=".content",
    screenshot=True
)

async with AsyncWebCrawler() as crawler:
    result = await crawler.arun("https://example.com", config=config)
    print(result.markdown)

This reference covers all available C4A-Script commands and patterns. For interactive learning, try the tutorial or live demo.

迁移与 API 参考（1/3）

迁移与 API 参考（1/3）

Class-Level Defaults (set_defaults / get_defaults / reset_defaults)

2.3 Example Usage

2.4 Compliance & Ethics

3. LLMConfig - Setting up LLM providers

3.1 Parameters

3.2 Example Usage

4. Putting It All Together

Command Categories

🧭 Navigation Commands

GO <url>

RELOAD

BACK

FORWARD

⏱️ Wait Commands

WAIT <time>

WAIT <selector> <timeout>

WAIT "<text>" <timeout>

🖱️ Mouse Commands

CLICK <selector>

CLICK <x> <y>

DOUBLE_CLICK <selector>

RIGHT_CLICK <selector>

SCROLL <direction> <amount>

MOVE <x> <y>

DRAG <x1> <y1> <x2> <y2>

⌨️ Keyboard Commands

TYPE "<text>"

TYPE $<variable>

PRESS <key>

KEY_DOWN <key>

KEY_UP <key>

CLEAR <selector>

SET <selector> "<value>"

🔀 Control Flow Commands

IF (EXISTS <selector>) THEN <command>

IF (EXISTS <selector>) THEN <command> ELSE <command>

IF (NOT EXISTS <selector>) THEN <command>

IF (<javascript>) THEN <command>

REPEAT (<command>, <count>)

REPEAT (<command>, <condition>)

💾 Variables and Data

SETVAR <name> = "<value>"

EVAL <javascript>

📝 Comments and Documentation

# <comment>

🔧 Procedures (Advanced)

PROC <name> ... ENDPROC

<procedure_name>

Error Handling Best Practices

1. Always Use Waits

2. Handle Optional Elements

3. Use Descriptive Variables

4. Add Debugging Information

Common Patterns

Login Flow

Infinite Scroll

Form Validation

Multi-step Process

Integration with Crawl4AI

Class-Level Defaults (`set_defaults` / `get_defaults` / `reset_defaults`)

`GO <url>`

`RELOAD`

`BACK`

`FORWARD`

`WAIT <time>`

`WAIT <selector> <timeout>`

`WAIT "<text>" <timeout>`

`CLICK <selector>`

`CLICK <x> <y>`

`DOUBLE_CLICK <selector>`

`RIGHT_CLICK <selector>`

`SCROLL <direction> <amount>`

`MOVE <x> <y>`

`DRAG <x1> <y1> <x2> <y2>`

`TYPE "<text>"`

`TYPE $<variable>`

`PRESS <key>`

`KEY_DOWN <key>`

`KEY_UP <key>`

`CLEAR <selector>`

`SET <selector> "<value>"`

`IF (EXISTS <selector>) THEN <command>`

`IF (EXISTS <selector>) THEN <command> ELSE <command>`

`IF (NOT EXISTS <selector>) THEN <command>`

`IF (<javascript>) THEN <command>`

`REPEAT (<command>, <count>)`

`REPEAT (<command>, <condition>)`

`SETVAR <name> = "<value>"`

`EVAL <javascript>`

`# <comment>`

`PROC <name> ... ENDPROC`

`<procedure_name>`