LibianCrawler Document

暗色模式

Steps API ​

在工程目录下的 ./steps 目录中存放着各个网站的自动化脚本。

API 指南 ​

杂项 ​

异常处理 ​

每个形如 {"fn":"function_name"} 的指令都可以传入 on_success_steps 与 on_timeout_steps 属性，例如:

json
{
  "fn": "page_random_mouse_move",
  "on_success_steps": "continue",
  "on_timeout_steps": "continue"
}

这两个属性的值可以传入 StepsBlock。

on_timeout_steps 将会在函数抛出 常见的超时异常 时发生作用。

常见的超时异常如 playwright.async_api.TimeoutError,asyncio.TimeoutError, TimeoutError 。

  • 当未指定 on_timeout_steps 时，异常将会继续抛出，这很有可能会直接中止爬虫。
  • 当指定 on_timeout_steps 后。将会继续执行 on_timeout_steps 值的指令。

而 on_success_steps 会于没有任何异常抛出时执行，通常用作 on_timeout_steps 的 else 分支

description ​

每个形如 {"fn":"function_name"} 的指令都可以传入 description 属性，例如:

json
{
  "fn": "page_random_mouse_move",
  "description": "正在模拟人类移动鼠标"
}

description 属性不会起任何作用，它仅用于便于人类阅读。

Ref ​

Step 指令列表 ​

dump_page_for_each ​

不停的执行 before_dump_steps 、转储页面、after_dump_steps 这三块步骤。 历次调用的转储页面的 tag 为 f'{dump_tag_prefix}_{count}'。

Params

dump_tag_prefixkwargrequire

标签名

txt
<class 'str'>
json
{
    "type": "string",
    "description": "标签名"
}

before_dump_stepskwargrequire

在 转储页面之前 执行此回调

txt
typing.Optional[ForwardRef('StepsBlock')]
json
{
    "description": "在 转储页面之前 执行此回调",
    "anyOf": [
        {
            "$ref": "#/definitions/StepsBlock"
        },
        {
            "type": "null"
        }
    ]
}

after_dump_stepskwargrequire

在 转储页面之后 执行此回调

txt
typing.Optional[ForwardRef('StepsBlock')]
json
{
    "description": "在 转储页面之后 执行此回调",
    "anyOf": [
        {
            "$ref": "#/definitions/StepsBlock"
        },
        {
            "type": "null"
        }
    ]
}

before_dump_break_by_timeoutkwargoptional

设为 true 后，若在 before_dump_steps 回调执行时发生超时异常，则退出循环。

Examples: false

txt
<class 'bool'>
json
{
    "type": "boolean",
    "description": "设为 true 后，若在 `before_dump_steps` 回调执行时发生超时异常，则退出循环。",
    "examples": [
        false
    ]
}

after_dump_break_by_timeoutkwargoptional

设为 true 后，若在 after_dump_steps 回调执行时发生超时异常，则退出循环。

Examples: false

txt
<class 'bool'>
json
{
    "type": "boolean",
    "description": "设为 true 后，若在 `after_dump_steps` 回调执行时发生超时异常，则退出循环。",
    "examples": [
        false
    ]
}

dump_page_with_uuid ​

直接调用转储页面。 转储页面的 tag 为 f'tag_{tag}_uuid_{uuid4().hex}'。

Params

tagarg[0]require

标签名

txt
<class 'str'>
json
{
    "type": "string",
    "description": "标签名"
}

every_times ​

一个根据该函数运行次数来执行不同代码块的工具函数。 每调用一次此函数，key所对应的全局计数器 +=1。 当全局计数器的值除以 div 的余数等于 expect_mod 时， 运行 if_steps 块，否则执行 else_steps 块。

Params

keykwargrequire

全局计数器 key 。调用此函数后，该计数器 +=1 。

txt
<class 'str'>
json
{
    "type": "string",
    "description": "全局计数器 key 。调用此函数后，该计数器 +=1 。"
}

divkwargrequire

除数

txt
<class 'int'>
json
{
    "type": "integer",
    "description": "除数"
}

expect_modkwargoptional

当此数等于 全局计数器值 除以 div 的余数 时，执行 if_steps 块; 否则执行 `else_steps 块。

Examples: 0

json
{
    "type": "integer",
    "description": "当此数等于 全局计数器值 除以 `div` 的余数 时，执行 `if_steps` 块; 否则执行 `else_steps 块。",
    "examples": [
        0
    ]
}

before_stepskwargoptional

不论 expect_mod 是否匹配，该块都会在 if_steps 和 else_steps 块之前被执行。

txt
typing.Optional[ForwardRef('StepsBlock')]
json
{
    "description": "不论 `expect_mod` 是否匹配，该块都会在 `if_steps` 和 `else_steps` 块之前被执行。",
    "anyOf": [
        {
            "$ref": "#/definitions/StepsBlock"
        },
        {
            "type": "null"
        }
    ]
}

if_stepskwargoptional

expect_mod 等于 全局计数器值 除数 div 的余数 时，此块执行。

txt
typing.Optional[ForwardRef('StepsBlock')]
json
{
    "description": "`expect_mod` 等于 全局计数器值 除数 `div` 的余数 时，此块执行。",
    "anyOf": [
        {
            "$ref": "#/definitions/StepsBlock"
        },
        {
            "type": "null"
        }
    ]
}

else_stepskwargoptional

expect_mod 不等于 全局计数器值 除数 div 的余数 时，此块执行。

txt
typing.Optional[ForwardRef('StepsBlock')]
json
{
    "description": "`expect_mod` 不等于 全局计数器值 除数 `div` 的余数 时，此块执行。",
    "anyOf": [
        {
            "$ref": "#/definitions/StepsBlock"
        },
        {
            "type": "null"
        }
    ]
}

after_stepskwargoptional

不论 expect_mod 是否匹配，该块都会在 if_steps 和 else_steps 块之后被执行。

txt
typing.Optional[ForwardRef('StepsBlock')]
json
{
    "description": "不论 `expect_mod` 是否匹配，该块都会在 `if_steps` 和 `else_steps` 块之后被执行。",
    "anyOf": [
        {
            "$ref": "#/definitions/StepsBlock"
        },
        {
            "type": "null"
        }
    ]
}

