API リファレンス — Page クラス

Playwright スタイルの Page 全メソッド。SessionPage を継承するので、ここに書かれた API はすべて session.* でも使えます。 クライアントの接続方法・Session 固有 API・例外・ライブログは API リファレンス(トップ) を参照してください。

コード例の表示モード

プロパティ(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) で安全に取り出せます。

Usage
reply = await page.goto("https://example.com")
r = pap.response_of(reply)   # {url, status, ok, headers, mime}
Arguments
  • url str — 遷移先 URL
Returns
  • dictresult["response"] に HTTP レスポンス

page.back() / forward() / history_first() / reload() → dict

履歴移動・再読み込み(境界で安全)。goto() と同じく result["response"] を持ちます。

Usage
await page.back()
await page.reload()
Returns
  • dictresult["response"]

page.last_response() → dict

直近のメインドキュメント HTTP レスポンス。クリック起因のナビゲーション(リンク・フォーム送信・location.href=)後の status 取得に使います。常に {url,status,status_text,ok,headers,mime} を返します(status=0 は「未取得」)。

Usage
await page.locator(".titleline > a").first.click()
r = await page.last_response()
if r["status"] == 404:
    return None
Returns
  • dict{url, status, status_text, ok, headers, mime}

page.click(selector) → dict

要素をクリックします。

Usage
await page.click("button.play")
Arguments
  • selector str — CSS セレクタ。[@N][data-paprika-id="N"] に展開
Returns
  • dict

page.fill(selector, value) → dict

input / textarea に値をセットします(input/change を発火)。

Usage
await page.fill("#email", "user@example.com")
Arguments
  • selector str — CSS セレクタ
  • value str — 入力する値
Returns
  • dict

page.press(key, *, count=1, modifiers=None) → dict

フォーカス要素にキーを送ります。

