phantomjs api文檔

phantomjs實現了一個無界面的webkit瀏覽器。雖然沒有界面，但dom渲染、js運行、網絡訪問、canvas/svg繪制等功能都很完備，在頁面抓取、頁面輸出、自動化測試等方面有廣泛的應用。

詳細文檔

安裝

下載phantomjs（官方下載，下載失敗請訪問另一個下載點）。解壓到任意目錄，並將包含phantomjs.exe的目錄添加到系統路徑。

如果要借助phantomjs進行無頭測試，請參考各個測試框架的說明，或者參考phantomjs的官方文檔：http://phantomjs.org/headless-testing.html。

使用說明

簡單示例

// test.js
var page = require('webpage').create(),
    system = require('system'),
    address;
if (system.args.length === 1) {
    phantom.exit(1);
} else {
    address = system.args[1];
    page.open(address, function (status) {
        console.log(page.content);
        phantom.exit();
    });
}

運行：

phantomjs ./test.js http://baidu.com

這個例子簡單地展示了通過phantom訪問baidu.com，並輸入html內容。使用方式就像使用node運行js代碼一樣。在phantom運行時，它會向當前代碼運行環境注入phantom對象。如上面代碼中，通過phantom對象控制程序終結。示例中其他代碼的含義以及更多深入的用法，將在下文中展開。

window對象

在使用phantom時，我首先關注的是DOM和BOM接口。不過這不是一個問題，看了下面的代碼就能了解：

// test.js
console.log(window === this);
phantom.exit();

運行：

phantomjs ./test.js

結果為 true。也就是說，就像瀏覽器環境一樣，我們的代碼運行在window環境下，可以很方便地進行DOM方面的操作。

注：如果使用web page模塊打開頁面，則請不要在此window對象下進行任何DOM相關的操作，因為這個window並不是page對象內的window。如果想要執行dom相關操作，請參閱page.evaluate()部分。

phantom對象

之前的例子中我們已經初步認識了phantom對象。它的功能是定義和控制phantom運行環境的參數和流程。關鍵的API有：

1. phantom.args String[]
   獲取傳給本JS程序的參數，需要與 system.args進行區分（system模塊詳見下文），后者表示傳給phantomjs引擎的參數。例如 phantomjs ./test.js http://baidu.com這句語句，通過phantom.args，我們能得到的參數列表為 ["http://baidu.com"]，而通過 system.args則得到 ["./test.js", "http://baidu.com"]這樣的參數列表。差異就在於是否包含當前腳本名稱。不過 phantom.scriptName這個API提供了獲取腳本名稱的功能。
2. phantom.cookies Object[]
   獲取或設置cookies，不過對於設置建議使用其他的API完成。同時相關的API還有:

    

   • phantom.addCookie(Object) Boolean：添加cookie值
   • phantom.deleteCookie(cookieName) Boolean：刪除指定Cookie值
   • phantom.clearCookies()：清空所有的cookie
   • phantom.cookiesEnabled Boolean：獲取或設置是否支持cookie
3. phantom.injectJs(fileName) Boolean:
   把指定的外部JS文件注入到當前環境。執行這個方法時，phantomjs首先會從當前目錄檢索此文件，如果找不到，則再到 phantom.libraryPath指定的路徑尋找。 phantom.libraryPath這個API基本上就是為 phantom.injectJs()服務的。
4. phantom.onError
   當頁面存在js錯誤，且沒有被 page.onError處理，則會被此handler捕獲。下面是使用此API的一個例子。由於phantom環境下代碼調試很困難，了解這些錯誤捕獲的API也許會對我們的實際使用有所幫助。

   phantom.onError = function(msg, trace) {
       var msgStack = ['PHANTOM ERROR: ' + msg];
       if (trace && trace.length) {
           msgStack.push('TRACE:');
           trace.forEach(function(t) {
               msgStack.push(' -> ' + (t.file || t.sourceURL) + ': ' + t.line + (t.function ? ' (in function ' + t.function +')' : ''));
           });
       }
       console.error(msgStack.join('\n'));
       phantom.exit(1);
   };

    

5. phantom.exit(returnValue)
   這個API已經見過多次了，它的作用是退出程序，可以設置一個退出代碼，默認是0。

web page 模塊