run_if_steps_on_errorkwargoptional

设为 true 时，如果发生了错误，会仅运行 if_steps 块之后（其他块都不运行）再抛出异常。

Examples: false

json
{
    "type": "boolean",
    "description": "设为 true 时，如果发生了错误，会仅运行 `if_steps` 块之后（其他块都不运行）再抛出异常。",
    "examples": [
        false
    ]
}

expect_download ​

处理浏览器下载事件。

Params

timeoutkwargrequire

超时时间，单位为毫秒。

txt
<class 'float'>
json
{
    "type": "integer",
    "minimum": 33,
    "maximum": 600000,
    "description": "超时时间，单位为毫秒。"
}

run_stepskwargrequire

只有在执行此块时，若发生下载事件才会被捕获。

txt
ForwardRef('StepsBlock')
json
{
    "$ref": "#/definitions/StepsBlock",
    "description": "只有在执行此块时，若发生下载事件才会被捕获。"
}

dump_obj_metakwargoptional

如果发生转储对象，此值将会携带在转储的对象中。

txt
typing.Optional[ForwardRef('JSON')]
json
{
    "description": "如果发生转储对象，此值将会携带在转储的对象中。",
    "anyOf": [
        {
            "$ref": "#/definitions/JSON"
        },
        {
            "type": "null"
        }
    ]
}

dump_csvkwargoptional

如果此值为 true 且下载的文件是 csv 文件，则转储 csv 内容对象。

Examples: false

txt
<class 'bool'>
json
{
    "type": "boolean",
    "description": "如果此值为 true 且下载的文件是 csv 文件，则转储 csv 内容对象。",
    "examples": [
        false
    ]
}

for_each ​

不停的执行 run_steps 块。

Params

run_stepskwargrequire

循环执行此块。

txt
ForwardRef('StepsBlock')
json
{
    "$ref": "#/definitions/StepsBlock",
    "description": "循环执行此块。"
}

gui_confirm ​

弹出gui弹窗，请求程序员确认。常用于在网站登录情景下，请求程序员手动操作浏览器并在完成后点击确认。 等待的过程中程序会暂停执行。

Params

titlekwargrequire

弹出窗口标题

txt
<class 'str'>
json
{
    "type": "string",
    "description": "弹出窗口标题"
}

messagekwargrequire

弹出窗口正文

txt
<class 'str'>
json
{
    "type": "string",
    "description": "弹出窗口正文"
}

if_url_is ​

如果 *args 包含当前页面的 url，则执行 run_steps 块，否则执行 else_steps块。

Params

*argsvarargoptional

run_stepskwargoptional

在 args 数组包含当前页面的 url 时，执行此回调。

txt
typing.Optional[ForwardRef('StepsBlock')]
json
{
    "description": "在 `args` 数组包含当前页面的 url 时，执行此回调。",
    "anyOf": [
        {
            "$ref": "#/definitions/StepsBlock"
        },
        {
            "type": "null"
        }
    ]
}

else_stepskwargoptional

在 args 数组不包含当前页面的 url 时，执行此回调。

txt
typing.Optional[ForwardRef('StepsBlock')]
json
{
    "description": "在 `args` 数组不包含当前页面的 url 时，执行此回调。",
    "anyOf": [
        {
            "$ref": "#/definitions/StepsBlock"
        },
        {
            "type": "null"
        }
    ]
}

logd ​

输出debug级别日志。

Params

*argsvarargrequire

json
{
    "type": "string"
}

loge ​

输出error级别日志。

Params

*argsvarargrequire

json
{
    "type": "string"
}

logi ​

输出info级别日志。

Params

*argsvarargrequire

json
{
    "type": "string"
}

logw ​

输出warn级别日志。

Params

*argsvarargrequire

json
{
    "type": "string"
}

page_click ​

通用的页面点击工具函数。

Params

selectorarg[0]require

playwright 定位元素所使用的 选择器。

txt
typing.Union[str, playwright.async_api._generated.Locator, libiancrawlers.crawlers.smart_crawl.steps_api.XY]
json
{
    "description": "playwright 定位元素所使用的 [选择器](https://playwright.dev/docs/locators)。",
    "anyOf": [
        {
            "type": "string"
        },
        {
            "type": "object",
            "additionalProperties": false,
            "properties": {
                "x": {
                    "type": "number"
                },
                "y": {
                    "type": "number"
                }
            },
            "required": [
                "x",
                "y"
            ]
        }
    ]
}

methodkwargoptional

具体点击事件的类型。

txt
typing.Optional[typing.Literal['click', 'tap', 'dispatch_event_click']]
json
{
    "description": "具体点击事件的类型。\n\n- 当 `selector` 传入 XY 对象 时，使用 [`page.mouse.click`](https://playwright.dev/python/docs/api/class-mouse#mouse-click) 触发点击事件。\n- 当 `selector` 传入 字符串 时，先使用 [`page_or_frame.locator`](https://playwright.dev/python/docs/api/class-locator) 定位元素:\n    - 当 method 为 `click` 时，使用 [`Locator.click`](https://playwright.dev/python/docs/api/class-locator#locator-click) 触发点击事件。\n    - 当 method 为 `tap` 时，使用 [`Locator.tap`](https://playwright.dev/python/docs/api/class-locator#locator-tap) 触发点击事件。\n    - 当 method 为 `dispatch_event_click` 时，使用 [`Locator.dispatch_event(\"click\")`](https://playwright.dev/python/docs/api/class-locator#locator-tap) 触发点击事件。",
    "anyOf": [
        {
            "enum": [
                "click",
                "tap",
                "dispatch_event_click"
            ]
        },
        {
            "type": "null"
        }
    ]
}

on_new_pagekwargoptional

当点击之后有新标签页时的处理方法。

  • 缺省及默认值为 "switch_it_and_run_steps_no_matter_which_page" ，将会自动将当前页面指针指向新页面，但假如没有新页面则无事发生。
  • "ignore" 值将会忽略新页面（且当前页面指针不会指向新页面）。
  • 如果传入 StepsBlock，则先将自动将当前页面指针指向新页面，然后 在新页面中执行此 StepsBlock ，并且会在 StepsBlock 块完毕后自动将当前页面指针指回旧页面 。