Usage
await page.press("Enter")
await page.press("a", modifiers=["Ctrl"])
Arguments
  • key str — キー名(例 "Enter"
  • count int (optional, 1) — 押下回数
  • modifiers list (optional, None) — 例 ["Ctrl"]
Returns
  • dict

page.type(text) → dict

フォーカス要素に文字列を挿入します。

Usage
await page.type("hello")
Arguments
  • text str — 挿入する文字列
Returns
  • dict

page.scroll(direction="down", pixels=800) → dict

ページをスクロールします。

Usage
await page.scroll("down", 1200)
Arguments
  • direction str (optional, "down")up / down
  • pixels int (optional, 800) — スクロール量
Returns
  • dict

page.hover() / dblclick() / focus() / scroll_into_view_if_needed() → bool

合成入力イベント系。いずれも同じ引数を取ります。複数一致時は index 番目の要素が対象。

Usage
await page.hover(".thumb")
await page.dblclick("video")
Arguments
  • selector str — CSS セレクタ
  • index int (optional, 0) — 何番目の一致要素か
Returns
  • bool — 成功なら True

page.select_option(selector, value, *, index=0) → bool

<select> の選択肢を選びます。

Usage
await page.select_option("#country", "JP")
Arguments
  • selector str<select> のセレクタ
  • value str — 選択する value
  • index int (optional, 0)
Returns
  • bool

page.check() / uncheck() → bool

チェックボックスを ON / OFF します。

Usage
await page.check("#agree")
Arguments
  • selector str — CSS セレクタ
  • index int (optional, 0)
Returns
  • bool

page.set_input_files(selector, files) → dict

ファイルアップロード(CDP)。

Usage
await page.set_input_files("input[type=file]", ["a.jpg", "b.jpg"])
Arguments
  • selector str — file input のセレクタ
  • files str | list[str] — ファイルパス(単体 or 複数)
Returns
  • 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"])
PHP は順次対応中です(現在は Job API + Session ライフサイクルまで)。当面は HTTP API もご利用ください。

Page — 取得・待機・状態

page.text_content() / inner_text() / inner_html() / input_value() → str | None

要素のテキスト / 表示テキスト / 内部 HTML / 入力値を取得します。一致なしは None

Usage
title = await page.text_content("h1")
Arguments
  • selector str — CSS セレクタ
  • index int (optional, 0)
Returns
  • str | None

page.get_attribute(selector, name, *, index=0) → str | None

指定属性の値を取得します。

Usage
href = await page.get_attribute("a.next", "href")
Arguments
  • selector str — CSS セレクタ
  • name str — 属性名
  • index int (optional, 0)
Returns
  • str | None

page.count(selector) → int

セレクタに一致する要素数を返します。

Usage
n = await page.count(".item")
Arguments
  • selector str — CSS セレクタ
Returns
  • int

page.is_visible() / is_checked() / is_enabled() / is_disabled() / is_editable() → bool

要素の状態を判定します。

Usage
if await page.is_visible("#captcha"):
    ...
Arguments
  • selector str — CSS セレクタ
  • index int (optional, 0)
Returns
  • bool

page.exists(selector) → bool

要素の存在チェック(確定的・LLM 不要)。

Usage
if await page.exists(".paywall"):
    ...
Arguments
  • selector str — CSS セレクタ
Returns
  • bool

page.wait_for_selector(selector, *, state="visible", timeout=30.0) → bool

要素の出現 / 消失を待ちます。タイムアウト時は False

Usage
await page.wait_for_selector("video", timeout=10)
Arguments
  • selector str — CSS セレクタ
  • state str (optional, "visible")attached / detached / visible / hidden
  • timeout float (optional, 30.0) — 秒
Returns
  • bool

page.wait_for(*, seconds=None, ms=None) → None

単純待機。

Usage
await page.wait_for(seconds=2)
Arguments
  • seconds float (optional, None)
  • ms int (optional, None)
Returns
  • None

page.state() → dict

ライブ状態を返します。

Usage
s = await page.state()   # {url, title, lane_idx, visited_count}
Returns
  • dict{url, title, lane_idx, visited_count}

page.title() / page.outline() → str

ページタイトル / 操作可能要素の一覧([@N] 付き)を返します。

Usage
print(await page.outline())
Returns
  • str

page.links(*, urls_only=False) → list

ページ内の全 <a href> を絶対 URL で返します。

Usage
urls = await page.links(urls_only=True)
Arguments
  • urls_only bool (optional, False) — True で URL 文字列のみ、False で text 付き dict
Returns
  • list

page.visited_urls() → list[str]

このセッションで踏んだ URL の一覧。

Usage
seen = await page.visited_urls()
Returns
  • list[str]

page.screenshot(*, path=None) → bytes

ビューポートの PNG バイト列を返します。

Usage
png = await page.screenshot(path="shot.png")
Arguments
  • path str (optional, None) — 指定するとファイルにも保存
Returns
  • 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)
PHP は順次対応中です(evaluate は Page サーフェスの一部として今後追加されます)。
ロケータ生成意味
page.locator(selector) → LocatorCSS セレクタ
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 を保存します。

Usage
await page.capture("after-login")
Arguments
  • label str (optional, "capture") — 保存時のラベル
Returns
  • dict

page.assets(*, kind="image", absolute=True, refresh=True, details=False) → list

このセッションでキャプチャ済みの asset 一覧(要 parent_job_id)。

Usage
imgs = await page.assets(kind="image")
Arguments
  • kind str (optional, "image") — asset 種別
  • absolute bool (optional, True) — 絶対 URL で返す
  • refresh bool (optional, True) — 最新を取り直す
  • details bool (optional, False) — メタ情報付き
Returns
  • list

page.save_assets(dest_dir, *, kind="image", refresh=True) → list[str]

キャプチャ済み asset をディスクへ保存し、保存したパス列を返します。

Usage
paths = await page.save_assets("./out", kind="image")
Arguments
  • dest_dir str — 保存先ディレクトリ
  • kind str (optional, "image")
  • refresh bool (optional, True)
Returns
  • list[str] — 保存したファイルパス

page.download_video(url=None, *, referer=None, timeout_s=1800) → dict

yt-dlp / httpx で動画を取得・保存します。url 省略時は検出済みストリームを使います。

Usage
await page.download_video(referer="https://supjav.com/")
Arguments
  • url str (optional, None) — 省略で検出済みストリーム
  • referer str (optional, None) — CDN 用 Referer
  • timeout_s int (optional, 1800)
Returns
  • dict

page.cookies(*, host=None, all_cookies=False) → dict

現在の Cookie を取得します。

