API

了解如何去用 YouYu 对象

项目开发

运行环境

browser

获取浏览器的相关信息，包括种类及版本号。

YouYu.browser Object

以 {BROWSER_TYPE: true, version: "BROWSER_VERSION", language: "BROWSER_LANGUAGE"} 的形式返回。其中 BROWSER_TYPE 的可能值有：

msie
chrome
firefox
safari
opera

当值为 chrome 或 safari 时，会多出一个 {webkit: true} 属性；当值为 firefox 时，会多出一个 {mozilla: true} 属性。

// IE 浏览器
YouYu.browser;
=> {msie: true, version: "11.0", language: "zh-CN"}

// Chrome 浏览器
YouYu.browser;
=> {chrome: true, version: "34.0.1847.131", webkit: true, language: "ja"}

platform

获取平台的相关信息，包括种类、版本号及是否可触摸。

YouYu.platform Object

以 {PLATFORM_TYPE: true, version: "PLATFORM_VERSION", touchable: true} 的形式返回。其中 PLATFORM_TYPE 的可能值有：

windows
macintosh
iphone
ipod
ipad
...

当值为 iphone、ipod 或 ipad 时，会多出一个 {ios: true} 属性。

// Windows 7
YouYu.platform;
=> {touchable: false, version: "7", windows: true}

// iPhone 5s
YouYu.platform;
=> {touchable: true, version: "7.1.2", iphone: true, ios: true}

plugins

获取插件的支持情况。目前支持的插件检测有以下几种：

YouYu.plugins Object

YouYu.plugins.pdf;
=> true

流程控制

inPage

YouYu.inPage(page) Boolean

page: [String / Array]

判断当前代码的执行环境是否在指定的页面中。

// 假设 <body data-page="users-index"></body>

YouYu.inPage("users-index");
=> true

YouYu.inPage("users-show");
=> false

YouYu.inPage(["users-index", "users-show"]);
=> true

YouYu.inPage(page, handler) Anything

page: [String / Array]
handler: [Function]

设置在指定页面中执行的函数。

YouYu.inPage("users-index", function() {
  // 在 users-index 页面中做点什么
});

YouYu.inPage(["users-index", "users-show"], function() {
  // 在 users-index 和 users-show 页面中做点什么
});

prepare

添加需要在 DOMContentLoaded 之前调用的处理函数

YouYu.prepare(handler)

handler: [Function]
不传入任何参数

主要进行事件委派等与 DOM 加载进程无关的操作。会在调用 YouYu.sandbox 时执行。

YouYu.prepare(function() {
  // Do sth.
});

ready

添加需要在 DOMContentLoaded 之后调用的处理函数

YouYu.ready(handler)

handler: [Function]
不传入任何参数

会在调用 YouYu.sandbox 时执行。

YouYu.ready(function() {
  // Do sth.
});

sandbox

启动封闭运行环境

YouYu.sandbox([settings]) Object / Boolean

settings: [Object]
系统配置参数

通过 YouYu.prepare 和 YouYu.ready 加入到队列中的函数只有在调用该方法时才执行。每个页面只能调用一次。返回（修改后的）系统配置参数。

// 未传参数时返回默认配置
YouYu.sandbox();
=> Object {debug: true, platform: "", locale: "zh-CN", lang: "zh", api: ""}

// 返回修改后的配置
YouYu.sandbox({api: "v1", platform: "YouYu", version: "0.1.0"});
=> Object {debug: true, platform: "YouYu", locale: "zh-CN", lang: "zh", api: "v1", version: "0.1.0"}

// 第二次调用
YouYu.sandbox({invoke_time: 2});
=> false

封闭环境内函数

functionExists

检测指定函数是否已经定义过。

YouYu.functionExists(funcName[, isWindow]) Boolean

funcName: [String]
isWindow: [Boolean]

默认从 YouYu 内部的函数列表中查找 funcName，若 isWindow 设置为 true，则从 window 对象上找。

YouYu.queue("foo", function() {});
YouYu.functionExists("foo");
=> true

function bar() {}
YouYu.functionExists("bar", true);
=> true

queue

将外部处理函数引入到沙盒中。

YouYu.queue(funcName, handler) Function

funcName: [String]
函数名称
handler: [Function]
处理函数

引入单个函数。

YouYu.queue("foobar", function() {
  console.log("Foobar!");
});
=> function() { console.log("Foobar!"); }

YouYu.run("foobar");
=> Foobar!

YouYu.queue(funcList)

funcList: [Object]
函数列表

引入函数列表。

YouYu.queue({
  foo: function() {
    console.log("Foo!");
  },
  bar: function() {
    console.log("Bar!");
  }
});
=> {foo: function() { console.log("Foo!"); }, bar: function() { console.log("Bar!"); }}

YouYu.run("foo");
=> Foo!

YouYu.run("bar");
=> Bar!

YouYu.queue(funcName) Function

funcName: [String]
要获取的函数的名称

获取指定的已保存的函数。

YouYu.queue("foobar", function() {
  console.log("Foobar!");
});