txt
typing.Union[typing.Literal['switch_it_and_run_steps_no_matter_which_page', 'ignore'], ForwardRef('StepsBlock'), NoneType]
json
{
    "description": "当点击之后有新标签页时的处理方法。\n\n- 缺省及默认值为 `\"switch_it_and_run_steps_no_matter_which_page\"` ，将会自动将当前页面指针指向新页面，但假如没有新页面则无事发生。\n- `\"ignore\"` 值将会忽略新页面（且当前页面指针不会指向新页面）。\n- 如果传入 StepsBlock，则先将自动将当前页面指针指向新页面，然后 在新页面中执行此 StepsBlock ，并且会在 StepsBlock 块完毕后自动将当前页面指针指回旧页面 。",
    "anyOf": [
        {
            "enum": [
                "switch_it_and_run_steps_no_matter_which_page",
                "ignore"
            ]
        },
        {
            "$ref": "#/definitions/StepsBlock"
        },
        {
            "type": "null"
        }
    ]
}

wait_any_page_create_time_limitkwargoptional

观察是否有新页面创建的等待时间，单位为毫秒。

txt
typing.Optional[float]
json
{
    "type": "integer",
    "minimum": 33,
    "maximum": 600000,
    "description": "观察是否有新页面创建的等待时间，单位为毫秒。"
}

only_main_framekwargoptional

只在页面根 iframe 中寻找元素，设为 false 后将会在页面的所有 iframe 中寻找元素。

Examples: true

txt
<class 'bool'>
json
{
    "type": "boolean",
    "description": "只在页面根 iframe 中寻找元素，设为 false 后将会在页面的所有 iframe 中寻找元素。",
    "examples": [
        true
    ]
}

each_steps_beforekwargoptional

（仅当使用page_or_frame.locator时有效。）当 each_steps_before 或 each_steps_after 非空时，将会点击符合 selector 的所有元素。在点击前会执行 each_steps_before 块。

txt
typing.Optional[ForwardRef('StepsBlock')]
json
{
    "description": "（仅当使用`page_or_frame.locator`时有效。）当 `each_steps_before` 或 `each_steps_after` 非空时，将会点击符合 selector 的所有元素。在点击前会执行 `each_steps_before` 块。",
    "anyOf": [
        {
            "$ref": "#/definitions/StepsBlock"
        },
        {
            "type": "null"
        }
    ]
}

each_steps_afterkwargoptional

（仅当使用page_or_frame.locator时有效。）当 each_steps_before 或 each_steps_after 非空时，将会点击符合 selector 的所有元素。在点击后会执行 each_steps_before 块。

txt
typing.Optional[ForwardRef('StepsBlock')]
json
{
    "description": "（仅当使用`page_or_frame.locator`时有效。）当 `each_steps_before` 或 `each_steps_after` 非空时，将会点击符合 selector 的所有元素。在点击后会执行 `each_steps_before` 块。",
    "anyOf": [
        {
            "$ref": "#/definitions/StepsBlock"
        },
        {
            "type": "null"
        }
    ]
}

timeout_retrykwargoptional

（仅当使用page_or_frame.locator时有效。）仅点击操作的超时重试次数。

Examples: 0

txt
<class 'int'>
json
{
    "type": "integer",
    "description": "（仅当使用`page_or_frame.locator`时有效。）仅点击操作的超时重试次数。",
    "examples": [
        0
    ]
}

close_new_pagekwargoptional

设为 true 时，在 on_new_page 块执行完成后关闭新页面。

Examples: false

txt
<class 'bool'>
json
{
    "type": "boolean",
    "description": "设为 true 时，在 on_new_page 块执行完成后关闭新页面。",
    "examples": [
        false
    ]
}

trialkwargoptional

传递给 Locator.click 或 Locator.tap 的可选参数。

设置为 true 后，此方法仅执行 actionability 检查并跳过操作。 默认为 false。

这在等待元素准备好执行操作而不执行操作很有用。 请注意，无论 trial 如何，键盘 修饰键 都会被按下，以允许测试仅在按下这些键时才可见的元素。

txt
typing.Optional[bool]
json
{
    "description": "传递给 `Locator.click` 或 `Locator.tap` 的可选参数。\n\n设置为 true 后，此方法仅执行 [actionability](https://playwright.dev/docs/actionability) 检查并跳过操作。\n默认为 false。\n\n这在等待元素准备好执行操作而不执行操作很有用。\n请注意，无论 trial 如何，键盘 修饰键 都会被按下，以允许测试仅在按下这些键时才可见的元素。",
    "anyOf": [
        {
            "type": "boolean"
        },
        {
            "type": "null"
        }
    ]
}

no_wait_afterkwargoptional

传递给 Locator.click 或 Locator.tap 的可选参数。 此参数已经被 playwright 弃用。

txt
typing.Optional[bool]
json
{
    "description": "传递给 `Locator.click` 或 `Locator.tap` 的可选参数。\n此参数已经被 playwright 弃用。",
    "anyOf": [
        {
            "type": "boolean"
        },
        {
            "type": "null"
        }
    ]
}

forcekwargoptional

传递给 Locator.click 或 Locator.tap 的可选参数。 设为 true 将不进行 actionability 检查而强行点击。

txt
typing.Optional[bool]
json
{
    "description": "传递给 `Locator.click` 或 `Locator.tap` 的可选参数。\n设为 true 将不进行 [actionability](https://playwright.dev/docs/actionability) 检查而强行点击。",
    "anyOf": [
        {
            "type": "boolean"
        },
        {
            "type": "null"
        }
    ]
}

positionkwargoptional

传递给 Locator.click 或 Locator.tap 的可选参数

txt
typing.Optional[playwright._impl._api_structures.Position]
json
{
    "description": "传递给 `Locator.click` 或 `Locator.tap` 的可选参数",
    "anyOf": [
        {
            "type": "object",
            "additionalProperties": false,
            "properties": {
                "x": {
                    "type": "number"
                },
                "y": {
                    "type": "number"
                }
            },
            "required": [
                "x",
                "y"
            ]
        },
        {
            "type": "null"
        }
    ]
}

on_locatorkwargoptional

当需要在 page_or_frame.locator 的结果上再调用 Locator 的以下函数(均为返回一个新 Locator 的函数)时，可以传入 OnLocatorBlock 进行链式调用:

  • get_by_text
  • get_by_alt_text
  • get_by_role
