App.js实现使用js开发app的应用，此文是中文文档

时间 2019-11-17

标签 app.js app 实现使用开发应用此文中文文档栏目 JavaScript 繁體版

原文原文链接

在阅读前，在此说明下，本人英文一直很差，因此该文档是借助翻译工具翻译的，阅读起来可能有点很差，请各位谅解，哪位大神有标准的中文文档请分享下javascript

Github下载地址：https://github.com/kikinteractive/appcss

App.js帮助文档

目录：html

　　1、Pagesjava

　　　　一、Controllers 控制器android

二、Page Arguments 参数ios

三、Templating 模板git

四、Events 事件github

五、Navigation stack 导航web

六、Back stack 返回按键浏览器

七、Pick a page 渲染页面

八、Transitions 切换模式

九、Restore stack 恢复会话

十、Stack manipulation 移除会话

　　2、UI Components

　　　　一、Topbar 头部工具栏

二、Content 内容组件

三、Buttons 按钮

四、Lists & scrolling 列表

五、Infinite scroll 列表冬天加载

六、Inputs 输入框

七、Sections 块组件

八、Dialogs 弹窗

九、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>

一、app.min.js是包含全部库功能的核心模块。

二、app.min.css是带有App.js的默认样式表。它包含了全部包含小部件的ios/android样式。

三、zepto.min.js是一个相似于jQuery-like的库，专一于轻量级和移动友好型。它不是对app.js的依赖，但仍然很好地编写简洁的、

跨平台的代码。若是你愿意的话，用jQuery替换它。

四、meta viewport标记只是确保在它运行的任何设备上正确地大小窗口。这对于在不一样的平台上得到一致的规模和规模是很重要的。

五、pages的注释是HTML页面元素的位置，如UI部分所描述的那样。

六、javascript的注释是控制器和导航代码的位置。

七、styles是页面的样式。

因为App.js应用程序本质上是静态的，你所要作的就是把你的代码放到一个HTML文件中，（也就是说在手机上浏览的不一样页面实际上是一个

html页面的不一样div对应的page页），而后在浏览器中打开它进行测试。

1、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]

2、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 */
}

　　一、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中添加按钮。

　　二、Content

　　　　应用程序内容包含页面的全部内容，包括按钮、列表和输入。虽然这些小部件是有用的，但一般状况下，

　　应用程序的自定义HTML结构会在这里。

　　　　默认状况下，它会自动为它进行滚动管理。要关闭自动滚动，能够将属性数据无滚动条添加到内容元素中。

<div class="app-content"></div>

　　三、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>

　　　　你能够想象，“后退”按钮会出如今左边和右边的“转发”按钮上。您会注意到，样式与内容区域中的按钮有很大的不一样，

　　由于在这个上下文中，咱们但愿一个更小的按钮适合于导航，等等。

　　四、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>

　　五、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将被克隆并在列表的底部使用，而内容正在被获取。

　　六、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>

　　七、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>

　　　　注意，您能够在一个小节中放置尽量多的小部件，而且它们将被相应地处理。

　　八、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
  }
});

　　九、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