web page模塊的功能是處理具體的頁面。使用時需要引入模塊，並創建實例：

var webPage = require('webpage');
var page = webPage.create();

 

本文中不經說明， page指代 require("webpage").create()的實例。

1. page.cookies Object[]
   與上文中的 phantom.cookies類似，表示本url下的cookie的讀取。同樣類似的API還有addCookie()、 deleteCookie()、 clearCookies()。
2. 頁面內容相關的API
   • page.content String：獲取或設置當前頁面的html。
   • page.plainText String：這是一個只讀屬性，獲取頁面去除html標記的文本（考慮$.text()）。
   • page.url String：只讀，獲取當前頁面的url。
   • page.setContent()：允許修改 page.content和 page.url內容，會觸發reload。
3. page.settings Object
   對於當前頁面的一些配置項。此API必須在 page.open()調用之前設置，否則不會起作用。以下是配置項：
   * javascriptEnabled 默認 true：是否執行頁面內的javascript

    

   • loadImages 默認 true：是否載入圖片
   • userAgent ：傳遞給服務器的userAgent字符串
   • userName ：用於http訪問授權的用戶名
   • password ：用於http訪問授權的密碼
   • XSSAuditingEnabled 默認 false：是否監控跨域請求
   • resourceTimeout 單位 ms：定義資源請求的超時時間。如果設置了此項，則頁面中如果有任何資源超過此時限未請求成功，則頁面其他部分也會停止請求，並觸發onResourceTimeout()事件處理。
4. page.customHeaders Object
   phantom允許在請求時在http請求頭部添加額外信息，此設置項對這個page里面所有的請求都生效（包含頁面和其他資源的請求）。添加的信息並沒有限制，但如果設置 User-Agent的值，那么這個值會覆蓋掉 page.settings里的設置值。示例：

   page.customHeaders = {
       "X-Test": "foo",
       "DNT": "1"
   };

   page.libraryPath String
5. 與 phantom.libraryPath類似，page對象也支持設置js文件路徑，同時可以通過相應的page.injectJs()方法注入javascript文件。除了 page.injectJs()方法外，還有page.includeJs()也可以加入javascript文件。它們的區別在於， page.injectJs()不強求此文件能訪問得到，即使是一個不可訪問的資源也可以。
6. page.navigationLocked Boolean 默認 fasle
   設置是否允許離開當前頁面，默認是允許。
7. page.open()
   此方法用於打開一個網頁，是一個很重要的API，它有三種調用形式： 
   • open(url, callback)
   • open(url, method, callback)
   • open(url, method, data, callback)

   聯想一下 $.ajax()，可以更好理解這個API。對於這些參數，需要單獨闡述的是 callback。callback()會在頁面載入完成后調用，由 page.onLoadFinished調用（時機晚於page.onLoadFinished）。這個 callback會接受一個參數 status，可能值為"success"和 "fail"，指示頁面是否加載成功。示例可以參考“簡單示例”一節的例子。

8. page.close()
   與 page.open()對應，調用 page.close()之后，會釋放page所占用的內存，我們不可以在此之后再調用page實例。在實際的操作中，調用此方法並不會完成清空所占內存；javascript的垃圾回收機制也不會回收page實例。但在實際使用中，常常會遇到將一個page實例反復open的情況。在一個頁面用完后，記得一定要執行 page.close()，這樣在下一次open的時候，才不會重復分配堆棧空間。
9. page.evaluate(fn, [param])
   對於page打開的頁面，往往需要與其進行一些交互。 page.evaluate()提供了在page打開頁面的上下文（下文直接用page上下文指代）執行function的功能（類比Chrome開發者工具的控制台）。如下例：

   page.open('http://m.bing.com', function(status) {
       var title = page.evaluate(function(s) {
           return document.querySelector(s).innerText;
       }, 'title');
       console.log(title);
       phantom.exit();
   });

   在這個例子中， page.evaluate()接受兩個參數，第一個是必需的，表示需要在page上下文運行的函數 fn；第二個是可選的，表示需要傳給 fn的參數 param。 fn允許有一個返回值return，並且此返回值最終作為 page.evaluate()的返回值。這邊對於剛剛命名的 param和return有一些額外的說明和注意事項。對於整個phantom進程而言， page.evaluate()是跑在一個沙盒中， fn無法訪問一切phantom域中的變量；同樣 page.evaluate()方法外部也不應該嘗試訪問page上下文中的內容。那么如果兩個作用域需要交換一些數據，只能依靠 param和 return。不過限制很大， param和 return必須為能夠轉化為JSON字符串，換言之，只能是基本數據類型或者簡單對象，像DOM 節點、$對象、function、閉包等就無能為力了。

   這個方法是同步的，如果執行的內容對后續操作不具備前置性，可以嘗試異步方法以提高性能：page.evaluateAsync()。