txt
typing.Optional[ForwardRef('OnLocatorBlock')]
json
{
    "description": "当需要在 `page_or_frame.locator` 的结果上再调用 [`Locator`](https://playwright.dev/docs/api/class-locator)\n的以下函数(均为返回一个新 Locator 的函数)时，可以传入 OnLocatorBlock 进行链式调用:\n\n- `get_by_text`\n- `get_by_alt_text`\n- `get_by_role`",
    "anyOf": [
        {
            "$ref": "#/definitions/OnLocatorBlock"
        },
        {
            "type": "null"
        }
    ]
}

click_countkwargoptional

传递给 page.mouse.click 或 Locator.click 的可选参数

txt
typing.Optional[int]
json
{
    "description": "传递给 `page.mouse.click` 或 `Locator.click` 的可选参数",
    "anyOf": [
        {
            "type": "integer"
        },
        {
            "type": "null"
        }
    ]
}

buttonkwargoptional

传递给 page.mouse.click 或 Locator.click 的可选参数

txt
typing.Optional[typing.Literal['left', 'middle', 'right']]
json
{
    "description": "传递给 `page.mouse.click` 或 `Locator.click` 的可选参数",
    "anyOf": [
        {
            "enum": [
                "left",
                "middle",
                "right"
            ]
        },
        {
            "type": "null"
        }
    ]
}

delaykwargoptional

传递给 page.mouse.click 或 Locator.click 或 Locator.tap 的可选参数

json
{
    "type": "number",
    "minimum": 0
}

has_no_textkwargoptional

（仅当使用page_or_frame.locator时有效。）定位不包含此文本的元素。

json
{
    "type": "string"
}

has_textkwargoptional

（仅当使用page_or_frame.locator时有效。）定位包含此文本的元素。

json
{
    "type": "string"
}

timeoutkwargoptional

超时时间，单位为毫秒。

json
{
    "type": "integer",
    "minimum": 33,
    "maximum": 600000,
    "description": "超时时间，单位为毫秒。"
}

page_click_and_expect_element_destroy ​

点击页面上的 selector 元素并期望该 selector 元素消失，如果在点击后该 selector 元素没有消失将会重新点击。

Params

selectorarg[0]require

playwright 定位元素所使用的 选择器。

txt
typing.Union[str, playwright.async_api._generated.Locator, libiancrawlers.crawlers.smart_crawl.steps_api.XY]
json
{
    "description": "playwright 定位元素所使用的 [选择器](https://playwright.dev/docs/locators)。",
    "anyOf": [
        {
            "type": "string"
        },
        {
            "type": "object",
            "additionalProperties": false,
            "properties": {
                "x": {
                    "type": "number"
                },
                "y": {
                    "type": "number"
                }
            },
            "required": [
                "x",
                "y"
            ]
        }
    ]
}

on_exist_stepskwargoptional

当 selector 元素未消失且 retry_count < retry_limit 时，执行此块。

txt
typing.Optional[ForwardRef('StepsBlock')]
json
{
    "description": "当 selector 元素未消失且 `retry_count < retry_limit` 时，执行此块。",
    "anyOf": [
        {
            "$ref": "#/definitions/StepsBlock"
        },
        {
            "type": "null"
        }
    ]
}

retry_limitkwargoptional

当 selector 元素未消失时，将会重新点击此参数次数。

Examples: 5

json
{
    "type": "integer",
    "description": "当 selector 元素未消失时，将会重新点击此参数次数。",
    "examples": [
        5
    ]
}

page_close ​

关闭当前页面。

page_go_back ​

调用浏览器导航栏返回功能。 https://camoufox.com/python/usage/#enable_cache

Params

wait_untilkwargoptional

传递给 page.go_back 的可选参数。`

txt
typing.Optional[typing.Literal['commit', 'domcontentloaded', 'load', 'networkidle']]
json
{
    "description": "传递给 `page.go_back` 的可选参数。`",
    "anyOf": [
        {
            "enum": [
                "commit",
                "domcontentloaded",
                "load",
                "networkidle"
            ]
        },
        {
            "type": "null"
        }
    ]
}

timeoutkwargoptional

超时时间，单位为毫秒。

json
{
    "type": "integer",
    "minimum": 33,
    "maximum": 600000,
    "description": "超时时间，单位为毫秒。"
}

page_random_mouse_move ​

让浏览器光标在视口中胡乱移动，像人似的装模作样。

page_scroll_down ​

将页面向下滚动到底或最大高度。 当滚到底部时，会上滚一下再下滚，反复多次后若高度不变（没有加载新玩意）则认为滚动完成。 如果指定了 page_click_if_found 属性，则会在合适的时机点击每个符合选择器的元素， 在点击之后还会转储页面 ，并可以指定转储页面前后运行指定的步骤。

Params

delta_ykwargoptional

每次向下滚动的距离因子。实际向下滚动的距离为其的 0.3~1.6 倍。 默认值 233.0 。 建议不要修改，容易出 BUG。

Examples: 233

json
{
    "type": "number",
    "description": "每次向下滚动的距离因子。实际向下滚动的距离为其的 0.3~1.6 倍。 默认值 233.0 。\n建议不要修改，容易出 BUG。",
    "examples": [
        233
    ]
}

intervalkwargoptional

每次向下滚动事件之间的时间间隔因子。实际的间隔时间为它的 0.7~1.3 倍。 默认值 0.5。 建议不要修改，容易出 BUG。

Examples: 0.5

json
{
    "type": "number",
    "description": "每次向下滚动事件之间的时间间隔因子。实际的间隔时间为它的 0.7~1.3 倍。 默认值 0.5。\n建议不要修改，容易出 BUG。",
    "examples": [
        0.5
    ]
}

max_heightkwargoptional

向下滚动的最大高度限制。 如果你需要 gecko 的网页截图功能，请勿设置过高的值，因为它会引发 gecko 截图超过像素上限 的问题。

Examples: 20000

txt
typing.Optional[float]
json
{
    "description": "向下滚动的最大高度限制。\n如果你需要 gecko 的网页截图功能，请勿设置过高的值，因为它会引发 [gecko 截图超过像素上限](https://www.google.com.hk/search?q=Cannot+take+screenshot+larger+than+32767) 的问题。",
    "anyOf": [
        {
            "type": "number"
        },
        {
            "type": "null"
        }
    ],
    "examples": [
        20000
    ]
}

