在閱讀前，在此說明下，本人英文一直不好，所以該文檔是借助翻譯工具翻譯的，閱讀起來可能有點不好，請各位諒解，哪位大神有標准的中文文檔請分享下
Github下載地址：https://github.com/kikinteractive/app
App.js幫助文檔
目錄：
一、Pages
1、Controllers 控制器
2、Page Arguments 參數
3、Templating 模板
4、Events 事件
5、Navigation stack 導航
6、Back stack 返回按鍵
7、Pick a page 渲染頁面
8、Transitions 切換模式
9、Restore stack 恢復會話
10、Stack manipulation 移除會話
二、UI Components
1、Topbar 頭部工具欄
2、Content 內容組件
3、Buttons 按鈕
4、Lists & scrolling 列表
5、Infinite scroll 列表冬天加載
6、Inputs 輸入框
7、Sections 塊組件
8、Dialogs 彈窗
9、PhotoViewer 圖片瀏覽
下面是App.js webpages的標准格式：
<!DOCTYPE html> <html> <head> <title>My App</title> <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, minimal-ui"> <link rel="stylesheet" href="//cdn.kik.com/app/3.0.0/app.min.css"> <style> /* put your styles here */ </style> </head> <body> <!-- （5）put your home pages start 編寫頁面--> <div class=”app-page” data-page=”home”> </div> <!-- put your pages end --> <script src="//zeptojs.com/zepto.min.js"></script> <script src="//cdn.kik.com/app/3.0.0/app.min.js"></script> <script> /* （6）put your javascript here */ </script> </body> </html>
1、app.min.js是包含所有庫功能的核心模塊。
2、app.min.css是帶有App.js的默認樣式表。它包含了所有包含小部件的ios/android樣式。
3、zepto.min.js是一個類似於jQuery-like的庫，專注於輕量級和移動友好型。它不是對app.js的依賴，但仍然很好地編寫簡潔的、
跨平台的代碼。如果你願意的話，用jQuery替換它。
4、meta viewport標記只是確保在它運行的任何設備上正確地大小窗口。這對於在不同的平台上獲得一致的規模和規模是很重要的。
5、pages的注釋是HTML頁面元素的位置，如UI部分所描述的那樣。
6、javascript的注釋是控制器和導航代碼的位置。
7、styles是頁面的樣式。
由於App.js應用程序本質上是靜態的，你所要做的就是把你的代碼放到一個HTML文件中，（也就是說在手機上瀏覽的不同頁面其實是一個
html頁面的不同div對應的page頁），然后在瀏覽器中打開它進行測試。
一、Pages
App.js是為單個靜態頁的應用提供服務的。這意味着它可以在網頁的會話中保持所有頁面導航，將“Page”定義為可以實例化的DOM節點。
page是具有某些通用組件的HTML元素，如topbar和內容區。注意，雖然這些組件是完全可選的，但是“app-page”格式是HTML的唯一要求。
如下代碼：
<div class="app-page" data-page="home"> <div class="app-topbar"></div> <div class="app-content"></div> </div>
“app-page”必須有一個“data-page”屬性，該屬性表示頁面的名稱。每當任何JavaScript代碼試圖加載該頁面時，都會使用這個名稱。
如下加載頁面：
App.load('home');
這一行JavaScript指示app.js加載名為“home”的頁面。在引擎蓋下，app.js用這個名字克隆HTML“app-page”元素，並使其對用戶可見。
通過這種方式，我們可以創建同一頁面的多個實例，並在不同的上下文中使用它。
1、Controllers
每當使用“app.load”加載一個新頁面時，都會調用一個特殊的函數來准備HTML頁面app-page元素。這允許您在向用戶
顯示頁面之前將頁面的任何動態方面連接起來。例如，按鈕可以被綁定來執行他們需要做的任何動作。
/* in your javascript */ App.controller('home', function (page) { // this runs whenever a 'home' page is loaded // 'page' is the HTML app-page element $(page) .find('.app-button') .on('click', function () { console.log('button was clicked!'); }); });
控制器也可以是一個JavaScript，這樣你就可以擁有從彼此繼承的控制器。如下
function HomeController(page) { // this runs whenever a 'home' page is loaded this.foo = 'bar'; this.print(); } HomeController.prototype.print = function () { console.log(this.foo); }; App.controller('home', HomeController);
如果您已經在HTML中描述了多個頁面，那么您將希望為每個頁面創建一個控制器，以便在加載時能夠正確地構造它們。
2、Page Arguments
控制器可以有動態參數，這樣您就可以根據輸入構造一個稍微不同的頁面。例如，如果我正在創建一個聯系人列表應用程序，
我將想要為我列表中的任何給定聯系人加載一個聯系人頁面。我們要做的是描述一個帶有空白字段的通用聯系人頁面，並根據頁面
的加載方式來填充它們。
要加載帶有特殊參數的頁面，只需在“app.load”調用中添加一個JSON對象，您就可以相應地在populator中使用該對象。
如下:
<!-- in your html --> <div class="app-page" data-page="contact"> <div class="app-topbar"> <div class="app-title">Contact</div> </div> <div class="app-content"> <div class="first-name"></div> <div class="last-name"></div> </div> </div> /* in your javascript */ App.controller('contact', function (page, contact) { $(page).find('.first-name').text(contact.firstName); $(page).find('.last-name' ).text(contact.lastName ); }); /* somewhere else in javascript */ var contact = { firstName : 'Bruce' , lastName : 'Lee' }; App.load('contact', contact);
在上面的第二行代碼中，“聯系人”對象可以有任何一個姓氏和名稱，控制器將相應地設置頁面。
這些類型的參數與Zepto或jQuery結合在一起，可以有效地讓您對HTML進行模板。
3、Templating
模板HTML元素是一種非常常見的范例，雖然app.js在模板上沒有任何專門的特性，但它絕對不會妨礙它。一般來說，
你可以使用任何你想要的框架/庫，如果你想在沒有任何框架的情況下使用它，那么就會有一些模式讓它變得簡單：
<!-- in your html --> <div class="app-page" data-page="contact"> <div class="app-topbar"> <div class="app-title">Contact</div> </div> <div class="app-content"> <div class="contacts"> <div class="contact"> <div class="first-name"></div> <div class="last-name"></div> </div> </div> </div> </div> /* in your javascript */ App.controller('contact', function (page, contacts) { var $template = $(page).find('.contact').remove(); var $contacts = $(page).find('.contacts'); contacts.forEach(function (contact) { var $contact = $template.clone(true); $contact.find('.first-name').text(contact.firstName); $contact.find('.last-name' ).text(contact.lastName ); $contacts.append($contact); }); });
4、Events
1、 appLayout：可能是最重要的事件，這是由方向改變、窗口大小調整、DOM中的頁面放置或任何可能使頁面布局無效的事件引起的。
綁定到這個事件，並在這里放置任何與布局相關的代碼。
2、 appShow：每當用戶導航到這個頁面時就會被觸發。如果用戶導航到另一個頁面並最終返回，那么這個過程可能會多次觸發。
3、 appHide：當用戶從這個頁面導航時，就會被觸發。請注意，這並不一定意味着頁面將被銷毀，例如，當用戶導航到另一個頁面並可能返回時。
4、 appBack：當用戶從這個頁面中向后導航時，就會被觸發。
5、 appBack：當用戶從這個頁面中向后導航時，就會被觸發。
6、 appBeforeBack：當用戶即將在堆棧中導航時，就會被觸發。這個導航可以通過在事件處理程序中返回false來取消（類似於窗口。onbeforeunload作品)。
7、 appReady：這實際上被稱為第一次在頁面上調用appShow。它在確保窗口方面有額外的好處。onload被調用，這使得它對於網絡綁定的初始化代碼非常有用。
8、 appDestroy：當頁面的實例即將被完全銷毀時觸發。這通常發生在用戶完成從頁面向后導航時。
要處理這些事件，需要在控制器中綁定它們。
App.controller('home', function (page) {
$(page).on('appShow', function () {
console.log('the user can see it!');
});
});
或者，所有事件都可以被綁定為控制器類的方法。
function HomeController(page) { // stuff } HomeController.prototype.onShow = function () { console.log('the user can see it'); }; App.controller('home', HomeController);
在銷毀時，重要的是取消綁定到頁面范圍之外的事件，以允許JavaScript垃圾收集器完成其工作。
App.controller('home', function (page) {
function doStuff() {
// handle event
}
window.addEventListener('keypress', doStuff);
$(page).on('appDestroy', function () {
window.removeEventListener('keypress', doStuff);
});
});
5、Navigation stack
正如前面所討論的，app.load對所選頁面進行克隆，為其創建一個控制器，然后將其呈現給用戶。
App.load('home');
這可以在任何時候在代碼的任何地方調用。如果在一個正在進行的過程中嘗試導航，那么導航將在當前完成之后排隊執行。
此外，當導航完成時，可以提供一個回調來運行。
如下：
App.load('home', function () {
// done!
});
因為按鈕通常直接加載頁面，所以有一個特性允許這是一種快速、簡潔的方式。
<!-- in your html -->
<div class="app-button" data-target="page2">Go to page 2</div>
<div class="app-button" data-target="contact" data-target-args='{"firstName":"Bruce","lastName":"Lee"}'>Open contact</div>
當第一個按鈕被單擊時，load（'page2'）將自動被調用。第二個按鈕是類似的，但也提供了要傳遞的
頁面參數(app.load('contact'，firstName：'Bruce'，lastName：'Lee') )
6、Back stack
當你從一個頁面切換到另一個頁面時，app.js將會有一段你曾經擁有的頁面的歷史，能夠導航到它們。
返回是應用程序的概念上的反轉，加載在導航欄中返回到前一個頁面加載（當導航完成時破壞當前頁面）。
// load home // load page2 App.back(function () { // back to home // page2's appDestroy event has been called });
如果沒有前頁導航回應用，返回將返回false。
與數據目標特性一樣，app.back有一個概念上的反向特性。
<!-- in your html -->
<div class="app-button" data-back>Go back</div>
當點擊上面的按鈕時，App.back() 將自動被調用。
回到一個特定的頁面，而不是簡單地返回一個頁面是很常見的。
// load home // load page2 // load page3 App.back('home', function () { // back to home // page2's and page3's appDestroy events have been called });
后退按鈕的另一個常見的做法是根據前一頁命名它。App.js提供了一種方便，可以自動地將后退按鈕命名為它將指向的頁面。
<div class="app-button" data-back="true" data-autotitle></div>
7、Pick a page
頁面的一個常見用例是為用戶提供一種方法，讓用戶可以選擇在呼叫頁面上使用的內容或數據。這可以通過以下方式完成：
App.controller('selector', function (page, request) {
// 'request' is data from the requestor
// respond to the caller
// will implicitely call App.back and destroy the page
this.reply({ some: 'data' });
});
App.pick('selector', { some: 'data' }, function (data) {
// 'data' is the reply data
// do something with it
});
8、Transitions
App.js在默認情況下會嘗試在頁面之間轉換，使用最適合你的應用程序運行的平台。例如，在iOS上，
你的頁面標題會隨着淡出而逐漸消失，模擬原生的iOS轉換風格。
有許多在轉換中構建的，每個對“app.load”的調用都可以指定直接使用哪個轉換（覆蓋默認值）。
App.load('home', 'fade'); // fade between pages
轉換是由Swapper.js提供的。到文檔中查看可用的轉換列表。
此外，您還可以為所有導航設置全局缺省躍遷。
App.setDefaultTransition('transition-name'); // global
// set per platform
App.setDefaultTransition({
ios : 'transition-name' , // iOS
iosFallback : 'transition-name' , // iOS <5
android : 'transition-name' , // Android
androidFallback : 'transition-name' , // Android < 4
fallback : 'transition-name' // non-iOS, non-Android
});
默認的轉換也可以設置為每一頁。
App.controller('page2', function (page) {
this.transition = 'fade';
});
9、Restore stack
因為app.js知道您的導航堆棧以及如何構造頁面，所以它還提供了自動恢復用戶會話的能力，
使其恢復到上次關閉時的位置。啟用這個特性需要以下的習語：
// in your apps main method try { // try to restore previous session App.restore(); } catch (err) { // else start from scratch App.load('home'); }
下面是一個例子，說明如果最后一個會話在最后5分鍾內，如何只恢復堆棧。
try { App.restore({ maxAge: 5*60*1000 }); } catch (err) { App.load('home'); }
注意：maxAge是以毫秒為間隔的。
單獨的頁面可以防止自己被恢復（例如，如果它們是模態的）。
App.controller('page2', function (page) {
this.restorable = false;
});
page2和堆棧前面的任何頁面都不會恢復（但是以前的頁面將會）。
10、Stack manipulation
雖然通常是一種糟糕的實踐，但通常需要在沒有用戶交互的情況下操縱導航堆棧。
注意，在不調用App.back或app.load的情況下，刪除當前可見的頁面是不可能的。
// stack = [home, page2, page3] App.removeFromStack(0,1); // remove home from stack // stack = [page2, page3] App.addToStack(1, ['home', 'page4']); // add two pages at index 1 // stack = [page2, home, page4, page3]
二、UI Components
App.js頁面通常有一個topbar和內容區域。topbar包含標題和按鈕（用於導航和其他操作），而內容則具有頁面的實際內容。
<div class="app-page"> <div class="app-topbar"></div> <div class="app-content"></div> </div>
App.js附帶了一些內置的UI組件，並且已經設計好了。幾乎所有這些都將在你的應用程序中結束。
注意，擁有特定於平台的樣式通常很方便。例如，在這個頁面頂部的演示中，topbar在iOS和Android上的風格略有不同。
為了適應這個應用，app.js在文檔的主體上添加類，表示它正在運行哪個平台。使用這個類作為過濾選擇器可以讓您為單個小部件有單獨的樣式。
.my-widget { /* cross-platform styles */ } .app-ios .my-widget { /* ios only styles */ } .app-android .my-widget { /* android only styles */ }
1、Topbar
與許多原生移動應用一樣，App.js topbar通常由幾個按鈕和一個標題組成。
<div class="app-topbar"> <div class="app-title">Page title</div> </div> 或者： <div class="app-topbar"> <div class="app-button left" data-back>Back</div> <div class="app-title">Page title</div> <div class="app-button right">Forward</div> </div>
點擊按鈕部分，了解如何在你的topbar中添加按鈕。
2、Content
應用程序內容包含頁面的所有內容，包括按鈕、列表和輸入。雖然這些小部件是有用的，但通常情況下，
應用程序的自定義HTML結構會在這里。
默認情況下，它會自動為它進行滾動管理。要關閉自動滾動，可以將屬性數據無滾動條添加到內容元素中。
<div class="app-content"></div>
3、Buttons
按鈕是任何應用程序和應用程序的基本組件。App.js有幾個內置的方便操作。任何帶有類app-button的元素都將自動進行相應的樣式化，
並在按下適當的下狀態時對觸摸做出響應。
<div class="app-button">My button</div>
最常見的按鈕位置之一是topbar。
<div class="app-topbar"> <div class="app-button left" data-back>Back</div> <div class="app-title">Page title</div> <div class="app-button right">Forward</div> </div>
你可以想象，“后退”按鈕會出現在左邊和右邊的“轉發”按鈕上。您會注意到，樣式與內容區域中的按鈕有很大的不同，
因為在這個上下文中，我們希望一個更小的按鈕適合於導航，等等。
4、Lists & scrolling
列表對於顯示批量數據或提供一組可供選擇的選項非常有用。
<!-- in your app-content --> <ul class="app-list"> <li>Item 1</li> <li>Item 2</li> <li>Item 3</li> </ul>
另外，列表項可以是按鈕。
<ul class="app-list"> <li class="app-button">Button item</li> </ul>
列表通常有將項目划分為邏輯部分的標簽。
<ul class="app-list"> <label>Animals</label> <li>Dogs</li> <li>Cats</li> <label>Fruits</label> <li>Apples</li> <li>Oranges</li> </ul>
5、Infinite scroll
列表經常在用戶滾動時創建動態加載內容的需求。App.js可以幫你處理這個問題。
App.infiniteScroll(listElement, function (next) { // dynamically fetch data var list = []; // add html elements to list next(list); });
請注意，listElement是將元素動態插入到的HTML元素。
在等待動態內容加載時，有一個加載元素是一個常見的用例。
App.infiniteScroll(listElement, { loading: loadingElem }, function (next) {
next([ stuff ]);
});
請注意，loadingElem將被克隆並在列表的底部使用，而內容正在被獲取。
6、Inputs
App.js提供標准組件來收集用戶輸入，無論是HTML輸入還是文本區域，都可以很容易地構造表單。
<!-- in your app-content --> <input class="app-input"> <input type="search" class="app-input"> <!-- will have search icon --> <textarea class="app-input"></textarea>
7、Sections
“section”是app.js UI中的一個概念，它允許您將組件塊分割成方便的塊。
在你的應用程序的內容中試試這個：
<!-- in your app-content --> <div class="app-section"> <input class="app-input" placeholder="Subject"> <textarea class="app-input" placeholder="Message"></textarea> <div class="app-button">Send</div> </div>
你會注意到，上面描述的相同的輸入現在都在一個圓形的部分中。此外，該部分還有一個邊界，以及適當的邊界。
這些特性可以應用於頁面內容區域中所描述的任何小部件。
<ul class="app-list app-section"> <li>Item 1</li> <li>Item 2</li> <li>Item 3</li> </ul> <div class="app-section"> <div class="app-button">Send</div> </div> <div class="app-section"> <input class="app-input"> </div>
注意，您可以在一個小節中放置盡可能多的小部件，並且它們將被相應地處理。
8、Dialogs
App.js對話框執行與傳統模態對話框和動作表單相似的任務。它們是可以將文本（或HTML元素）呈現給用戶的modals，
可以選擇關閉的按鈕。
App.dialog({ title : 'Network Error', text : 'Looks like the connection is flaky. Try again in a bit' okButton : 'Try Again', cancelButton : 'Cancel' }, function (tryAgain) { if (tryAgain) { // try again } });
這里dialog只展示了文本，有時我們希望dialog展示的是表單或者是其他組件元素，這是就需要用的rawHTML屬性，
這個屬性值是一個元素對象，而不是字符串
//獲取login的元素 var loginForm = $(page).find(‘.login’)[0]; App.dialog({ title : 'Network Error', rawHTML : loginForm， okButton : 'Try Again', cancelButton : 'Cancel' }, function (tryAgain) { if (tryAgain) { // try again } });
9、PhotoViewer
PhotoViewer.js 是為App.js提供的可定制的照片庫，這對於設置來說是微不足道的。它是一種帶有滑動手勢、縮放和放大功能的原生感覺。
<!-- in your html --> <script src="http://cdn.kik.com/photo-viewer/1/photo-viewer.js"></script> <div class="app-page dark-page" data-page="viewer"> <div class="app-topbar"> <div class="left app-button" data-back data-autotitle></div> <div class="app-title">Viewer</div> </div> <div class="app-content"></div> </div> // in your js App.controller('viewer', function (page, data) { var photoViewer = new PhotoViewer(page, data.urls); }); // to use the viewer App.load('viewer', { urls: [ 'http://i.imgur.com/yDK68Ff.jpg', 'http://i.imgur.com/rKIESYd.jpg', 'http://i.imgur.com/OTaodxO.jpg' ] });
請閱讀PhotoViewer文檔，了解更多選項和定制。
Github下載地址：https://github.com/kikinteractive/app