10. page.render(filename)
    page.render()能夠把當前頁面渲染成圖片並輸出到指定文件中。輸出的文件格式由傳入的文件擴展名決定，目前支持 PNG、 JPEG、 GIF、 PDF。

    var page = require('webpage').create();
    page.open('http://github.com/', function() {
        page.render('github.png');
        phantom.exit();
    });

    還有其他一些API會對 page.render()產生影響，如：
    • page.zoomFactor Number： 設置縮放比率
    • page.clipRect Object：設置輸出的矩形區域，例如：

      page.clipRect = {
          top: 14,
          left: 3,
          width: 400,
          height: 300
      };

      還有一些頁面設置參數，如果紙張大小，側邊距等，在此不詳述。web page也支持輸出圖片base64格式的字符串，API為 page.renderBase64()，也不再詳述。
11. page.sendEvent()
    為了交互的需要（測試的需要），phantom允許通過代碼模擬一些交互事件（注意與DOM事件的區分）。 
    • 鼠標事件：
      API： sendEvent(mouseEventType[, mouseX, mouseY, button='left'])
      mouseEventtype可能的取值為： 'mouseup'、 'mousedown'、 'mousemove'、'doubleclick'和 'click'，這個參數為必須的。
      后兩個參數為鼠標事件的坐標位置。最后一個參數為鼠標按鍵，只對需要按鍵的事件有效，默認為 'left'，可能值為 'right'、 'left'、 'middle'。
    • 鍵盤事件：
      API： sendEvent(keyboardEventType, keyOrKeys, [null, null, modifier])
      keyboardEventType可能的取值為 'keyup'、 'keydown'、 'keypress'，第2個參數傳入一個鍵值或一個字符串。鍵值可以通過 page.event.key來查詢調用。第三和第四個參數無效，第五個參數表示同時按下的修飾鍵。取值情況如下： 
      • 0: 未使用修飾鍵
      • 0x02000000: Shift鍵被按下
      • 0x04000000: Ctrl鍵被按下
      • 0x08000000: Alt鍵被按下

    看一個示例：

    page.sendEvent('keypress', page.event.key.A, null, null, 0x02000000 | 0x08000000);

     

12. page.switchToFrame(frameName/framePosition)
    默認page對應的是frame，如果一個頁面中還有其他frame，則可以通過此方法切換page對應的frame。其他類似的方法還有 switchToChildFrame()、 switchToParentFrame()、switchToFocusedFrame()、 switchToMainFrame()等，不再贅述。
13. page.uploadFile(selector, file)
    頁面中常常會有上傳文件的操作，但phantom沒有界面，因而也就沒有辦法選擇文件上傳，通過此方法可以模擬文件上傳操作。示例如下：

    page.uploadFile('input[name=image]','/path/to/some/photo.jpg');