retry_scroll_up_limitkwargoptional

默认值 2 。当 没有发现新加载的内容 时，会 试图向上滚动再向下滚动检查 此次数。 当该过程中发现了新加载的内容，清空此计数器并继续向下滚动；

直到此计数器超过该值 或 超过高度上限 时，才会认为页面已经滚动到底。

Examples: 2

txt
<class 'int'>
json
{
    "type": "integer",
    "description": "默认值 2 。当 没有发现新加载的内容 时，会 试图向上滚动再向下滚动检查 此次数。\n当该过程中发现了新加载的内容，清空此计数器并继续向下滚动；\n\n直到此计数器超过该值 或 超过高度上限 时，才会认为页面已经滚动到底。",
    "examples": [
        2
    ]
}

retry_scroll_down_limitkwargoptional

默认值 2 。当发现滚动后高度和上次一致时，再向下滚动此次数，若还是一致或高度缩短，则认为 没有发现新加载的内容。

Examples: 2

txt
<class 'int'>
json
{
    "type": "integer",
    "description": "默认值 2 。当发现滚动后高度和上次一致时，再向下滚动此次数，若还是一致或高度缩短，则认为 没有发现新加载的内容。",
    "examples": [
        2
    ]
}

page_click_if_foundkwargoptional

当指定此值时，将会在向下滚动的过程中不断的将 满足 locator 属性的选择器要求的元素 的位置收集入列表中。

仅当同时满足 元素可以被点击、元素出现在视口内、元素的长宽均超过10 时，将会点击此元素。 如果没满足点击条件，则会保留在列表中，直到满足条件才被点击并移出列表，（或是因已经划过高度而跳过）。

txt
typing.Optional[libiancrawlers.crawlers.smart_crawl.steps_api.PageScrollDownPageClickIfFound]
json
{
    "description": "当指定此值时，将会在向下滚动的过程中不断的将 满足 locator 属性的选择器要求的元素 的位置收集入列表中。\n\n仅当同时满足 元素可以被点击、元素出现在视口内、元素的长宽均超过10 时，将会点击此元素。\n如果没满足点击条件，则会保留在列表中，直到满足条件才被点击并移出列表，（或是因已经划过高度而跳过）。",
    "anyOf": [
        {
            "type": "object",
            "additionalProperties": false,
            "properties": {
                "locator": {
                    "type": "string",
                    "description": "传递给 `page.locator(locator, **kwargs)` 的参数。"
                },
                "not_clickable_top_margin": {
                    "description": "向下滚动中点击元素时，不会点击距离窗口顶部的距离小于此值的位置。通常用于一些有 sticky 顶栏的网站，以免误触到顶栏",
                    "anyOf": [
                        {
                            "type": "number"
                        },
                        {
                            "type": "null"
                        }
                    ]
                },
                "duplicated_only_text": {
                    "description": "在找到满足 `locator` 的全部元素后，需要根据特定的方法，\n来判别多次查询到的元素列表中，“新旧查询中是否为同一个元素”的对应关系。\n\n旧的已经被点击过的元素不会再次点击，“判断是不是旧”的通过这里指定的 key 算法。\n\n如果 `duplicated_only_text` 为 False（默认值），\n则将 `element.inner_text()[0:30] + \"_\" + md5(element.inner_html())` 作为 key 。\n\n如果 `duplicated_only_text` 为 True，\n则将 `element.inner_text()[0:30]` 作为 key 。",
                    "anyOf": [
                        {
                            "type": "boolean"
                        },
                        {
                            "type": "null"
                        }
                    ]
                },
                "on_before_click_steps": {
                    "description": "在点击元素之前，执行此回调。",
                    "anyOf": [
                        {
                            "$ref": "#/definitions/StepsBlock"
                        },
                        {
                            "type": "null"
                        }
                    ]
                },
                "check_selector_exist_after_click": {
                    "description": "传入此值后。在点击满足 `locator` 的某元素后，检查页面上是否出现满足此参数 selector 的元素。\n如果存在，则继续执行；如果不存在，则处理下一个元素。\n\n如果不传入此值，则继续执行。",
                    "anyOf": [
                        {
                            "type": "string"
                        },
                        {
                            "type": "null"
                        }
                    ]
                },
                "on_before_click_check_steps": {
                    "description": "在点击元素之后，检查另一个元素是否存在之前，执行此回调。\n不管 `check_selector_exist_after_click` 是否为 True，此回调都会执行。",
                    "anyOf": [
                        {
                            "$ref": "#/definitions/StepsBlock"
                        },
                        {
                            "type": "null"
                        }
                    ]
                },
                "on_before_dump_steps": {
                    "description": "在转储页面被调用之前一刹那，执行此回调。\n\n关于自动转储页面的时机:\n- 如果 `on_new_page` 不为 `\"ignore\"`，且有新页面出现，则:\n    - 如果 `on_new_page` 为缺省值 `\"switch_it_and_run_steps_no_matter_which_page\"` ，则在 新页面被切换到之后 转储页面。\n    - 如果 `on_new_page` 为回调块，则在 新页面被切换到之后、且回调块执行完之后 转储页面。\n- 如果上述情况均不满足。\n    - 在 `check_selector_exist_after_click` 通过后 转储页面。",
                    "anyOf": [
                        {
                            "$ref": "#/definitions/StepsBlock"
                        },
                        {
                            "type": "null"
                        }
                    ]
                },
                "detail_logd": {
                    "description": "输出详细日志。",
                    "anyOf": [
                        {
                            "type": "boolean"
                        },
                        {
                            "type": "null"
                        }
                    ]
                },
                "on_after_dump_steps": {
                    "description": "在转储页面被调用之后一刹那，执行此回调。",
                    "anyOf": [
                        {
                            "$ref": "#/definitions/StepsBlock"
                        },
                        {
                            "type": "null"
                        }
                    ]
                },
                "on_new_page": {
                    "description": "传递给 `self.page_click` 的可选参数。\n\n\n当点击之后有新标签页时的处理方法。\n\n- 缺省及默认值为 `\"switch_it_and_run_steps_no_matter_which_page\"` ，将会自动将当前页面指针指向新页面，但假如没有新页面则无事发生。\n- `\"ignore\"` 值将会忽略新页面（且当前页面指针不会指向新页面）。\n- 如果传入 StepsBlock，则先将自动将当前页面指针指向新页面，然后 在新页面中执行此 StepsBlock ，并且会在 StepsBlock 块完毕后自动将当前页面指针指回旧页面 。",
                    "anyOf": [
                        {
                            "enum": [
                                "switch_it_and_run_steps_no_matter_which_page",
                                "ignore"
                            ]
                        },
                        {
                            "$ref": "#/definitions/StepsBlock"
                        },
                        {
                            "type": "null"
                        }
                    ]
                },
                "close_new_page": {
                    "description": "传递给 `self.page_click` 的可选参数。\n\n设为 true 时，在 on_new_page 块执行完成后关闭新页面。",
                    "anyOf": [
                        {
                            "type": "boolean"
                        },
                        {
                            "type": "null"
                        }
                    ]
                }
            },
            "required": [
                "locator"
            ]
        },
        {
            "type": "null"
        }
    ]
}

