API

了解如何去用 YouYu 对象

核心

名称设置

mask

更改 YouYu 依附在全局对象上的名字。

YouYu.mask(guise) Boolean

guise: [String]

原来的名字会被删除，即访问 YouYu 会报错。

YouYu.mask("YouYu_new");
=> true

YouYu_new;
=> Object {mixin: function, each: function, type: function, slice: function, hasProp: function…}

YouYu;
=> ReferenceError: YouYu is not defined

alias

为 YouYu 起个别名。

YouYu.alias(name) Object

name: [String]

用别名也可以访问 YouYu 对象。

只能设置一个别名，若在已设置别名的情况下再次调用该方法，则上次设置的别名会被销毁。

YouYu.alias("TTM");
=> Object {mixin: function, each: function, type: function, slice: function, hasProp: function…}

TTM === YouYu;
=> true

YouYu.alias("FFF");
=> Object {mixin: function, each: function, type: function, slice: function, hasProp: function…}

FFF === YouYu;
=> true

TTM;
=> ReferenceError: TTM is not defined

扩展能力

mixin

扩展指定对象

YouYu.mixin(target[, object1][, objectN]) Object

target: [Object]
object1: [Object]
objectN: [Object]

可以传入任意多个类型为 Object 的参数，如果具有相同的 key，则后者覆盖前者，否则附加到前者上。当只传入一个参数时，则扩展 YouYu 本身。返回值为被扩展的对象，即 target。

// 扩展 YouYu 自身
YouYu.mixin({foo: true, bar: false});

YouYu.foo;
=> true

YouYu.bar;
=> false

// 返回新对象
YouYu.mixin({}, {foo: true, bar: false});
=> {foo: true, bar: false}

YouYu.mixin();
=> {}

YouYu.mixin(deep, target, object1[, objectN]) Object

deep: [Boolean]
如果是 true 的话则进行深度复制。
target: [Object]
object1: [Object]
objectN: [Object]

var obj1 = {
    foo: {
      foo: "foo"
    }
  };

var obj2 = {
    foo: {
      bar: "bar"
    }
  };

// 普通扩展
YouYu.mixin({}, obj1, obj2);
=> {foo: {bar: "bar"}}

// 深度复制
YouYu.mixin(true, {}, obj1, obj2);
=> {foo: {foo: "foo", bar: "bar"}}

extend

使用特定格式的数据扩充指定对象。内置「预处理」功能。

YouYu.extend(data[, target]) Object

data: [Array / Plain object]
具备特定格式的数据
target: [Object]
被扩充的对象。忽略此参数则扩充到 YouYu 上。

返回值为包含通过 data 构造的方法的对象。

data 的基本结构为：

{
  validator: function() {},
  value: "",
  handlers: [
    {
      name: "methodName",
      handler: function() {},
      validator: function() {},
      value: ""
    }
  ]
}

其中 validator 用于验证参数合法性，value 为验证不通过时的返回值，它们都是可省略的。

var GeometryMethods = {
    Graphic: {
      Circle: {
        validator: function( radius ) {
          return typeof radius === "number";
        },
        value: 0,
        handlers: [{
            name: "perimeter",
            handler: function( radius ) {
              return Math.PI * radius * 2;
            }
          }]
      },
      Rectangle: {
        handlers: [{
            name: "area",
            handler: function( width, height ) {
              return true;
            },
            validator: function( width, height ) {
              return typeof width === "number" && typeof height === "number";
            },
            value: 0
          }]
      }
    }
  };

// 扩展 YouYu 自身
YouYu.extend(GeometryMethods);

typeof YouYu.perimeter;
=> "function"

// 创建新对象
var Geometry = YouYu.extend(GeometryMethods, {});

Geometry;
=> Object {perimeter: function, area: function}

// 扩展新建的对象
YouYu.extend({
  handlers: [{
    name: "volume",
    handler: function( a, b, h ) {
      return a * b * h;
    }
  }]
}, Geometry);

Geometry;
=> Object {perimeter: function, area: function, volume: function}

addComponent

为 YouYu 添加一个组件类的方法。

YouYu.addComponent(name, initializer) Anything

name: [String]
组件的名字（方法名）
initializer: [Function]
初始化组件

// 创建一个新组件
YouYu.addComponent("dialog", function( settings ) {
  var defaultSettings = {
    title: "对话框",
    width: 600,
    height: 400
  };

  settings = $.extend(true, {}, defaultSettings, settings);

  ...
});