14. 一些事件處理接口
    • page.onAlert：phantom沒有界面，所以也就不能處理alert窗口，但可以通過此接口捕獲到alert。
    • page.onPrompt：類似的，phantom不能處理prompt窗口，通過這個接口可以捕獲prompt。
    • page.onConfirm：類似的，phantom不能處理confirm窗口，通過這個接口可以捕獲confirm。
    • page.onConsoleMessage：類似的，phantom不能顯示console窗口，通過這個接口可以捕獲console消息。

      varwebPage=require('webpage');
      varpage=webPage.create();
      page.onAlert=function(msg){
          console.log('ALERT: '+msg);
      };
      page.onPrompt=function(msg,defaultVal){
          if(msg==="What's your name?"){
              return'PhantomJS';
          }
          // 返回值就是prompt得到的值
          returndefaultVal;
      };
      page.onConfirm=function(msg){
          console.log('CONFIRM: '+msg);
          // 返回true相當於點擊“確定”，返回false相當於點擊“取消”
          returntrue;
      };
      page.onConsoleMessage=function(msg,lineNum,sourceId){
          console.log('CONSOLE: '+msg+' (from line #'+lineNum+' in "'+sourceId+'")');
      };

    • page.onInitialized：在page創建后觸發。
    • page.onUrlChanged：在url發生變化時觸發。它接受新的url作為參數。首次加載頁面，page.onUrlChanged是在 page.onInitialized之后觸發。
    • page.onNavigationRequested：如果在 page.navigationLocked中允許頁面跳轉，此接口才會有意義（參見 page.navigationLocked）。它接受4個參數，先看示例：

      page.onNavigationRequested=function(url,type,willNavigate,main){
            console.log('Trying to navigate to: '+url);
            console.log('Caused by: '+type);
            console.log('Will actually navigate: '+willNavigate);
            console.log('Sent from the page\'s main frame: '+main);
      }

      • url表示要跳轉到的url
      • type表示產生跳轉的原因，可能值有 'Undefined'、 'LinkClicked'、'FormSubmitted'、 'BackOrForward'、 'Reload'、 'FormResubmitted'、'Other'
      • willNavigate表示是否會跳轉，由 page.navigationLocked控制
      • main表示發生跳轉的是否是主frame，如果是主frame則為true，如果為其他frame則為false
    • page.onLoadStarted：在開始載入資源時觸發。
    • page.onLoadFinished：頁面所有資源載入完成后觸發。其實與 page.open()的回調函數等價。它接受一個參數 status，表示加載是否成功。參見 page.open()。
    • page.onClosing：當在phantom域調用 page.close()或page上下文調用window.close()時觸發。
    • page.onError： 此接口捕獲所有page上下文發生的javascript錯誤。參數是錯誤信息和調用堆棧，參見 phantom.onError。如果page不處理錯誤，那么這些錯誤會冒泡到phantom的onError處理器。
    • page.onCreate：當page創建子窗口時觸發，例如在page上下文中使用window.open，但是子窗口再創建子窗口不會觸發此事件。
    • page.onResourceRequested：當頁面請求一個資源時觸發的事件，它接受兩個參數，第一個參數是 requestData對象，它有如下屬性：
      • id : 資源請求編號
      • method : http請求方法，get/post等
      • url：請求的URL
      • time : 一個Date object，包含響應接收的時間
      • headers : http頭部的信息列表

      第二個參數是 networkRequest實例，它包含3個方法：

      • abort()：中斷當前的請求。這樣做會觸發onResourceError
      • changeUrl(url)：改變當前請求的目標url
      • setHeader(key, value)：修改/添加http頭部信息
    • page.onResourceReceived：當一個資源請求的響應接收到后觸發此事件，它接受一個response對象，這個對象有如下屬性：
      • id : 資源請求編號
      • url：請求的URL
      • time : 一個Date object，包含響應接收的時間
      • headers : http頭部的信息列表
      • bodySize : 已接收到的數據大小（全部數據或已接收的部分數據）
      • contentType : 指定的內容類型
      • redirectURL : 如果是一個重定向響應，那么此處是重定向到的url
      • stage : “start”/ “end”
      • status : http狀態碼，如：200
      • statusText : http狀態描述，如：OK
    • page.onResourceError：當資源加載失敗時，觸發此事件。它接收一個resourceError對象，這個對象有如下屬性：
      • id：資源請求的編號
      • url：請求的URL
      • errorCode：錯誤代碼
      • errorString：錯誤信息

    可參考如下示例：

    page.onResourceError=function(resourceError){
        console.log('Unable to load resource (#'+resourceError.id+'URL:'+resourceError.url+')');
        console.log('Error code: '+resourceError.errorCode+'. Description: '+resourceError.errorString);
    };

    • page.onResourceTimeout：在講 page.settings時曾經提到過這個事件。如果設置了page.settings.resourceTimeout，並且資源在這個時間內沒有載入完成，則會觸發此事件，它接受一個 request對象，這個對象包含如下屬性：
      • id : 資源請求編號
      • method : http請求方法，get/post等
      • url：請求的URL
      • time : 一個Date object，包含響應接收的時間
      • headers : http頭部的信息列表
      • errorCode：錯誤代碼
      • errorString：錯誤信息