page_type ​

通用的输入文本的工具函数。默认使用 page_or_frame.type 进行输入（可使用 use_fill 或 use_select_options 更改）。

Params

selectorarg[0]require

playwright 定位元素所使用的 选择器。

txt
<class 'str'>
json
{
    "type": "string",
    "description": "playwright 定位元素所使用的 [选择器](https://playwright.dev/docs/locators)。"
}

textarg[1]require

要输入的值。

txt
<class 'str'>
json
{
    "type": "string",
    "description": "要输入的值。"
}

labelkwargoptional

传递给 page_or_frame.select_option 的可选参数。

txt
typing.Optional[str]
json
{
    "description": "传递给 `page_or_frame.select_option` 的可选参数。",
    "anyOf": [
        {
            "type": "string"
        },
        {
            "type": "null"
        }
    ]
}

indexkwargoptional

传递给 page_or_frame.select_option 的可选参数。

txt
typing.Optional[int]
json
{
    "description": "传递给 `page_or_frame.select_option` 的可选参数。",
    "anyOf": [
        {
            "type": "integer"
        },
        {
            "type": "null"
        }
    ]
}

use_select_optionskwargoptional

使用 page_or_frame.select_option 在 select 标签中选择。

txt
typing.Optional[bool]
json
{
    "description": "使用 `page_or_frame.select_option` 在 select 标签中选择。",
    "anyOf": [
        {
            "type": "boolean"
        },
        {
            "type": "null"
        }
    ]
}

forcekwargoptional

传递给 page_or_frame.fill 或 page_or_frame.select_option 的可选参数。 设为 true 将不进行 actionability 检查而强行输入。

txt
typing.Optional[bool]
json
{
    "description": "传递给 `page_or_frame.fill` 或 `page_or_frame.select_option` 的可选参数。\n设为 true 将不进行 [actionability](https://playwright.dev/docs/actionability) 检查而强行输入。",
    "anyOf": [
        {
            "type": "boolean"
        },
        {
            "type": "null"
        }
    ]
}

use_fillkwargoptional

使用 page_or_frame.fill 重新填充文本框。

txt
typing.Optional[bool]
json
{
    "description": "使用 `page_or_frame.fill` 重新填充文本框。",
    "anyOf": [
        {
            "type": "boolean"
        },
        {
            "type": "null"
        }
    ]
}

strictkwargoptional

传递给 page_or_frame.type 或 page_or_frame.fill 或 page_or_frame.select_option 的可选参数。设为 true 时将确保符合条件的元素只有一个。

txt
typing.Optional[bool]
json
{
    "description": "传递给 `page_or_frame.type` 或 `page_or_frame.fill` 或 `page_or_frame.select_option` 的可选参数。设为 true 时将确保符合条件的元素只有一个。",
    "anyOf": [
        {
            "type": "boolean"
        },
        {
            "type": "null"
        }
    ]
}

no_wait_afterkwargoptional

传递给 page_or_frame.type 或 page_or_frame.fill 或 page_or_frame.select_option 的可选参数。 此参数已经被 playwright 弃用。

txt
typing.Optional[bool]
json
{
    "description": "传递给 `page_or_frame.type` 或 `page_or_frame.fill` 或 `page_or_frame.select_option` 的可选参数。\n此参数已经被 playwright 弃用。",
    "anyOf": [
        {
            "type": "boolean"
        },
        {
            "type": "null"
        }
    ]
}

delaykwargoptional

传递给 page_or_frame.type 或 page_or_frame.fill 的可选参数

json
{
    "type": "number",
    "minimum": 0
}

timeoutkwargoptional

超时时间，单位为毫秒。

json
{
    "type": "integer",
    "minimum": 33,
    "maximum": 600000,
    "description": "超时时间，单位为毫秒。"
}

only_main_framekwargoptional

只在页面根 iframe 中寻找元素，设为 false 后将会在页面的所有 iframe 中寻找元素。

txt
typing.Optional[bool]
json
{
    "description": "只在页面根 iframe 中寻找元素，设为 false 后将会在页面的所有 iframe 中寻找元素。",
    "anyOf": [
        {
            "type": "boolean"
        },
        {
            "type": "null"
        }
    ]
}

page_type_days_ranges_iter ​

用于在一些日期范围选择器组件中输入日期范围的工具函数。 该函数会遍历 [StartDate, EndDate][] 并将其输出到日期范围选择器组件中。

Params

startkwargrequire

起始日期，可以传入 now 或 YMDParam(形如 [2025,6,24] 或 "2025-6-24" 之类的日期格式)

Examples: "now" [2025,3,31] "2025-4-25"

txt
typing.Union[typing.Literal['now'], ForwardRef('YMDParam'), str]
json
{
    "description": "起始日期，可以传入 `now` 或 YMDParam(形如 `[2025,6,24]` 或 `\"2025-6-24\" 之类的日期格式)`",
    "anyOf": [
        {
            "enum": [
                "now"
            ]
        },
        {
            "$ref": "#/definitions/YMDParam"
        },
        {
            "type": "string"
        }
    ],
    "examples": [
        "now",
        [
            2025,
            3,
            31
        ],
        "2025-4-25"
    ]
}