Usage
c = await page.cookies()
Arguments
  • host str (optional, None) — 対象ホスト
  • all_cookies bool (optional, False)
Returns
  • dict

page.save_cookies_to_host(*, host=None, notes=None, all_cookies=False) → dict

現在の Cookie を Host レジストリへ保存します(次回以降のセッションに自動注入)。

Usage
await page.save_cookies_to_host(notes="logged-in")
Arguments
  • host str (optional, None)
  • notes str (optional, None)
  • all_cookies bool (optional, False)
Returns
  • dict

page.network(*, since=0.0) → dict

メディア系のネットワークログを取得します。

Usage
log = await page.network()
Arguments
  • since float (optional, 0.0) — これ以降のエントリ
Returns
  • dict

page.ask(question, *, engine="auto") → bool

LLM に yes/no を問います。

Usage
if await page.ask("認証ダイアログが出ている?"):
    ...
Arguments
  • question str — 質問文
  • engine str (optional, "auto")
Returns
  • bool

page.agent(goal, *, max_steps=5, engine="auto") → dict

vision / LLM エージェントにゴールを委譲します。

Usage
await page.agent("認証画面をクリアして", max_steps=3)
Arguments
  • goal str — 達成目標
  • max_steps int (optional, 5) — 1–30
  • engine str (optional, "auto")auto / qwen / cogagent
Returns
  • dict

page.get_state(key) / set_state(key, value) → dict | None

親 job に紐づく永続データの読み書き(要 parent_job_id)。

Usage
await page.set_state("cursor", {"page": 3})
cur = await page.get_state("cursor")
Arguments
  • key str — キー
  • value anyset_state のみ。保存する値
Returns
  • dict | None

page.solve_cloudflare(*, timeout_s=25.0) → dict

Cloudflare のチャレンジを待つ / 通します。

Usage
await page.solve_cloudflare()
Arguments
  • timeout_s float (optional, 25.0)
Returns
  • dict

page.resize_window(width, height) → dict

Chrome のウィンドウサイズを変更します。

Usage
await page.resize_window(1280, 720)
Arguments
  • width int — 幅(px)
  • height int — 高さ(px)
Returns
  • dict

Page — 拡張機能コマンド(Agent ext)

CDP / nodriver では直接届かない Chrome 機能を、全レーンに常駐する Paprika Agent 拡張機能経由で呼ぶための API 群です(本物の ページズーム、リクエストヘッダ書き換え、コンテンツ設定、プライバシー、 ダウンロード、プロキシ、ナビゲーション監視、ユーザースクリプト、拡張管理)。 下の型付きメソッドはすべて汎用 page.ext() の薄いラッパーです。 fetch 実行中のセッションでも呼べます(ブラウザ設定であってページ書き込みではないため)。

