C4A-Script API 参考
¥C4A-Script API Reference
所有 C4A-Script 命令、语法和高级功能的完整参考。
¥Complete reference for all C4A-Script commands, syntax, and advanced features.
命令类别
¥Command Categories
🧭 导航命令
¥🧭 Navigation Commands
在页面之间导航并管理浏览器历史记录。
¥Navigate between pages and manage browser history.
GO <url>
导航到特定的 URL。
¥Navigate to a specific URL.
句法：
¥Syntax:
参数： -url - 目标 URL（字符串）
¥Parameters:
- url - Target URL (string)
例子：
¥Examples:
笔记： - 支持绝对和相对 URL - 自动处理协议检测 - 等待页面加载完成
¥Notes: - Supports both absolute and relative URLs - Automatically handles protocol detection - Waits for page load to complete
RELOAD
刷新当前页面。
¥Refresh the current page.
句法：
¥Syntax:
例子：
¥Examples:
笔记： - 相当于按 F5 或单击浏览器刷新 - 等待页面重新加载完成 - 保留当前 URL
¥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:
例子：
¥Examples:
笔记： - 相当于单击浏览器后退按钮 - 如果不存在上一页则不执行任何操作 - 等待导航完成
¥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:
例子：
¥Examples:
笔记： - 相当于单击浏览器前进按钮 - 如果不存在下一页则不执行任何操作 - 等待导航完成
¥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:
参数： -seconds - 等待的秒数（数字）
¥Parameters:
- seconds - Number of seconds to wait (number)
例子：
¥Examples:
笔记： - 接受十进制值 - 有助于为动态内容提供加载时间 - 不阻塞其他浏览器操作
¥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:
参数： -selector - 元素的 CSS 选择器（反引号中的字符串）-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
笔记： - 如果元素在超时时间内未出现，则失败 - 比固定时间等待更可靠 - 支持复杂的 CSS 选择器
¥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:
参数： -text - 等待的文本内容（引号中的字符串） -timeout - 等待的最大秒数（数字）
¥Parameters:
- text - Text content to wait for (string in quotes)
- timeout - Maximum seconds to wait (number)
例子：
¥Examples:
笔记： - 区分大小写的文本匹配 - 搜索整个页面内容 - 适用于动态状态消息
¥Notes: - Case-sensitive text matching - Searches entire page content - Useful for dynamic status messages
🖱️ 鼠标命令
¥🖱️ Mouse Commands
模拟鼠标交互和移动。
¥Simulate mouse interactions and movements.
CLICK <selector>
单击 CSS 选择器指定的元素。
¥Click on an element specified by CSS selector.
句法：
¥Syntax:
参数： -selector - 元素的 CSS 选择器（反引号中的字符串）
¥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:
参数： -x - X 坐标（像素）（数字）-y - Y 坐标（像素）（数字）
¥Parameters:
- x - X coordinate in pixels (number)
- y - Y coordinate in pixels (number)
例子：
¥Examples:
笔记： - 坐标相对于视口 - 当元素选择器不可靠时有用 - 考虑响应式设计的影响
¥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:
参数： -selector - 元素的 CSS 选择器（反引号中的字符串）
¥Parameters:
- selector - CSS selector for the element (string in backticks)
例子：
¥Examples:
笔记： - 触发 dblclick 事件 - 常用于打开文件或编辑内联内容 - 自动处理点击之间的时间
¥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:
参数： -selector - 元素的 CSS 选择器（反引号中的字符串）
¥Parameters:
- selector - CSS selector for the element (string in backticks)
例子：
¥Examples:
笔记： - 打开浏览器/应用程序上下文菜单 - 用于测试上下文菜单交互 - 可能被某些应用程序阻止
¥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:
参数： -direction - 滚动方向：UP ，DOWN ，LEFT ，RIGHT -amount - 滚动的像素数（数字）
¥Parameters:
- direction - Direction to scroll: UP, DOWN, LEFT, RIGHT
- amount - Number of pixels to scroll (number)
例子：
¥Examples:
笔记： - 平滑滚动动画 - 适用于无限滚动页面 - 数量可以大于视口
¥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:
参数： -x - X 坐标（像素）（数字）-y - Y 坐标（像素）（数字）
¥Parameters:
- x - X coordinate in pixels (number)
- y - Y coordinate in pixels (number)
例子：
¥Examples:
笔记： - 触发悬停效果 - 适用于测试鼠标悬停交互 - 不点击，仅移动光标
¥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:
参数： -x1 ，y1 - 起始坐标（数字） -x2 ，y2 - 结束坐标（数字）
¥Parameters:
- x1, y1 - Starting coordinates (numbers)
- x2, y2 - Ending coordinates (numbers)
例子：
¥Examples:
笔记： - 模拟点击、拖动和释放 - 适用于滑块、调整大小、重新排序 - 平滑的拖动动画
¥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:
参数： -text - 要输入的文本（引号中的字符串）
¥Parameters:
- text - Text to type (string in quotes)
例子：
¥Examples:
笔记： - 需要输入元素获得焦点 - 按照实际时间逐个字符输入 - 支持特殊字符和 Unicode
¥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:
参数： -variable - 变量名称（不带引号）
¥Parameters:
- variable - Variable name (without quotes)
例子：
¥Examples:
笔记： - 变量必须先用 SETVAR 定义 - 变量值是字符串 - 适用于可重复使用的凭证或数据
¥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:
参数： -key - 键名（见下面支持的键）
¥Parameters:
- key - Key name (see supported keys below)
支持的按键： -Tab ，Enter ，Escape ，Space -ArrowUp ，ArrowDown ，ArrowLeft ，ArrowRight -Delete ，Backspace -Home ，End ，PageUp ，PageDown
¥Supported Keys:
- Tab, Enter, Escape, Space
- ArrowUp, ArrowDown, ArrowLeft, ArrowRight
- Delete, Backspace
- Home, End, PageUp, PageDown
例子：
¥Examples:
笔记： - 模拟实际的按键按下和释放 - 适用于表单导航和快捷方式 - 区分大小写的键名
¥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 - 修饰键：Shift ，Control ，Alt ，Meta
¥Parameters:
- key - Modifier key: Shift, Control, Alt, Meta
例子：
¥Examples:
笔记： - 必须与 KEY_UP 配对 - 适用于组合键 - Meta 键在 Mac 上为 Cmd，在 PC 上为 Windows 键
¥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 - 修饰键：Shift ，Control ，Alt ，Meta
¥Parameters:
- key - Modifier key: Shift, Control, Alt, Meta
例子：
¥Examples:
笔记： - 必须与 KEY_DOWN 配对 - 释放指定的修饰键 - 始终释放按住的键的良好做法
¥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:
参数： -selector - 输入元素的 CSS 选择器（反引号中的字符串）
¥Parameters:
- selector - CSS selector for input element (string in backticks)
例子：
¥Examples:
笔记： - 适用于输入、文本区域元素 - 比全选和删除更快 - 触发适当的更改事件
¥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:
参数： -selector - 输入元素的 CSS 选择器（反引号中的字符串）-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."
笔记： - 直接设置值，无需输入动画 - 对于长文本比 TYPE 更快 - 触发更改和输入事件
¥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:
参数： -selector - 要检查的 CSS 选择器（反引号中的字符串）-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
笔记： - 执行时检查元素是否存在 - 不等待元素出现 - 可以与 ELSE 结合使用
¥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:
参数： -selector - 要检查的 CSS 选择器（反引号中的字符串）- 第一个command- 如果条件为真则执行 - 第二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:
参数： -selector - 要检查的 CSS 选择器（反引号中的字符串）-command - 如果元素不存在则执行的命令
¥Parameters:
- selector - CSS selector to check (string in backticks)
- command - Command to execute if element doesn't exist
例子：
¥Examples:
笔记： - EXISTS 条件的逆 - 适用于错误处理 - 可以检查是否缺少必需元素
¥Notes: - Inverse of EXISTS condition - Useful for error handling - Can check for missing required elements
IF (<javascript>) THEN <command>
根据 JavaScript 条件执行命令。
¥Execute command based on JavaScript condition.
句法：
¥Syntax:
参数： -javascript - 返回布尔值（反引号中的字符串）的 JavaScript 表达式 -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
笔记： - JavaScript 在浏览器上下文中执行 - 必须返回布尔值 - 访问所有浏览器 API 和全局变量
¥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:
参数： -command - 重复命令 -count - 重复次数（数字）
¥Parameters:
- command - Command to repeat
- count - Number of times to repeat (number)
例子：
¥Examples:
笔记： - 精确执行命令 count 次 - 适用于分页、滚动、导航 - 重复之间没有延迟（如果需要，添加 WAIT）
¥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:
参数： -command - 重复命令 -condition - 要检查的 JavaScript 条件（反引号中的字符串）
¥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`)
笔记： - 每次迭代前检查条件 - JavaScript 条件必须返回布尔值 - 小心避免无限循环
¥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:
参数： -name - 变量名称（字母数字、下划线）-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"
笔记： - 变量在脚本范围内是全局的 - 值始终是字符串 - 可以使用 $variable 语法与 TYPE 命令一起使用
¥Notes: - Variables are global within script scope - Values are always strings - Can be used with TYPE command using $variable syntax
EVAL <javascript>
执行任意 JavaScript 代码。
¥Execute arbitrary JavaScript code.
句法：
¥Syntax:
参数： -javascript - 要执行的 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"`
笔记： - 完全访问浏览器 JavaScript API - 适用于自定义逻辑和调试 - 不捕获返回值 - 注意安全隐患
¥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:
例子：
¥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:
参数： -name - 程序名称（字母数字、下划线）-commands - 包含在程序中的命令
¥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:
例子：
¥Examples:
笔记： - 调用之前必须定义过程 - 可以多次调用 - 不支持参数（使用变量代替）
¥Notes: - Procedure must be defined before calling - Can be called multiple times - No parameters supported (use variables instead)
错误处理最佳实践
¥Error Handling Best Practices
1. 始终使用等待
¥1. Always Use Waits
# Bad - element might not be ready
CLICK `#button`
# Good - wait for element first
WAIT `#button` 5
CLICK `#button`
2.处理可选元素
¥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.使用描述性变量
¥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.添加调试信息
¥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
登录流程
¥Login Flow
# 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
与 Crawl4AI 集成
¥Integration with Crawl4AI
使用 C4A-Script 与 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)
本参考涵盖所有可用的 C4A-Script 命令和模式。如需互动学习，请尝试教程或者现场演示。
¥This reference covers all available C4A-Script commands and patterns. For interactive learning, try the tutorial or live demo.