offset_daykwargrequire

日期步长。可以传入正整数或负整数，不能传入0。

传入正整数会 yield (今天, 明天),(明天, 后天),... ; 传入负整数会 yield (今天, 昨天),(昨天, 前天),... ;

Examples: 1 -1 2 -2 7 -7 15 -15

txt
typing.Union[int, str]
json
{
    "description": "日期步长。可以传入正整数或负整数，不能传入0。\n\n传入正整数会 yield (今天, 明天),(明天, 后天),... ;\n传入负整数会 yield (今天, 昨天),(昨天, 前天),... ;",
    "anyOf": [
        {
            "type": "integer"
        },
        {
            "type": "string"
        }
    ],
    "examples": [
        1,
        -1,
        2,
        -2,
        7,
        -7,
        15,
        -15
    ]
}

stop_untilkwargrequire

停止日期 或 停止循环次数。传入 integer 为停止循环次数，传入 YMDParam(形如 [2025,6,24] 或 `"2025-6-24" 之类的日期格式) 为停止日期。

Examples: 3 15 30 60 [2025,6,20] "2025-6-20"

txt
typing.Union[int, ForwardRef('YMDParam')]
json
{
    "description": "停止日期 或 停止循环次数。传入 integer 为停止循环次数，传入 YMDParam(形如 `[2025,6,24]` 或 `\"2025-6-24\" 之类的日期格式) 为停止日期。",
    "anyOf": [
        {
            "type": "integer"
        },
        {
            "$ref": "#/definitions/YMDParam"
        }
    ],
    "examples": [
        3,
        15,
        30,
        60,
        [
            2025,
            6,
            20
        ],
        "2025-6-20"
    ]
}

yield_stop_until_value_if_end_value_not_equalkwargoptional

当停止日期不在步长倍数上时，设为 true 将 yield (最后一步, 停止日期)。默认值为 true

Examples: true

txt
<class 'bool'>
json
{
    "type": "boolean",
    "description": "当停止日期不在步长倍数上时，设为 true 将 yield (最后一步, 停止日期)。默认值为 true",
    "examples": [
        true
    ]
}

end_offsetkwargoptional

截止时间点的偏移量，单位为天。会令输出变为 (date1, date2+end_offset), (date2, date3+offset), ...

Examples: 0 0 3 7 -1

txt
<class 'int'>
json
{
    "type": "integer",
    "description": "截止时间点的偏移量，单位为天。会令输出变为 (date1, date2+end_offset), (date2, date3+offset), ...",
    "examples": [
        0,
        0,
        3,
        7,
        -1
    ]
}

time_formatkwargoptional

输出时间格式

Examples: "%Y-%m-%d"

txt
<class 'str'>
json
{
    "type": "string",
    "description": "输出时间格式",
    "examples": [
        "%Y-%m-%d"
    ]
}

delaykwargoptional

传递给 self.page_type 的可选参数

txt
typing.Optional[float]
json
{
    "type": "number",
    "minimum": 0
}

timeoutkwargoptional

传递给 self.page_type 的可选参数

txt
typing.Optional[float]
json
{
    "type": "integer",
    "minimum": 33,
    "maximum": 600000,
    "description": "传递给 `self.page_type` 的可选参数"
}

strictkwargoptional

传递给 self.page_type 的可选参数

Examples: true

txt
typing.Optional[bool]
json
{
    "description": "传递给 `self.page_type` 的可选参数",
    "anyOf": [
        {
            "type": "boolean"
        },
        {
            "type": "null"
        }
    ],
    "examples": [
        true
    ]
}

only_main_framekwargoptional

传递给 self.page_type 的可选参数

txt
typing.Optional[bool]
json
{
    "description": "传递给 `self.page_type` 的可选参数",
    "anyOf": [
        {
            "type": "boolean"
        },
        {
            "type": "null"
        }
    ]
}

use_fillkwargoptional

传递给 self.page_type 的可选参数

txt
typing.Optional[bool]
json
{
    "description": "传递给 `self.page_type` 的可选参数",
    "anyOf": [
        {
            "type": "boolean"
        },
        {
            "type": "null"
        }
    ]
}

forcekwargoptional

传递给 self.page_type 的可选参数

txt
typing.Optional[bool]
json
{
    "description": "传递给 `self.page_type` 的可选参数",
    "anyOf": [
        {
            "type": "boolean"
        },
        {
            "type": "null"
        }
    ]
}

begin_selectorkwargoptional

playwright 定位元素所使用的 选择器。 。起始日期将会被输入到此元素

txt
typing.Union[str, playwright.async_api._generated.Locator, libiancrawlers.crawlers.smart_crawl.steps_api.XY, NoneType]
json
{
    "description": "playwright 定位元素所使用的 [选择器](https://playwright.dev/docs/locators)。\n。起始日期将会被输入到此元素",
    "anyOf": [
        {
            "type": "string"
        },
        {
            "type": "object",
            "additionalProperties": false,
            "properties": {
                "x": {
                    "type": "number"
                },
                "y": {
                    "type": "number"
                }
            },
            "required": [
                "x",
                "y"
            ]
        },
        {
            "type": "null"
        }
    ]
}

end_selectorkwargoptional

playwright 定位元素所使用的 选择器。 。截止日期将会被输入到此元素

txt
typing.Union[str, playwright.async_api._generated.Locator, libiancrawlers.crawlers.smart_crawl.steps_api.XY, NoneType]
json
{
    "description": "playwright 定位元素所使用的 [选择器](https://playwright.dev/docs/locators)。\n。截止日期将会被输入到此元素",
    "anyOf": [
        {
            "type": "string"
        },
        {
            "type": "object",
            "additionalProperties": false,
            "properties": {
                "x": {
                    "type": "number"
                },
                "y": {
                    "type": "number"
                }
            },
            "required": [
                "x",
                "y"
            ]
        },
        {
            "type": "null"
        }
    ]
}

steps_before_beginkwargoptional

输入起始日期之前的回调（起始日期不一定在截止日期之前输入，因为有的日期选择器组件会限制输入）