Child Process模塊

通過Child Process模塊，我們能創建子進程，借助 stdin、 stdout、 stderr來實現進程間通信（很C++）。使用子進程能夠做很多事情，如打印、發郵件、調用腳本或其他程序（不局限於javascript）。

要使用Child Process模塊，我們需要在代碼中添加 require("child_process")。

以下內容缺乏文檔支持，並未經過充分測試，可能存在一定的理解偏差。這部分功能是極有用的，希望在項目中使用的時候注意測試。

Child Process模塊本身應該也並完全開發完全。 spawn()、 execFile()可用， exec()和fork()尚未實現。

1. spawn(command, [args], [options])
   最基本的創建進程的方法。前兩個參數比較重要，例如現在想從phantom進程中運行一段nodejs腳本，腳本路徑為 “main.js”，這個腳本接受一個參數，假定為 “helloworld”，那么如果想得到這段腳本的運行結果應該怎么做呢？參考下面的腳本：

   var spawn = require("child_process").spawn;
   child = spawn('node', ['main.js', 'helloworld']);
   child.stdout.on("data", function (data) {
       console.log("spawnSTDOUT:", JSON.stringify(data))
   });
   child.stderr.on("data", function (data) {
       console.log("spawnSTDERR:", JSON.stringify(data))
   });
   child.on("exit", function (code) {
       console.log("spawnEXIT:", code)
   });
   setTimeout(function () {
       phantom.exit(0)
   }, 2000);

   
   其實 spawn()方法沒什么神秘的，它就是運行第一個參數表示的命令，第二個參數就是這個命令的參數列表。所以如果要開啟一個新的phantom進程，第一個參數為 phantom就行。同樣的道理，指定好程序的路徑或者是腳本語言解釋器的路徑，通過這個方法可以做的事情很多。
   比較不方便的是，進程間的通信只能通過 stdin、 stdout、 stderr來完成，調用spawn()方法后，還需要對這些交互信息進行監聽，上面的例子中演示了監聽 stdout和stderr的方法。
2. execFile(cmd, args, opts, cb)
   就像剛剛說的， spawn()方法稍微感覺有點麻煩，使用 execFile()能夠稍稍簡化上面的代碼。 execFile()的前三個參數與 spawn()的三個參數完全一樣，不同的是它多了一個 cb回調函數，看一個例子就知道這個回調函數有什么用了：

   var execFile = require("child_process").execFile;
   child = execFile('node', ['main.js', 'helloworld'], null,
       function (err, stdout, stderr) {
           console.log("execFileSTDOUT:", JSON.stringify(stdout))
           console.log("execFileSTDERR:", JSON.stringify(stderr))
       });
   setTimeout(function () {
       phantom.exit(0)
   }, 2000);

   
   在 execFile()中，對 stdout、 stderr的監聽做了封裝，簡化了我們的代碼，不過功能上與 spawn()並無區別。

file system模塊

雖然與node.js中文件系統模塊名稱和調用方法（ require("fs")）一樣，但不得不說，phantom的文件系統模塊總體是比較簡單的，API不多但夠用，API也不同於node.js的異步回調風格，而是采用stream+同步的風格，濃濃的C++風味。在使用的時間請一定要注意與node.js的文件系統模塊做區分。

1. fs.open(path, mode/opts) File
   open()方法接受兩個參數，第一個參數是要打開的文件路徑，第二個參數后面還會見到，這里統一說明。如果是字符串，則代表文件打開的模式，可選的有 'r'、 'w'、 'a/+'、'b'（read時僅支持 'b'）；如果是一個對象，則表示配置項，一共有兩個配置項，分別是mode和 charset， mode就是剛剛提到的打開模式， charset表示文件的編碼類型。參閱下面的示例：

   var fs = require("fs");
   var file = fs.open("main.js", 'r');
   console.log(file.read());
   file.close();
   file = fs.open("main.js", 'a');
   file.write("123");
   file.close();
   setTimeout(function () {
       phantom.exit(0)
   }, 2000);

   
   對打開的文件，我們可以進行讀寫操作（具體使用與打開模式有關）。如果對一個文件執行了open，請別忘了在文件使用完成后，再對其執行close。