YouYu.queue("foobar");
=> function() { console.log("Foobar!"); }

YouYu.queue() Object

获取已保存的所有函数。

YouYu.queue({
  foo: function() {
    console.log("Foo!");
  },
  bar: function() {
    console.log("Bar!");
  }
});

YouYu.queue();
=> {foo: function() { console.log("Foo!"); }, bar: function() { console.log("Bar!"); }}

dequeue

将指定处理函数从沙盒中删除

YouYu.dequeue(funcName) Boolean

funcName: [String]
要删除的函数的名称

YouYu.queue("foo", function() {
  return "foo";
});

YouYu.functionExists("foo");
=> true

YouYu.dequeue("foo");
=> true

YouYu.functionExists("foo");
=> false

YouYu.dequeue(funcNameList) Boolean

funcNameList: [Array]
要删除的函数的名称列表

YouYu.queue({
  foo: function() {
    return "foo";
  },
  bar: function() {
    return "bar";
  }
});

YouYu.functionExists("foo");
=> true

YouYu.functionExists("bar");
=> true

YouYu.dequeue(["foo", "bar"]);
=> true

YouYu.functionExists("foo");
=> false

YouYu.functionExists("bar");
=> false

run

执行指定函数。

YouYu.run(funcName) Anything

funcName: [String]
函数名

YouYu.queue("foobar", function() {
  return "Foobar!";
});

YouYu.run("foobar");
=> "Foobar!"

YouYu.run(funcNameList)

funcNameList: [Array]
函数名列表

YouYu.queue({
  foo: function() {
    console.log("Foo!");
  },
  bar: function() {
    console.log("Bar!");
  }
});

YouYu.run(["foo", "bar"]);
=> Foo!
=> Bar!

初始化与配置

config

获取系统信息。

YouYu.config([key]) Anything

key: [String]
系统配置参数的 key。若省略则返回所有信息。

YouYu.sandbox({
  platform: "Ourairyu"
  version: "0.1.0",
  api: "v1"
});

// 获取指定信息
YouYu.config("platform");
=> "Ourairyu"

// 获取所有信息
YouYu.config();
=> {debug: true, platform: "Ourairyu", locale: "zh-CN", lang: "zh", api: "v1", version: "0.1.0"}

init

设置初始化信息。

初始化函数是 YouYu 内部定义好的。目前已经有以下几种：

systemDialog
ajaxHandler
runSandbox
apiNS

YouYu.init(function, key) Anything

function: [Function]
key: [String]

设置单个初始化函数。

YouYu.init(function() {
  // To do sth.
}, "systemDialog");

YouYu.init(settings) Anything

settings: [Object]

设置多个初始化函数。

YouYu.init({
  ajaxHandler: function() {
    // To do sth.
  },
  runSandbox: function() {
    // To do sth.
  }
});

api

设置及获取 Web API。

YouYu.api(settings)

settings: [Object]

设置 Web API。

YouYu.api({
  users: "/v1/users",
  user: "/v1/users/:id"
});

YouYu.api(key[, params]) String

key: [String]
params: [Object]

获取 Web API。

YouYu.api("users");
=> "/v1/users"

YouYu.api("user", {id: 1024});
=> "/v1/users/1024"

route

设置及获取页面 URL。

YouYu.route(settings)

settings: [Object]

设置路由。

YouYu.route({
  users: "/schools/demo/users/",
  user: "/schools/demo/users/:slug/"
});

YouYu.route(key[, params]) String

key: [String]
params: [Object]

获取路由。

YouYu.route("users");
=> "/schools/demo/users/"

YouYu.route("user", {slug: "ourai"});
=> "/schools/demo/users/ourai/"

asset

设置及获取资源 URL。

YouYu.asset(settings)

settings: [Object]

设置资源。

YouYu.asset({
  loading: "loading.gif",
  logo: "logo.png"
});

YouYu.asset(key[, params]) String

key: [String]
params: [Object]

获取资源。

YouYu.asset("loading");
=> "loading.gif"

YouYu.asset("logo");
=> "logo.png"

tmpl

设置及获取 HTML 模版。要与 JST 配合使用。

YouYu.tmpl(settings)

settings: [Object]

设置模版。

YouYu.tmpl({
  empty: "empty",
  loading: "loading",
  user_item: "user_list_item",
  activity: {
    item: "components/activities/item",
    comment: "components/activities/comment",
    form: "components/activities/form"
  }
});

YouYu.tmpl(key[, params]) Function

key: [String]
params: [Object]

获取模版。

// 获取并执行模板函数
YouYu.tmpl("activity.item")({id: 12345, content: "有渔大法好！"});

系统对话框

alert

弹出警告提示框。

如果引入了 jQuery UI Dialog，则为自定义的警告对话框。

YouYu.alert(message[, callback]) Boolean

message: [String]
callback: [Function]
点击「确定」按钮的响应

YouYu.alert("Alert Dialog", function() {
  console.log("Clicked 'DETERMINE' button!");
});

confirm

弹出确认提示框。