txt
typing.Optional[ForwardRef('StepsBlock')]
json
{
    "description": "输入起始日期之前的回调（起始日期不一定在截止日期之前输入，因为有的日期选择器组件会限制输入）",
    "anyOf": [
        {
            "$ref": "#/definitions/StepsBlock"
        },
        {
            "type": "null"
        }
    ]
}

steps_after_beginkwargoptional

输入起始日期之后的回调（起始日期不一定在截止日期之前输入，因为有的日期选择器组件会限制输入）

txt
typing.Optional[ForwardRef('StepsBlock')]
json
{
    "description": "输入起始日期之后的回调（起始日期不一定在截止日期之前输入，因为有的日期选择器组件会限制输入）",
    "anyOf": [
        {
            "$ref": "#/definitions/StepsBlock"
        },
        {
            "type": "null"
        }
    ]
}

steps_before_endkwargoptional

输入截止日期之前的回调（起始日期不一定在截止日期之前输入，因为有的日期选择器组件会限制输入）

txt
typing.Optional[ForwardRef('StepsBlock')]
json
{
    "description": "输入截止日期之前的回调（起始日期不一定在截止日期之前输入，因为有的日期选择器组件会限制输入）",
    "anyOf": [
        {
            "$ref": "#/definitions/StepsBlock"
        },
        {
            "type": "null"
        }
    ]
}

steps_after_endkwargoptional

输入截止日期之后的回调（起始日期不一定在截止日期之前输入，因为有的日期选择器组件会限制输入）

txt
typing.Optional[ForwardRef('StepsBlock')]
json
{
    "description": "输入截止日期之后的回调（起始日期不一定在截止日期之前输入，因为有的日期选择器组件会限制输入）",
    "anyOf": [
        {
            "$ref": "#/definitions/StepsBlock"
        },
        {
            "type": "null"
        }
    ]
}

steps_after_type_allkwargoptional

两个日期均输入完毕后的回调。

txt
typing.Optional[ForwardRef('StepsBlock')]
json
{
    "description": "两个日期均输入完毕后的回调。",
    "anyOf": [
        {
            "$ref": "#/definitions/StepsBlock"
        },
        {
            "type": "null"
        }
    ]
}

page_wait_for_function ​

等待执行 js 函数。请参考 Camoufox 文档以区分世界隔离机制: https://camoufox.com/python/main-world-eval

Params

*argsvarargoptional

page_wait_for_selector_in_any_frame ​

等待指定的 selector 在任意 Frame 中出现。

Params

selectorarg[0]require

playwright 定位元素所使用的 选择器。

txt
<class 'str'>
json
{
    "type": "string",
    "description": "playwright 定位元素所使用的 [选择器](https://playwright.dev/docs/locators)。"
}

timeoutkwargrequire

超时时间，单位为毫秒。

txt
typing.Optional[float]
json
{
    "type": "integer",
    "minimum": 33,
    "maximum": 600000,
    "description": "超时时间，单位为毫秒。"
}

statekwargoptional

传递给 frame.wait_for_selector 的可选参数

txt
typing.Optional[typing.Literal['attached', 'detached', 'hidden', 'visible']]
json
{
    "description": "传递给 `frame.wait_for_selector` 的可选参数",
    "anyOf": [
        {
            "enum": [
                "attached",
                "detached",
                "hidden",
                "visible"
            ]
        },
        {
            "type": "null"
        }
    ]
}

strictkwargoptional

传递给 frame.wait_for_selector 的可选参数

txt
typing.Optional[bool]
json
{
    "description": "传递给 `frame.wait_for_selector` 的可选参数",
    "anyOf": [
        {
            "type": "boolean"
        },
        {
            "type": "null"
        }
    ]
}

page_wait_loaded ​

这是一个封装好的等待页面加载完成的工具函数。它会调用 page.wait_for_load_state('domcontentloaded')、 page.wait_for_load_state('networkidle')、page.bring_to_front() 等多种方式来等待页面加载完成。

random ​

生成 [0,1) 之间的随机数，如果此数小于等于 probability 则执行 if_steps 块，否则执行 else_steps 块。

Params

probabilitykwargrequire

执行 if_steps 块的概率，介于 [0,1] 之间。

txt
typing.Union[float, str]
json
{
    "description": "执行 `if_steps` 块的概率，介于 [0,1] 之间。",
    "anyOf": [
        {
            "type": "number"
        },
        {
            "type": "string"
        }
    ]
}

if_stepskwargoptional

probability 概率生效时，执行此块

txt
typing.Optional[ForwardRef('StepsBlock')]
json
{
    "description": "`probability` 概率生效时，执行此块",
    "anyOf": [
        {
            "$ref": "#/definitions/StepsBlock"
        },
        {
            "type": "null"
        }
    ]
}

else_stepskwargoptional

probability 概率未生效时，执行此块

txt
typing.Optional[ForwardRef('StepsBlock')]
json
{
    "description": "`probability` 概率未生效时，执行此块",
    "anyOf": [
        {
            "$ref": "#/definitions/StepsBlock"
        },
        {
            "type": "null"
        }
    ]
}

sleep ​

使程序暂停指定毫秒。

Params

totalarg[0]require

睡眠时间，单位为毫秒

txt
<class 'float'>
json
{
    "type": "integer",
    "minimum": 33,
    "maximum": 600000,
    "description": "睡眠时间，单位为毫秒"
}

switch_page ​

切换当前页面指针。

Params

toarg[0]require

要切换到的页面序号。可以传入 "default" 或 整数。

  • 传入 "default" 切换至 启动浏览器时 --url 中的标签页。
  • 传入 0或正整数 时，切换至对应下标的标签页。超出则切换到最后一个。
  • 传入 负整数 时，切换至对应下标的标签页。超出则切换到最后一个。
txt
typing.Union[int, typing.Literal['default'], playwright.async_api._generated.Page]
json
{
    "description": "要切换到的页面序号。可以传入 `\"default\"` 或 整数。\n\n- 传入 `\"default\"` 切换至 启动浏览器时 `--url` 中的标签页。\n- 传入 0或正整数 时，切换至对应下标的标签页。超出则切换到最后一个。\n- 传入 负整数 时，切换至对应下标的标签页。超出则切换到最后一个。",
    "anyOf": [
        {
            "type": "integer"
        },
        {
            "enum": [
                "default"
            ]
        }
    ]
}