API リファレンス — Page クラス
Playwright スタイルの Page 全メソッド。Session は Page を継承するので、ここに書かれた API はすべて session.* でも使えます。
クライアントの接続方法・Session 固有 API・例外・ライブログは API リファレンス(トップ) を参照してください。
Page — ナビゲーション・操作
プロパティ(I/O なし): page.url / session_id / worker_id / lane_idx / novnc_url / page_id。
page.goto(url) → dict
ページを遷移します。result["response"] に Playwright 互換の HTTP レスポンス(status/ok/headers/mime/url)が入ります。pap.response_of(reply) で安全に取り出せます。
reply = await page.goto("https://example.com")
r = pap.response_of(reply) # {url, status, ok, headers, mime}
urlstr — 遷移先 URL
- dict —
result["response"]に HTTP レスポンス
page.back() / forward() / history_first() / reload() → dict
履歴移動・再読み込み(境界で安全)。goto() と同じく result["response"] を持ちます。
await page.back()
await page.reload()
- dict —
result["response"]
page.last_response() → dict
直近のメインドキュメント HTTP レスポンス。クリック起因のナビゲーション(リンク・フォーム送信・location.href=)後の status 取得に使います。常に {url,status,status_text,ok,headers,mime} を返します(status=0 は「未取得」)。
await page.locator(".titleline > a").first.click()
r = await page.last_response()
if r["status"] == 404:
return None
- dict —
{url, status, status_text, ok, headers, mime}
page.click(selector) → dict
要素をクリックします。
await page.click("button.play")
selectorstr — CSS セレクタ。[@N]は[data-paprika-id="N"]に展開
- dict
page.fill(selector, value) → dict
input / textarea に値をセットします(input/change を発火)。
await page.fill("#email", "user@example.com")
selectorstr — CSS セレクタvaluestr — 入力する値
- dict
page.press(key, *, count=1, modifiers=None) → dict
フォーカス要素にキーを送ります。
await page.press("Enter")
await page.press("a", modifiers=["Ctrl"])
keystr — キー名(例"Enter")countint (optional, 1) — 押下回数modifierslist (optional, None) — 例["Ctrl"]
- dict
page.type(text) → dict
フォーカス要素に文字列を挿入します。
await page.type("hello")
textstr — 挿入する文字列
- dict
page.scroll(direction="down", pixels=800) → dict
ページをスクロールします。
await page.scroll("down", 1200)
directionstr (optional, "down") —up/downpixelsint (optional, 800) — スクロール量
- dict
page.hover() / dblclick() / focus() / scroll_into_view_if_needed() → bool
合成入力イベント系。いずれも同じ引数を取ります。複数一致時は index 番目の要素が対象。
await page.hover(".thumb")
await page.dblclick("video")
selectorstr — CSS セレクタindexint (optional, 0) — 何番目の一致要素か
- bool — 成功なら True
page.select_option(selector, value, *, index=0) → bool
<select> の選択肢を選びます。
await page.select_option("#country", "JP")
selectorstr —<select>のセレクタvaluestr — 選択する valueindexint (optional, 0)
- bool
page.check() / uncheck() → bool
チェックボックスを ON / OFF します。
await page.check("#agree")
selectorstr — CSS セレクタindexint (optional, 0)
- bool
page.set_input_files(selector, files) → dict
ファイルアップロード(CDP)。
await page.set_input_files("input[type=file]", ["a.jpg", "b.jpg"])
selectorstr — file input のセレクタfilesstr | list[str] — ファイルパス(単体 or 複数)
- dict
import paprika_client as pap
# HTTP ステータスの取得(Playwright 互換 Response)
reply = await page.goto("https://example.com/missing")
r = pap.response_of(reply) # {url,status,status_text,ok,headers,mime}
if r["status"] == 404:
return None
if not r["ok"]:
raise RuntimeError(f"HTTP {r['status']}")
# クリック起因のナビゲーション後は last_response() を使う
await page.locator(".titleline > a").first.click()
r = await page.last_response()
if r["status"] == 404:
return None
await page.fill("#email", "user@example.com")
await page.press("Enter")
await page.set_input_files("input[type=file]", ["a.jpg", "b.jpg"])import paprika_client as pap
reply = page.goto("https://example.com/missing")
r = pap.response_of(reply)
if r["status"] == 404:
return None
# クリック起因のナビゲーション(sync でも await 不要)
page.locator(".titleline > a").first.click()
r = page.last_response()
if r["status"] == 404:
return None
page.fill("#email", "user@example.com")
page.press("Enter")
page.set_input_files("input[type=file]", ["a.jpg", "b.jpg"])Page — 取得・待機・状態
page.text_content() / inner_text() / inner_html() / input_value() → str | None
要素のテキスト / 表示テキスト / 内部 HTML / 入力値を取得します。一致なしは None。
title = await page.text_content("h1")
selectorstr — CSS セレクタindexint (optional, 0)
- str | None
page.get_attribute(selector, name, *, index=0) → str | None
指定属性の値を取得します。
href = await page.get_attribute("a.next", "href")
selectorstr — CSS セレクタnamestr — 属性名indexint (optional, 0)
- str | None
page.count(selector) → int
セレクタに一致する要素数を返します。
n = await page.count(".item")
selectorstr — CSS セレクタ
- int
page.is_visible() / is_checked() / is_enabled() / is_disabled() / is_editable() → bool
要素の状態を判定します。
if await page.is_visible("#captcha"):
...
selectorstr — CSS セレクタindexint (optional, 0)
- bool
page.exists(selector) → bool
要素の存在チェック(確定的・LLM 不要)。
if await page.exists(".paywall"):
...
selectorstr — CSS セレクタ
- bool
page.wait_for_selector(selector, *, state="visible", timeout=30.0) → bool
要素の出現 / 消失を待ちます。タイムアウト時は False。
await page.wait_for_selector("video", timeout=10)
selectorstr — CSS セレクタstatestr (optional, "visible") —attached/detached/visible/hiddentimeoutfloat (optional, 30.0) — 秒
- bool
page.wait_for(*, seconds=None, ms=None) → None
単純待機。
await page.wait_for(seconds=2)
secondsfloat (optional, None)msint (optional, None)
- None
page.state() → dict
ライブ状態を返します。
s = await page.state() # {url, title, lane_idx, visited_count}
- dict —
{url, title, lane_idx, visited_count}
page.title() / page.outline() → str
ページタイトル / 操作可能要素の一覧([@N] 付き)を返します。
print(await page.outline())
- str
page.links(*, urls_only=False) → list
ページ内の全 <a href> を絶対 URL で返します。
urls = await page.links(urls_only=True)
urls_onlybool (optional, False) — True で URL 文字列のみ、False で text 付き dict
- list
page.visited_urls() → list[str]
このセッションで踏んだ URL の一覧。
seen = await page.visited_urls()
- list[str]
page.screenshot(*, path=None) → bytes
ビューポートの PNG バイト列を返します。
png = await page.screenshot(path="shot.png")
pathstr (optional, None) — 指定するとファイルにも保存
- bytes — PNG データ
Page — JS 実行・ロケータ生成
page.evaluate(expression, *, await_promise=False) → 値
任意 JS を実行し評価値を返す(JSON 化可能な値のみ)。取得・待機・入力系はこれが土台。
title = await page.evaluate("document.title")
data = await page.evaluate("fetch('/api').then(r=>r.json())", await_promise=True)title = page.evaluate("document.title")
data = page.evaluate("fetch('/api').then(r=>r.json())", await_promise=True)evaluate は Page サーフェスの一部として今後追加されます)。| ロケータ生成 | 意味 |
|---|---|
page.locator(selector) → Locator | CSS セレクタ |
page.get_by_text(text) → Locator | 可視テキスト一致 |
page.get_by_role(role, *, name=None) → Locator | [role=] |
page.get_by_test_id(id) / get_by_placeholder(text) / get_by_title(text) / get_by_alt_text(text) → Locator | 属性セレクタ。詳細は Locator リファレンス を参照 |
Page — 収集・Cookie・LLM・永続状態
page.capture(label="capture") → dict
現在のページの HTML + スクショ + outline を保存します。
await page.capture("after-login")
labelstr (optional, "capture") — 保存時のラベル
- dict
page.assets(*, kind="image", absolute=True, refresh=True, details=False) → list
このセッションでキャプチャ済みの asset 一覧(要 parent_job_id)。
imgs = await page.assets(kind="image")
kindstr (optional, "image") — asset 種別absolutebool (optional, True) — 絶対 URL で返すrefreshbool (optional, True) — 最新を取り直すdetailsbool (optional, False) — メタ情報付き
- list
page.save_assets(dest_dir, *, kind="image", refresh=True) → list[str]
キャプチャ済み asset をディスクへ保存し、保存したパス列を返します。
paths = await page.save_assets("./out", kind="image")
dest_dirstr — 保存先ディレクトリkindstr (optional, "image")refreshbool (optional, True)
- list[str] — 保存したファイルパス
page.download_video(url=None, *, referer=None, timeout_s=1800) → dict
yt-dlp / httpx で動画を取得・保存します。url 省略時は検出済みストリームを使います。
await page.download_video(referer="https://supjav.com/")
urlstr (optional, None) — 省略で検出済みストリームrefererstr (optional, None) — CDN 用 Referertimeout_sint (optional, 1800)
- dict
page.cookies(*, host=None, all_cookies=False) → dict
現在の Cookie を取得します。
c = await page.cookies()
hoststr (optional, None) — 対象ホストall_cookiesbool (optional, False)
- dict
page.save_cookies_to_host(*, host=None, notes=None, all_cookies=False) → dict
現在の Cookie を Host レジストリへ保存します(次回以降のセッションに自動注入)。
await page.save_cookies_to_host(notes="logged-in")
hoststr (optional, None)notesstr (optional, None)all_cookiesbool (optional, False)
- dict
page.network(*, since=0.0) → dict
メディア系のネットワークログを取得します。
log = await page.network()
sincefloat (optional, 0.0) — これ以降のエントリ
- dict
page.ask(question, *, engine="auto") → bool
LLM に yes/no を問います。
if await page.ask("認証ダイアログが出ている?"):
...
questionstr — 質問文enginestr (optional, "auto")
- bool
page.agent(goal, *, max_steps=5, engine="auto") → dict
vision / LLM エージェントにゴールを委譲します。
await page.agent("認証画面をクリアして", max_steps=3)
goalstr — 達成目標max_stepsint (optional, 5) — 1–30enginestr (optional, "auto") —auto/qwen/cogagent
- dict
page.get_state(key) / set_state(key, value) → dict | None
親 job に紐づく永続データの読み書き(要 parent_job_id)。
await page.set_state("cursor", {"page": 3})
cur = await page.get_state("cursor")
keystr — キーvalueany —set_stateのみ。保存する値
- dict | None
page.solve_cloudflare(*, timeout_s=25.0) → dict
Cloudflare のチャレンジを待つ / 通します。
await page.solve_cloudflare()
timeout_sfloat (optional, 25.0)
- dict
page.resize_window(width, height) → dict
Chrome のウィンドウサイズを変更します。
await page.resize_window(1280, 720)
widthint — 幅(px)heightint — 高さ(px)
- dict
Page — 拡張機能コマンド(Agent ext)
CDP / nodriver では直接届かない Chrome 機能を、全レーンに常駐する
Paprika Agent 拡張機能経由で呼ぶための API 群です(本物の
ページズーム、リクエストヘッダ書き換え、コンテンツ設定、プライバシー、
ダウンロード、プロキシ、ナビゲーション監視、ユーザースクリプト、拡張管理)。
下の型付きメソッドはすべて汎用 page.ext() の薄いラッパーです。
fetch 実行中のセッションでも呼べます(ブラウザ設定であってページ書き込みではないため)。
{status, result, elapsed_ms})を返し、
実際のペイロードは reply["result"] に入ります(例: set_referer() なら
result["id"])。一覧取得系(net_rules / navigation_events /
installed_extensions / download_status)だけは list を直接返します。
# CDN が iframe URL を Referer に取って弾くプレーヤーを救う(HLS の 403 対策)
await page.set_referer("https://supjav.com/")
# リダイレクト連鎖で開く popup を素通しさせる
await page.allow_popups()
# 本物のページズーム(縮小もできる。CDP の setPageScaleFactor と違い 1.0 未満も有効)
await page.zoom(0.5)
# 広告ドメインを遮断
await page.block_hosts(["ads.example.net", "track.example.com"])
# 型付きラッパーの無い機能は汎用 ext() で(例: 画像読み込みをブロック)
reply = await page.ext("setContentSetting", {"type": "images", "setting": "block"})
print(reply["result"])page.set_referer("https://supjav.com/")
page.allow_popups()
page.zoom(0.5)
page.block_hosts(["ads.example.net"])
reply = page.ext("setContentSetting", {"type": "images", "setting": "block"})page.ext(cmd, args=None, *, timeout=20.0) → dict
拡張機能の任意コマンドを実行する汎用パススルー。下の全ラッパーはこれの薄い別名で、新しい能力も「拡張にハンドラ+ここにラッパー」だけで増やせます。
reply = await page.ext("setContentSetting", {"type": "images", "setting": "block"})
print(reply["result"])
cmdstr — 拡張側ハンドラ名(例"netSetHeader")argsdict (optional, None) — ハンドラへ渡す引数timeoutfloat (optional, 20.0) — 応答待ちの秒数
- dict — reply 全体
{status, result, elapsed_ms}。ペイロードはresult
page.zoom(factor) / page.set_zoom(factor) → dict
本物のページズーム。リフローを伴い全画面クロスオリジン iframe プレーヤーにも効きます。CDP の setPageScaleFactor と違い 1.0 未満(縮小)も有効。
await page.zoom(0.5) # 50% に縮小
await page.zoom(1.0) # 等倍に戻す
factorfloat — 倍率。1.0 = 100%、範囲 0.25–5.0
- dict —
result["factor"]とresult["method"]("chrome.tabs.setZoom"なら本物のズーム成功)
page.set_referer(value, *, url_filter="*") → dict
マッチする URL に Referer リクエストヘッダを強制します。CDN/HLS が iframe の URL を Referer に取って 403 を返すプレーヤーの救済に使います。
await page.set_referer("https://supjav.com/")
valuestr — 設定する Referer の値url_filterstr (optional, "*") — 適用先 URL パターン
- dict —
result["id"]にルール ID
page.set_request_header(header, value, *, url_filter="*", rule_id=2000) → dict
任意のリクエストヘッダを強制します(declarativeNetRequest の modifyHeaders)。同じ rule_id で呼ぶとルールを置き換えます。
await page.set_request_header("X-Requested-With", "XMLHttpRequest")
headerstr — ヘッダ名valuestr — ヘッダ値url_filterstr (optional, "*") — 適用先 URL パターンrule_idint (optional, 2000) — 同 ID で上書き
- dict —
result["id"]
page.block_hosts(hosts) → dict
指定したドメインへの全リクエストを遮断します(広告・トラッカー除去)。
await page.block_hosts(["ads.example.net", "track.example.com"])
hostslist[str] — 遮断するドメインの列
- dict —
result["added"]に追加ルール件数
page.net_rules() → list[dict]
現在有効な動的ネットワークルール(ブロック・ヘッダ書き換え)の一覧を返します。
rules = await page.net_rules()
- list[dict] — 動的 declarativeNetRequest ルール
page.clear_net_rules() → dict
すべての動的ネットワークルールを削除します。
await page.clear_net_rules()
- dict —
result["removed"]に削除件数
page.set_content_setting(type, setting, *, pattern="*://*/*") → dict
サイト別のコンテンツ設定を変更します。
await page.set_content_setting("images", "block")
typestr —popups/images/javascript/automaticDownloads等settingstr —allow/block/session_only/askpatternstr (optional, "*://*/*") — 適用先パターン
- dict
page.allow_popups(*, pattern="*://*/*") → dict
popup を許可します(リダイレクト連鎖で別窓を開くプレーヤー対策)。set_content_setting("popups", "allow") の別名。
await page.allow_popups()
patternstr (optional, "*://*/*") — 適用先パターン
- dict
page.allow_auto_downloads(*, pattern="*://*/*") → dict
複数の自動ダウンロードを確認ダイアログ無しで許可します。
await page.allow_auto_downloads()
patternstr (optional, "*://*/*") — 適用先パターン
- dict
page.set_privacy(path, value) → dict
chrome.privacy の ChromeSetting をドット区切りパスで設定します。
await page.set_privacy("network.webRTCIPHandlingPolicy", "disable_non_proxied_udp")
pathstr — 設定パス(例network.webRTCIPHandlingPolicy)valueany — 設定値
- dict
page.prevent_webrtc_leak() → dict
WebRTC による実 IP 漏洩を防ぎます(プロキシ併用時に重要)。set_privacy のショートカット。
await page.prevent_webrtc_leak()
- dict
page.navigation_events(*, since=0.0) → list[dict]
バッファされた遷移イベント(committed / completed / newtarget / error)を取り出します。newtarget は popup・新規タブの出自(ソースフレーム+URL)を含みます。
events = await page.navigation_events()
for e in events:
print(e["type"], e["url"])
sincefloat (optional, 0.0) — この epoch(ms) 以降のイベントのみ
- list[dict] — 各イベント
{type, url, tabId, frameId, sourceFrameId, ...}
page.download(url, *, filename=None, conflict="uniquify", headers=None) → dict
制御付きのダウンロードを開始します(chrome.downloads)。保存先・ファイル名・追加ヘッダを指定でき、セッションの Cookie を引き継ぎます。
dl = await page.download("https://cdn.example.com/v.mp4", filename="evidence.mp4")
urlstr — ダウンロード URLfilenamestr (optional, None) — 保存ファイル名conflictstr (optional, "uniquify") —uniquify/overwrite/promptheaderslist (optional, None) —[{name, value}]の追加リクエストヘッダ
- dict —
result["download_id"]
page.download_status(*, download_id=None) → list[dict]
ダウンロードの状態を検索します。
items = await page.download_status(download_id=dl["result"]["download_id"])
print(items[0]["state"], items[0]["bytesReceived"])
download_idint (optional, None) — 省略で全件
- list[dict] —
{state, bytesReceived, totalBytes, filename, ...}
page.cancel_download(download_id) → dict
進行中のダウンロードを中止します。
await page.cancel_download(1)
download_idint — ダウンロード ID
- dict
page.set_proxy(host, port, *, scheme="http", bypass=None) → dict
このレーン(Chrome プロファイル)単位の固定プロキシを設定します。タブ単位ではなくプロファイル全体に効きます。認証付きプロキシは非対応。
await page.set_proxy("10.0.0.2", 1080, scheme="socks5")
hoststr — プロキシホストportint — プロキシポートschemestr (optional, "http") —http/https/socks5bypasslist (optional, None) — 直結するドメイン列
- dict —
result["mode"]
page.clear_proxy() → dict
プロキシ設定を解除します。
await page.clear_proxy()
- dict
page.proxy_info() → dict
現在のプロキシ設定を取得します。
info = await page.proxy_info()
- dict —
result["value"]/result["levelOfControl"]
page.register_user_script(id, code, *, matches=None, world="MAIN", run_at="document_idle") → dict
MAIN ワールドへ常駐スクリプトを登録します(プレーヤー API をフックして実ソース URL を露出させる等)。同じ id で更新。
await page.register_user_script("hook", "window.__paprika = jwplayer;")
idstr — スクリプト IDcodestr — JavaScript ソースmatcheslist (optional, ["<all_urls>"]) — 適用先 match パターンworldstr (optional, "MAIN") —MAIN/USER_SCRIPTrun_atstr (optional, "document_idle") — 実行タイミング
- dict —
result["id"]
page.unregister_user_script(id) → dict
登録済みのユーザースクリプトを解除します。
await page.unregister_user_script("hook")
idstr — スクリプト ID
- dict
page.installed_extensions() → list[dict]
このレーンの Chrome にインストール済みの拡張一覧を返します(uBlock 等が有効か検証する用途)。
exts = await page.installed_extensions()
- list[dict] —
{id, name, enabled, version}
page.set_extension_enabled(ext_id, enabled) → dict
他の拡張を有効/無効に切り替えます。
await page.set_extension_enabled("cjpalhdlnbpafiamejdnhcphjbkeiagm", True)
ext_idstr — 対象拡張の IDenabledbool — 有効化するなら True
- dict
Page — タブ・ライフサイクル
page.new_page(url) / page.open(url) → Page
新規タブを開きます。
tab = await page.new_page("https://example.com", switch=True)
urlstr — 開く URLswitchbool (optional, False) — True で新タブを既定に
- Page
page.pages() → list[Page]
セッションの全タブを返します。
tabs = await page.pages()
- list[Page]
page.switch() → dict
このタブを前面(既定)にします。
await tab.switch()
- dict
page.close() → None
タブを閉じます(最後の 1 枚を閉じるとセッション終了)。
await tab.close()
- None
page.keepalive(*, idle_ttl_s=120, absolute_ttl_s=86400) → HandoffInfo
スクリプト終了後もセッションを残し、noVNC で人手に引き継ぎます(別名 detach)。
info = await page.keepalive(idle_ttl_s=600)
idle_ttl_sint (optional, 120) — 無操作での生存秒数absolute_ttl_sint (optional, 86400) — 絶対上限
- HandoffInfo