App.js实现使用js开发app的应用,此文是中文文档 - 折翼的飞鸟

时间:2024-03-18 08:07:21

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

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

 

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”元素,并使其对用户可见。

通过这种方式,我们可以创建同一页面的多个实例,并在不同的上下文中使用它。

 

  1Controllers

    每当使用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中描述了多个页面,那么您将希望为每个页面创建一个控制器,以便在加载时能够正确地构造它们。

 

  2Page 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);

    在上面的第二行代码中,“联系人”对象可以有任何一个姓氏和名称,控制器将相应地设置页面。

    这些类型的参数与ZeptojQuery结合在一起,可以有效地让您对HTML进行模板。

 

  3Templating

    模板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);
  });
});

   

  4Events

    1appLayout:可能是最重要的事件,这是由方向改变、窗口大小调整、DOM中的页面放置或任何可能使页面布局无效的事件引起的。

      绑定到这个事件,并在这里放置任何与布局相关的代码。

    2appShow:每当用户导航到这个页面时就会被触发。如果用户导航到另一个页面并最终返回,那么这个过程可能会多次触发。

    3appHide:当用户从这个页面导航时,就会被触发。请注意,这并不一定意味着页面将被销毁,例如,当用户导航到另一个页面并可能返回时。

    4appBack:当用户从这个页面中向后导航时,就会被触发。

    5appBack:当用户从这个页面中向后导航时,就会被触发。

    6appBeforeBack:当用户即将在堆栈中导航时,就会被触发。这个导航可以通过在事件处理程序中返回false来取消(类似于窗口。onbeforeunload作品)

    7appReady:这实际上被称为第一次在页面上调用appShow它在确保窗口方面有额外的好处。onload被调用,这使得它对于网络绑定的初始化代码非常有用。

    8appDestroy:当页面的实例即将被完全销毁时触发。这通常发生在用户完成从页面向后导航时。

 

    要处理这些事件,需要在控制器中绑定它们。

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

    

  5Navigation 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\') )

 

  6Back 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>

 

  7Pick 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
});

    

  8Transitions

    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\';
});

    

  9Restore 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和堆栈前面的任何页面都不会恢复(但是以前的页面将会)。

 

  10Stack manipulation

    虽然通常是一种糟糕的实践,但通常需要在没有用户交互的情况下操纵导航堆栈。

    注意,在不调用App.backapp.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组件,并且已经设计好了。几乎所有这些都将在你的应用程序中结束。

  注意,拥有特定于平台的样式通常很方便。例如,在这个页面顶部的演示中,topbariOSAndroid上的风格略有不同。

 为了适应这个应用,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