// 调用新创建的组件
YouYu.dialog({title: "弹窗", width: 300, height: 200});

字符串

stringify

将任意类型的变量转化为字符串。

YouYu.stringify(target) String

target: [Anything]

YouYu.stringify(1234567);
=> "1234567"

YouYu.stringify("1234567");
=> "\"1234567\""

YouYu.stringify(true);
=> "true"

YouYu.stringify(function() {
  return 1234567 + "1234567";
});
=> "function () {
      return 1234567 + \"1234567\";
    }"

YouYu.stringify([1, 2, 3, [4, [5, 6], 7]]);
=> "[1,2,3,[4,[5,6],7]]"

YouYu.stringify({
  n: 1234567,
  s: "1234567",
  b: true,
  f: function() {
    return 1234567 + "1234567";
  }
});
=> "{\"n\":1234567,\"s\":\"1234567\",\"b\":true,\"f\":function () {
      return 1234567 + \"1234567\";
    }}"

pad

用指定占位符填补字符串。

YouYu.pad(target, length[, placeholder]) String

target

[String]

原字符串

length

[Integer]

必须为整数，可以是正数也可以是负数。

数字部分代表目标字符串的长度，正负号代表占位符添加的位置：正数时添加到原字符串的后边；负数时添加到原字符串的前边。

placeholder

[String]

占位符，只能是一个字符，默认为空格（\x20）。

YouYu.pad("b", 3, "e");
=> "bee"

YouYu.pad("var foo;", -10);
=> "  var foo;"

YouYu.pad("var foo;", -10.9);
=> "var foo;"

对象

hasProp

判断指定对象自身是否拥有指定属性。

YouYu.hasProp(prop[, object]) Boolean

prop

[String]

object

[Object]

被检测属性的宿主。如果忽略，则为 YouYu 自身。

YouYu.hasProp("hasProp");
=> true

YouYu.hasProp("document", window);
=> true

namespace

通过命名空间格式的字符串从指定对象上获取值。若指定对象上不存在相应的 key，则创建一个空对象。

YouYu.namespace(target[, nsStr1][, nsStrN][, isGlobal]) Object

target: [Object]
nsStr1: [String]
nsStrN: [String]
isGlobal: [Boolean]

nsStr1 和 nsStrN 是以 . 分割的由数字、字母和下划线所组成的字符串。若 isGlobal 的值为 true，则 target 为全局对象。

keys

获取指定对象的 key 集合。

YouYu.keys(target) Array

target: [Object]

var obj = {
  foo: "foo",
  bar: "bar",
  foobar: function() {
    return this.foo + this.bar;
  }
};

YouYu.keys(obj);
=> ["bar", "foo", "foobar"]

数组及类数组

slice

返回数组、类数组对象的片段。

YouYu.slice(target[, begin][, end]) Array

target: [Array / Array-like object]
begin: [Integer]
end: [Integer]

begin 和 end 是以零开始的索引，为负数时表示从 target 的末尾算起的偏移量。当 begin 被忽略时从 0 开始截取；end 被忽略时，截取到 target 的末尾。

String 类型也能够使用。

var arr = [1, 2, 3, 4, 5, 6];

YouYu.slice(arr);
=> [1, 2, 3, 4, 5, 6]

YouYu.slice(arr) === arr;
=> false

YouYu.slice(arr, 2);
=> [3, 4, 5, 6]

YouYu.slice(arr, -2);
=> [5, 6]

YouYu.slice(arr, 2, 4);
=> [3, 4]

YouYu.slice(arr, 2, 2);
=> []

YouYu.slice(arr, -2, -3);
=> []

YouYu.slice(arr, -2, -1);
=> [5]

YouYu.slice(arr, 2, -1);
=> [3, 4, 5]

日期时间

date

格式化日期

YouYu.date(format[, date]) String

format

[String]

指定格式化的形式（参照PHP: date）

date

[Date / String]

日期对象或能被解析成日期对象的字符串（参照Date.parse()）

如果 date 被忽略或者非法，则返回当前时间的格式化后的结果。

// ISO 8601 扩展格式（UTC）
YouYu.date("y-m-d H:i:s", "1994-03-28T10:11:22");
=> "94-03-28 18:11:22"

// ISO 8601 扩展格式（指定时区）
YouYu.date("y-m-d H:i:s", "1994-03-28T10:11:22+0800");
=> "94-03-28 10:11:22"

YouYu.date("F j, Y", "Feb 24 1955 GMT");
=> "February 24, 1955"