2. fs.read(path, mode/opts) String
   fs.read()方法對文件讀取做了封裝，不必關心文件的打開關閉，返回值為文件內容。
3. fs.write(path, content, mode/opts)
   fs.write()方法對文件寫入做了封裝，不必關心文件的打開關閉。
4. 其他API:
   • fs.size(path) Number：獲取文件大小
   • fs.copy(source, destination)：復制文件
   • fs.copyTree(source, destination)：復制目錄樹
   • fs.move(source, destination)：移動文件
   • fs.moveTree(source, destination)：移動目錄樹
   • fs.remove(file)：刪除文件
   • fs.removeTree(path)：刪除目錄
   • fs.join(partialPath[]) String：組合路徑
   • fs.split(path) String[]：切割路徑
   • fs.exist(path) Boolean：文件或目錄是否存在
   • fs.isFile(path) Boolean：指定路徑是否是文件
   • fs.isDirectory(path) Boolean：指定路徑是否是目錄
   • fs.list(path) String[]：獲取指定目錄下的文件/目錄名稱列表

System模塊

在文檔一開始就已經提到過system模塊，一開始的例子中，我們使用了system模塊提供的 args屬性。現在重新來認識一下system模塊。system模塊主要管理着一些與運行環境有關的屬性。

1. system.args String[]
   獲取運行phantomjs時傳入的所有參數，這個不再贅述。
2. system.env Object
   獲取當前的環境信息。包含操作系統信息、環境變量信息等等。通過下面的代碼來查看一下吧：

   var system = require('system');
   var env = system.env;
   Object.keys(env).forEach(function (key) {
       console.log(key + '=' + env[key]);
   });
   setTimeout(function () {
       phantom.exit(0)
   }, 2000);

3. system.os Object
   獲取操作系統信息，返回一個簡單對象，這個對象有3個屬性： architecture：架構，如“32bit”； name：操作系統名稱； version：操作系統版本。
4. system.pid Number
   獲取當前進程的pid。
5. system.platform String
   永遠返回 'phantomjs'

Web Server模塊

phantomjs支持一個簡單的web server模塊， require('webserver')即可引入。web server模塊基於mongoose。不過最好不要在生產環境使用這樣的服務器模塊，因為現階段此模塊僅允許10個並發請求。

看一個簡單的例子吧：

var webserver = require('webserver');
var server = webserver.create();
var service = server.listen(8080, function(request, response) {
    response.statusCode = 200;
    response.write('<html><body>Hello!</body></html>')
    response.close();
});

首先需要創建服務器實例，然后調用 listen()方法監聽， listen()方法的第一個參數可以為一個端口號，也可以中 ip:port這樣的ip+port組合方式。第二個參數是處理請求的回調方法。下面描述一下 request和 response兩個對象。

• request：
  • method：http請求的方法，get、post等
  • url: 包含http請求URL和get請求的query string（如果有的話）
  • httpVersion：當前采用的http協議的版本
  • headers：所有http請求頭部信息，以鍵值對的形式提供
  • post：請求主體，僅對post和put方法的請求有效
  • postRaw：如果Content-type為 'application/x-www-form-urlencoded'（表單上傳的默認值）時，post的原始信息會暫存在此屬性中。
• response：
  • headers：以鍵值對的形式保存所有的HTTP請求頭部的信息，在第一次調用 write()方法前一定要設置
  • setHeader(name, value)：設置或添加特定的頭部信息
  • header(name)：獲取特定的頭部信息
  • statusCode：設置HTTP狀態碼
  • setEncoding(encoding): 標明傳給 write()的數據需要轉換成什么格式，默認為UTF-8。如果數據為二進制字符串，則設置為“binary”
  • write(data)：向response中發送數據塊，可以多次調用
  • writeHead(statusCode, headers)：向response中發送響應頭部。 statusCode是一個3位數字，表示HTTP狀態碼（如404）。后一個參數代碼響應頭部
  • close()：關閉HTTP連接
    • 為了避免客戶端檢測到連接中斷，記得最后再用 write()方法發送一個空字符串（如： response.write("")）。
  • closeGracefully()：功能與 close()一樣，不過更安全可靠，它能保證響應頭部先發送，並自動在響應最后加上 response.write("")

 

參考：https://www.cnblogs.com/Sonet-life/p/5393730.html