[譯文]casperjs的API-clientutils模塊

casper提供了少許的客戶端接口用來進行遠程DOM環境注入，經過clientutils模塊的ClientUtils類實例中的__utils__對象來執行:

casper.evaluate(function() {
  __utils__.echo("Hello World!");
});

提示：

這個工具不須要使用jQuery, Mootools等第三方庫，可是不影響你經過Casper.options.clientScripts來使用這些第三方庫

Bookmarklet（標籤頁）

一個標籤頁也可以幫助你在你熟悉的瀏覽器中使用casper的客戶端接口。

只須要拖拽下面的標籤到工具欄，而後點擊它，一個__utils__對象已經在控制檯裏了

CasperJS Utils

javascript:(function(){void(function(){if(!document.getElementById('CasperUtils')){var%20CasperUtils=document.createElement('script');CasperUtils.id='CasperUtils';CasperUtils.src='https://raw.github.com/n1k0/casperjs/master/modules/clientutils.js';document.documentElement.appendChild(CasperUtils);var%20interval=setInterval(function(){if(typeof%20ClientUtils==='function'){window.__utils__=new%20window.ClientUtils();clearInterval(interval);}},50);}}());})();

注：這裏的用法不是很明白，CasperJS Utils連接實際的內容是一個javascript執行語句，做用是生成一個帶有__uitls__對象的頁面，使用戶能夠在瀏覽器控制檯調試__utils__的功能，個人理解是如此，若是以爲疑惑的能夠去看官方網站說明

提示：

CasperJS和PhantomJS基於webkit，你在使用標籤頁時最好使用最新的基於webkit的瀏覽器（如chrome,safari等）

ClientUtils 原型

echo()

Signature: echo(String message)

新增於1。0版本.

從遠程DOM環境打印一個消息到casper控制檯

Print a message out to the casper console from the remote page DOM environment:

casper.start('http://foo.ner/').thenEvaluate(function() {
    __utils__.echo('plop'); // this will be printed to your shell at runtime
});

encode()

Signature: encode(String contents)

Encodes a string using the base64 algorithm. For the records, CasperJS doesn’t use builtin window.btoa() function because it can’t deal efficiently with strings encoded using >8b characters:

使用base64編碼編碼一個字符串，爲何這麼作？CasperJS不能使用內置的window.btoa()方法，由於它不能有效的處理使用了 >8b的字符串 

var base64;
casper.start('http://foo.bar/', function() {
    base64 = this.evaluate(function() {
        return __utils__.encode("I've been a bit cryptic recently");
    });
});

casper.run(function() {
    this.echo(base64).exit();
});

exists()

Signature: exists(String selector)

Checks if a DOM element matching a given selector expression exists:

檢查給定的選擇器表達式是否能匹配到一個DOM元素：

var exists;
casper.start('http://foo.bar/', function() {
    exists = this.evaluate(function() {
        return __utils__.exists('#some_id');
    });
});

casper.run(function() {
    this.echo(exists).exit();
});

findAll()

Signature: findAll(String selector)

Retrieves all DOM elements matching a given selector expression:

得到根據給定的選擇器表達式匹配的全部元素：

var links;
casper.start('http://foo.bar/', function() {
    links = this.evaluate(function() {
        var elements = __utils__.findAll('a.menu');
        return Array.prototype.forEach.call(elements, function(e) {
            return e.getAttribute('href');
        });
    });
});

casper.run(function() {
    this.echo(JSON.stringify(links)).exit();
});

findOne()

Signature: findOne(String selector)

Retrieves a single DOM element by a selector expression:

得到根據給定的選擇器表達式匹配的單個元素：

var href;
casper.start('http://foo.bar/', function() {
    href = this.evaluate(function() {
        return __utils__.findOne('#my_id').getAttribute('href');
    });
});

casper.run(function() {
    this.echo(href).exit();
});

getBase64()

Signature: getBase64(String url[, String method, Object data])

This method will retrieved a base64 encoded version of any resource behind a url. For example, let’s imagine we want to retrieve the base64 representation of some website’s logo:

這個方法用來得到一個URL連接後面的資源，而且將該資源轉碼爲base64格式，例如，讓咱們想象咱們想獲得一些網站的logo base64表示：

var logo = null;
casper.start('http://foo.bar/', function() {
    logo = this.evaluate(function() {
        var imgUrl = document.querySelector('img.logo').getAttribute('src');
        return __utils__.getBase64(imgUrl);
    });
});

casper.run(function() {
    this.echo(logo).exit();
});

getBinary()

Signature: getBinary(String url[, String method, Object data])

This method will retrieved the raw contents of a given binary resource; unfortunately though, PhantomJS cannot process these data directly so you’ll have to process them within the remote DOM environment. If you intend to download the resource, use getBase64() or Casper.base64encode() instead:

這個方法用來獲取一個二進制文件的原始內容，由於PhantomJS不能直接處理這些數據，因此你智能在遠程DOM環境中進行處理，若是你計劃下載這些資源，使用getBase64() 或者 Casper.base64encode() 來替代：

casper.start('http://foo.bar/', function() {
    this.evaluate(function() {
        var imgUrl = document.querySelector('img.logo').getAttribute('src');
        console.log(__utils__.getBinary(imgUrl));
    });
});

casper.run();

getDocumentHeight()

Signature: getDocumentHeight()

新增於1.0版本.

獲取當前的文檔高度:

var documentHeight;

casper.start('http://google.com/', function() {
    documentHeight = this.evaluate(function() {
        return __utils__.getDocumentHeight();
    });
    this.echo('Document height is ' + documentHeight + 'px');
});

casper.run();

etElementBounds()

Signature: getElementBounds(String selector)

Retrieves boundaries for a DOM elements matching the provided selector.

獲取給定選擇器匹配的一個元素的邊界值

It returns an Object with four keys: top, left, width and height, or null if the selector doesn’t exist.

若是匹配到元素，返回一個擁有top,left,width,height的對象，若是沒有匹配到元素，返回null

getElementsBounds()

Signature: getElementsBounds(String selector)

Retrieves boundaries for all DOM element matching the provided selector.

獲取給定選擇器匹配的全部元素的邊界值

It returns an array of objects each having four keys: top, left, width and height.

若是匹配到元素，返回一個列表，列表中的對象都擁有top,left,width,height屬性

getElementByXPath()

Signature: getElementByXPath(String expression [, HTMLElement scope])

獲取一個給定xpath選擇器匹配的元素

新增於1.0版本

The scope argument allow to set the context for executing the XPath query:

scope參數容許你設置執行xpath查詢的上下文。

// will be performed against the whole document
__utils__.getElementByXPath('.//a');

// will be performed against a given DOM element
__utils__.getElementByXPath('.//a', __utils__.findOne('div.main'));

getElementsByXPath()

Signature: getElementsByXPath(String expression [, HTMLElement scope])

Retrieves all DOM elements matching a given XPath expression, if any.

獲取給定xpath選擇器匹配的全部元素，若是它有的話

新增於1.0版本

scope參數容許你設置執行xpath查詢的上下文。

 

getFieldValue()

Signature: getFieldValue(String inputName[, Object options])

新增於1.0版本

Retrieves the value from the field named against the inputNamed argument:

獲取值，從表單的元素中獲取對應的值

<form>
    <input type="text" name="plop" value="42">
</form>

對」plop」使用getFieldValue()方法:

__utils__.getFieldValue('plop'); // 42

選項：

• formSelector:容許爲表單包含的元素設置選擇器

getFormValues()

Signature: getFormValues(String selector)

新增於1.0版本

獲取表單中全部元素的值：

<form id="login" action="/login">
    <input type="text" name="username" value="foo">
    <input type="text" name="password" value="bar">
    <input type="submit">
</form>

獲取表單中的值：

__utils__.getFormValues('form#login'); // {username: 'foo', password: 'bar'}

log()

Signature: log(String message[, String level])

Logs a message with an optional level. Will format the message a way CasperJS will be able to log phantomjs side. Default level is debug:

記錄一個選定級別的消息，這個消息將格式化爲phantomjs 的消息，默認級別爲debug

 

mouseEvent()

Signature: mouseEvent(String type, String selector)

給選定的dom元素上發起一個鼠標事件

支持的事件有mouseup, mousedown, click, mousemove, mouseover 和 mouseout.

 

removeElementsByXPath()

Signature: removeElementsByXPath(String expression)

Removes all DOM elements matching a given XPath expression.

移除給定的xpath選擇器匹配的全部dom元素

 

sendAJAX()

Signature: sendAJAX(String url[, String method, Object data, Boolean async, Object settings])

新增於1.0版本

發送一個AJAX請求，使用以下參數：

• url: 請求的URL
• method:HTTP方法(默認: GET).
• data:請求參數 (默認: null).
• async:是否同步請求的標誌 (默認: false)
• settings: 執行AJAX請求的其餘設置(默認: null)

注意：

不要忘記設置--web-security=no 選項在命令行執行時，若是你須要跨域的話：

var data, wsurl = 'http://api.site.com/search.json';

casper.start('http://my.site.com/', function() {
    data = this.evaluate(function(wsurl) {
        return JSON.parse(__utils__.sendAJAX(wsurl, 'GET', null, false));
    }, {wsurl: wsurl});
});

casper.then(function() {
    require('utils').dump(data);
});

visible()

Signature: visible(String selector)

將選定的元素設置爲不可用：

var logoIsVisible = casper.evaluate(function() {
    return __utils__.visible('h1');
});