// 传入当前时间的日期对象
YouYu.date("Y年n月j日", new Date());
=> "2014年7月24日"

// 传入错误非法日期参数，返回当前时间
YouYu.date("Y年n月j日", "YouYu is good!");
=> "2014年7月24日"

// 忽略日期参数，返回当前时间
YouYu.date("Y年n月j日");
=> "2014年7月24日"

now

取得当前时间

YouYu.now([isObject]) Integer / Date

isObject: [Boolean]
值为 true 时返回日期对象

默认返回毫秒，即 (new Date()).getTime()。

YouYu.now();
=> 1406183042252

YouYu.now(true);
=> Thu Jul 24 2014 14:24:05 GMT+0800 (China Standard Time)

变量检测

isInteger

判断是否为一个整型数字。

YouYu.isInteger(object) Boolean

object: [Anything]

YouYu.isInteger(0x88);
=> true

YouYu.isInteger(0100);
=> true

YouYu.isInteger(+10.0);
=> true

YouYu.isInteger(-1);
=> true

YouYu.isInteger("0x88");
=> true

YouYu.isInteger("0100");
=> true

YouYu.isInteger("+10.0");
=> true

YouYu.isInteger("-1");
=> true

isArrayLike

判断是否为类数组对象。

YouYu.isArrayLike(object) Boolean

object: [Anything]

YouYu.isArrayLike([]);
=> false

YouYu.isArrayLike(document.links);
=> true

YouYu.isArrayLike(document.getElementsByTagName("div"));
=> true

isEmpty

判断是否为空。

YouYu.isEmpty(object) Boolean

object: [Anything]

当 object 的值是以下几种：

null
undefined
""
{}

或者是数组、类数组对象并且 object.length 的值为 0 时，结果返回 true。

YouYu.isEmpty(null);
=> true

YouYu.isEmpty(undefined);
=> true

YouYu.isEmpty("");
=> true

YouYu.isEmpty([]);
=> true

YouYu.isEmpty({});
=> true

isElement

判断是否为 DOM 元素节点。

YouYu.isElement(object) Boolean

object: [Anything]

YouYu.isElement(document);
=> false

YouYu.isElement(document.body);
=> true

YouYu.isElement(window);
=> false

equal

比较两个同类型的变量是否相等

YouYu.equal(base, target[, strict]) Boolean

base: [Anything]
target: [Anything]
strict: [Boolean]
值为 true 时严格比较

当 base 和 target 为纯对象或数组时，如果 strict 的值为 true 则比较它们的引用，否则对它们的结构进行对比。

var arr1 = [1, 2, 3];
var arr2 = [1, 2, 3];
var arr3 = [1, 3, 2];
var obj1 = {foo: "foo", bar: "bar", foobar: function() { return this.foo + this.bar; }};
var obj2 = {foo: "foo", bar: "bar", foobar: function() { return this.foo + this.bar; }};
var obj3 = {foo: "foo", foobar: function() { return this.foo + this.bar; }, bar: "bar"};

// 比较两个结构相同、值也相同的数组
YouYu.equal(arr1, arr2);
=> true

// 严格比较两个结构相同、值也相同的数组
YouYu.equal(arr1, arr2, true);
=> false

// 比较两个结构不同、值相同的数组
YouYu.equal(arr1, arr3);
=> false

// 比较两个结构相同、key 顺序相同的纯对象
YouYu.equal(obj1, obj2);
=> true

// 严格比较两个结构相同、key 顺序相同的纯对象
YouYu.equal(obj1, obj2, true);
=> false

// 比较两个结构相同、key 顺序不同的纯对象
YouYu.equal(obj1, obj3);
=> true

// 比较两个值相同的原始类型
YouYu.equal(1, 1);
=> true

// 严格比较两个值相同的原始类型
YouYu.equal(1, 1, true);
=> true

// 比较值相同的原始类型和对应的包装对象
YouYu.equal(1, new Number(1));
=> true

// 严格比较值相同的原始类型和对应的包装对象
YouYu.equal(1, new Number(1), true);
=> false

// 比较两个在用 == 时返回 true 的原始类型
YouYu.equal(1, "1");
=> false

有渔前端团队

API

核心

目录

名称设置

mask

alias

扩展能力

mixin

extend

addComponent

字符串

stringify

pad

对象

hasProp

namespace

keys

数组及类数组

slice

日期时间

date

now

变量检测

isInteger

isArrayLike

isEmpty

isElement

equal