核心 API 參考

本章節匯總了在候鳥環境中使用 Playwright 時最頻繁調用的接口與方法。

---

1. 基礎鏈路管理 (HTTP 接口)

這些接口由 ApiServer.exe 提供，用於控制環境的生命週期。

啟動環境

• 方法: POST
• URL: /api/v1/browser/start
• 參數: {"Session_ID": "環境ID"}
• 關鍵返回: data.ws (用於 Playwright 的 WS 連接地址)

停止環境

• 方法: POST
• URL: /api/v1/browser/stop
• 參數: {"Session_ID": "環境ID"}
• 作用: 關閉瀏覽器窗口並同步雲端數據。

---

2. Playwright 接管方法

chromium.connectOverCDP

這是唯一的推薦連接方式，用於接管候鳥已啟動的環境。

const browser = await chromium.connectOverCDP(ws_endpoint);

---

3. 定位器 (Locators)

Playwright 推薦使用 Locator 代替 $ 符號，因為它具備自動等待與重試機制。

方法	範例	說明
getByRole	page.getByRole('button', { name: '登錄' })	根據語義角色定位（最推薦）
getByText	page.getByText('歡迎回來')	根據文本內容定位
getByPlaceholder	page.getByPlaceholder('請輸入帳號')	根據輸入框提示定位
locator (CSS/XPath)	page.locator('#submit-btn')	使用傳統 CSS 選取器

---

4. 網絡攔截與修改 (Network)

這是 Playwright 的殺手級功能，在候鳥環境中非常有用，可以用來過濾廣告或修改 API 返回數據。

// 攔截所有圖片請求以提升加載速度
await page.route('**/*.{png,jpg,jpeg}', route => route.abort());

// 修改 API 返回結果 (Mock數據)
await page.route('**/api/user/info', async route => {
  const json = { name: '候鳥高級用戶', level: 99 };
  await route.fulfill({ json });
});

---

5. 常用動作命令

• page.goto(url): 跳轉頁面，建議配合 waitUntil: 'domcontentloaded'。
• page.click(selector): 模擬真實點擊，會自動滾動元素到可視區域。
• page.fill(selector, text): 快速填充輸入框。
• page.type(selector, text, { delay: 100 }): 模擬真人敲擊鍵盤，帶有延遲。

---

IMPORTANT

記住： 在候鳥環境中，始終操作 browser.contexts()[0] 下的頁面，不要手動創建新的上下文，以免丟失指紋配置。

---

TIP

掌握了基礎 API？現在去 實戰示例 看看如何解決複雜的網頁交互。