戻り値の見かた ほとんどのメソッドは reply 全体{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"})
PHP は順次対応中です(拡張コマンドは Page サーフェスの一部として今後追加されます)。

page.ext(cmd, args=None, *, timeout=20.0) → dict

拡張機能の任意コマンドを実行する汎用パススルー。下の全ラッパーはこれの薄い別名で、新しい能力も「拡張にハンドラ+ここにラッパー」だけで増やせます。

Usage
reply = await page.ext("setContentSetting", {"type": "images", "setting": "block"})
print(reply["result"])
Arguments
  • cmd str — 拡張側ハンドラ名(例 "netSetHeader"
  • args dict (optional, None) — ハンドラへ渡す引数
  • timeout float (optional, 20.0) — 応答待ちの秒数
Returns
  • dict — reply 全体 {status, result, elapsed_ms}。ペイロードは result

page.zoom(factor) / page.set_zoom(factor) → dict

本物のページズーム。リフローを伴い全画面クロスオリジン iframe プレーヤーにも効きます。CDP の setPageScaleFactor と違い 1.0 未満(縮小)も有効。

Usage
await page.zoom(0.5)   # 50% に縮小
await page.zoom(1.0)   # 等倍に戻す
Arguments
  • factor float — 倍率。1.0 = 100%、範囲 0.25–5.0
Returns
  • dictresult["factor"]result["method"]"chrome.tabs.setZoom" なら本物のズーム成功)

page.set_referer(value, *, url_filter="*") → dict

マッチする URL に Referer リクエストヘッダを強制します。CDN/HLS が iframe の URL を Referer に取って 403 を返すプレーヤーの救済に使います。

Usage
await page.set_referer("https://supjav.com/")
Arguments
  • value str — 設定する Referer の値
  • url_filter str (optional, "*") — 適用先 URL パターン
Returns
  • dictresult["id"] にルール ID

page.set_request_header(header, value, *, url_filter="*", rule_id=2000) → dict

任意のリクエストヘッダを強制します(declarativeNetRequest の modifyHeaders)。同じ rule_id で呼ぶとルールを置き換えます。

Usage
await page.set_request_header("X-Requested-With", "XMLHttpRequest")
Arguments
  • header str — ヘッダ名
  • value str — ヘッダ値
  • url_filter str (optional, "*") — 適用先 URL パターン
  • rule_id int (optional, 2000) — 同 ID で上書き
Returns
  • dictresult["id"]

page.block_hosts(hosts) → dict

指定したドメインへの全リクエストを遮断します(広告・トラッカー除去)。

Usage
await page.block_hosts(["ads.example.net", "track.example.com"])
Arguments
  • hosts list[str] — 遮断するドメインの列
Returns
  • dictresult["added"] に追加ルール件数

page.net_rules() → list[dict]

現在有効な動的ネットワークルール(ブロック・ヘッダ書き換え)の一覧を返します。

Usage
rules = await page.net_rules()
Returns
  • list[dict] — 動的 declarativeNetRequest ルール

page.clear_net_rules() → dict

すべての動的ネットワークルールを削除します。

Usage
await page.clear_net_rules()
Returns
  • dictresult["removed"] に削除件数

page.set_content_setting(type, setting, *, pattern="*://*/*") → dict

サイト別のコンテンツ設定を変更します。

Usage
await page.set_content_setting("images", "block")
Arguments
  • type strpopups / images / javascript / automaticDownloads
  • setting strallow / block / session_only / ask
  • pattern str (optional, "*://*/*") — 適用先パターン
Returns
  • dict

page.allow_popups(*, pattern="*://*/*") → dict

popup を許可します(リダイレクト連鎖で別窓を開くプレーヤー対策)。set_content_setting("popups", "allow") の別名。

Usage
await page.allow_popups()
Arguments
  • pattern str (optional, "*://*/*") — 適用先パターン
Returns
  • dict

page.allow_auto_downloads(*, pattern="*://*/*") → dict

複数の自動ダウンロードを確認ダイアログ無しで許可します。

Usage
await page.allow_auto_downloads()
Arguments
  • pattern str (optional, "*://*/*") — 適用先パターン
Returns
  • dict

page.set_privacy(path, value) → dict

chrome.privacy の ChromeSetting をドット区切りパスで設定します。

Usage
await page.set_privacy("network.webRTCIPHandlingPolicy", "disable_non_proxied_udp")
Arguments
  • path str — 設定パス(例 network.webRTCIPHandlingPolicy
  • value any — 設定値
Returns
  • dict

page.prevent_webrtc_leak() → dict

WebRTC による実 IP 漏洩を防ぎます(プロキシ併用時に重要)。set_privacy のショートカット。

Usage
await page.prevent_webrtc_leak()
Returns
  • dict

page.navigation_events(*, since=0.0) → list[dict]

バッファされた遷移イベント(committed / completed / newtarget / error)を取り出します。newtarget は popup・新規タブの出自(ソースフレーム+URL)を含みます。

Usage
events = await page.navigation_events()
for e in events:
    print(e["type"], e["url"])
Arguments
  • since float (optional, 0.0) — この epoch(ms) 以降のイベントのみ
Returns
  • list[dict] — 各イベント {type, url, tabId, frameId, sourceFrameId, ...}

page.download(url, *, filename=None, conflict="uniquify", headers=None) → dict

制御付きのダウンロードを開始します(chrome.downloads)。保存先・ファイル名・追加ヘッダを指定でき、セッションの Cookie を引き継ぎます。

Usage
dl = await page.download("https://cdn.example.com/v.mp4", filename="evidence.mp4")
Arguments
  • url str — ダウンロード URL
  • filename str (optional, None) — 保存ファイル名
  • conflict str (optional, "uniquify")uniquify / overwrite / prompt
  • headers list (optional, None)[{name, value}] の追加リクエストヘッダ
Returns
  • dictresult["download_id"]

page.download_status(*, download_id=None) → list[dict]

ダウンロードの状態を検索します。

Usage
items = await page.download_status(download_id=dl["result"]["download_id"])
print(items[0]["state"], items[0]["bytesReceived"])
Arguments
  • download_id int (optional, None) — 省略で全件
Returns
  • list[dict]{state, bytesReceived, totalBytes, filename, ...}

page.cancel_download(download_id) → dict

進行中のダウンロードを中止します。

Usage
await page.cancel_download(1)
Arguments
  • download_id int — ダウンロード ID
Returns
  • dict

page.set_proxy(host, port, *, scheme="http", bypass=None) → dict

このレーン(Chrome プロファイル)単位の固定プロキシを設定します。タブ単位ではなくプロファイル全体に効きます。認証付きプロキシは非対応。

Usage
await page.set_proxy("10.0.0.2", 1080, scheme="socks5")
Arguments
  • host str — プロキシホスト
  • port int — プロキシポート
  • scheme str (optional, "http")http / https / socks5
  • bypass list (optional, None) — 直結するドメイン列
Returns
  • dictresult["mode"]

page.clear_proxy() → dict

プロキシ設定を解除します。

Usage
await page.clear_proxy()
Returns
  • dict

page.proxy_info() → dict

現在のプロキシ設定を取得します。

Usage
info = await page.proxy_info()
Returns
  • dictresult["value"] / result["levelOfControl"]

page.register_user_script(id, code, *, matches=None, world="MAIN", run_at="document_idle") → dict

MAIN ワールドへ常駐スクリプトを登録します(プレーヤー API をフックして実ソース URL を露出させる等)。同じ id で更新。

Usage
await page.register_user_script("hook", "window.__paprika = jwplayer;")
Arguments
  • id str — スクリプト ID
  • code str — JavaScript ソース
  • matches list (optional, ["<all_urls>"]) — 適用先 match パターン
  • world str (optional, "MAIN")MAIN / USER_SCRIPT
  • run_at str (optional, "document_idle") — 実行タイミング
Returns
  • dictresult["id"]

page.unregister_user_script(id) → dict

登録済みのユーザースクリプトを解除します。

Usage
await page.unregister_user_script("hook")
Arguments
  • id str — スクリプト ID
Returns
  • dict

page.installed_extensions() → list[dict]

このレーンの Chrome にインストール済みの拡張一覧を返します(uBlock 等が有効か検証する用途)。

Usage
exts = await page.installed_extensions()
Returns
  • list[dict]{id, name, enabled, version}

page.set_extension_enabled(ext_id, enabled) → dict

他の拡張を有効/無効に切り替えます。

Usage
await page.set_extension_enabled("cjpalhdlnbpafiamejdnhcphjbkeiagm", True)
Arguments
  • ext_id str — 対象拡張の ID
  • enabled bool — 有効化するなら True
Returns
  • dict

Page — タブ・ライフサイクル

page.new_page(url) / page.open(url) → Page

新規タブを開きます。

Usage
tab = await page.new_page("https://example.com", switch=True)
Arguments
  • url str — 開く URL
  • switch bool (optional, False) — True で新タブを既定に
Returns
  • Page

page.pages() → list[Page]

セッションの全タブを返します。

Usage
tabs = await page.pages()
Returns
  • list[Page]

page.switch() → dict

このタブを前面(既定)にします。

Usage
await tab.switch()
Returns
  • dict

page.close() → None

タブを閉じます(最後の 1 枚を閉じるとセッション終了)。

Usage
await tab.close()
Returns
  • None

page.keepalive(*, idle_ttl_s=120, absolute_ttl_s=86400) → HandoffInfo

スクリプト終了後もセッションを残し、noVNC で人手に引き継ぎます(別名 detach)。

Usage
info = await page.keepalive(idle_ttl_s=600)
Arguments
  • idle_ttl_s int (optional, 120) — 無操作での生存秒数
  • absolute_ttl_s int (optional, 86400) — 絶対上限
Returns
  • HandoffInfo