如果引入了 jQuery UI Dialog，则为自定义的带有两个按钮的确认提示框。

YouYu.confirm(message[, okCallback][, cancelCallback]) Boolean

message: [String]
okCallback: [Function]
点击「确定」按钮的响应
cancelCallback: [Function]
点击「取消」按钮的响应

YouYu.confirm("Confirm Dialog with Two Buttons", function() {
  console.log("Clicked 'DETERMINE' button of confirm dialog!");
}, function() {
  console.log("Clicked 'CANCEL' button of confirm dialog!");
});

confirmEX

弹出确认提示框。

如果引入了 jQuery UI Dialog，则为自定义的带有三个按钮的确认提示框。

YouYu.confirmEX(message[, yesCallback][, noCallback]) Anything

message: [String]
yesCallback: [Function]
点击「是」按钮的响应
noCallback: [Function]
点击「否」按钮的响应

YouYu.confirmEX("Confirm Dialog with Three Buttons", function() {
  console.log("Clicked 'YES' button of ex-confirm dialog!");
}, function() {
  console.log("Clicked 'NO' button of ex-confirm dialog!");
});

destroySystemDialogs

销毁系统对话框。

只有在引入 jQuery UI Dialog 时才会有效。

YouYu.destroySystemDialogs() Boolean

YouYu.alert("Alert");
YouYu.confirm("Confirm");
YouYu.confirmEX("Confirm EX");

YouYu.destroySystemDialogs();
=> true

其他

data

获取 DOM 的「data-*」属性集或存储数据到内部/从内部获取数据。

YouYu.data(node) Object

node: [DOM]
元素节点

获取元素节点的「data-*」属性集。

// <span id="test" data-node="true" data-enabled="yes">An element node</span>
YouYu.data(document.getElementById("test"));
=> {node: "true", enabled: "yes"}

YouYu.data(key, data[, lock]) Anything

key

[String]

命名空间格式的字符串

data

[Anything]

lock

[Boolean]

值为 true 时，在第一次设置之后无法再读写到内部。

保存数据到 YouYu 内部。

YouYu.data("foo.bar", 121);

YouYu.data("foo");
=> {bar: 121}

YouYu.data("foobar.doo", [1, 2, 3], true);

YouYu.data("foobar");
=> null

YouYu.data(key) Anything

key: [String]

获取保存到 YouYu 内部的数据。

示例请看 YouYu.data(key, data[, lock]) 的。

ajax

发起 AJAX (Asynchronous JavaScript and XML) 请求。

YouYu.ajax(url[, succeed][, fail]) Object

url: [String]
请求 URL
succeed: [Function]
成功时的操作
fail: [Function]
失败时的操作

YouYu.ajax("/api/v1/users", function( data, textStatus, jqXHR ) {
  // To do sth. when XHR request succeeded
}, function( data, textStatus, jqXHR ) {
  // To do sth. when XHR request failed
});

YouYu.ajax(options[, succeed][, fail]) Object

options: [Object]
与jQuery.ajax() 几乎同样的参数
succeed: [Function]
成功时的操作
fail: [Function]
失败时的操作

YouYu.ajax({
  url: "/api/v1/users",
  type: "post"
}, function( data, textStatus, jqXHR ) {
  // To do sth. when XHR request succeeded
}, function( data, textStatus, jqXHR ) {
  // To do sth. when XHR request failed
});

sjax

发起 SJAX (Synchronous JavaScript and XML) 请求。

用法与 YouYu.ajax() 基本一致。

YouYu.sjax(url[, succeed][, fail]) Object

url: [String]
请求 URL
succeed: [Function]
成功时的操作
fail: [Function]
失败时的操作

YouYu.sjax(options[, succeed][, fail]) Object

options: [Object]
与jQuery.ajax() 几乎同样的参数
succeed: [Function]
成功时的操作
fail: [Function]
失败时的操作

save

利用 localStorage 将数据保存到本地。

YouYu.save(key, data)

key: [String]
data: [Anything]

YouYu.save("foo", {bar: "bar"});
YouYu.access("foo");
=> {bar: "bar"}

YouYu.save("foo", {foo: "foo"});
YouYu.access("foo");
=> {bar: "bar", foo: "foo"}

YouYu.save("foo", {foo: "foobar"});
YouYu.access("foo");
=> {bar: "bar", foo: "foobar"}

YouYu.save("bar", true);
YouYu.access("bar");
=> true

YouYu.save("bar", "true");
YouYu.access("bar");
=> "true"

YouYu.save("bar", undefined);
YouYu.access("bar");
=> undefined

YouYu.save("bar", "undefined");
YouYu.access("bar");
=> "undefined"

YouYu.save("doo");
YouYu.access("doo");
=> undefined

access

访问利用 localStorage 保存到本地的数据。

YouYu.access(key) Anything

key: [String]

YouYu.save("foo", null);
YouYu.access("foo");
=> null

YouYu.save("foo", "null");
YouYu.access("foo");
=> "null"

YouYu.access("bar");
=> undefined

YouYu.access(1);
=> undefined

有渔前端团队

API