JSFace 项目技术文档

1. 安装指南

浏览器环境

使用 Bower 安装

bower install jsface

在 HTML 文件中引入：

<script src="bower_components/jsface/jsface.js"></script>

使用 CDN

<script src="https://cdn.jsdelivr.net/jsface/2.4.9/jsface.min.js"></script>

手动下载

直接下载 jsface.js 文件并在 HTML 中引入：

<script src="jsface.js"></script>

Node.js 环境

通过 npm 安装：

npm install jsface

然后在代码中使用：

var jsface = require("jsface"),
    Class  = jsface.Class,
    extend = jsface.extend;

2. 项目使用说明

定义一个类

var Person = Class({
  constructor: function(name, age) {
    this.name = name;
    this.age  = age;
  },

  // Getter/Setter
  address: {
    get: function() {
      return this._address;
    },
    set: function(value) {
      this._address = value;
    }
  },

  toString: function() {
    return this.name + "/" + this.age;
  }
});

var person = new Person("Rika", 20);
person.toString();                               // "Rika/20"

定义子类

var Student = Class(Person, {
  constructor: function(id, name, age) {
    this.id = id;
    Student.$super.call(this, name, age);        // 调用父类的构造函数
  },

  toString: function() {
    return this.id + "/" + Student.$superp.toString.call(this); // 调用父类的 toString 方法
  }
});

var student = new Student(1, "Rika", 20);
student.toString();                              // "1/Rika/20"

主方法

JSFace 支持一个特殊的方法 main()，该方法在类创建后立即执行。

Class({
  constructor: function(name) {
    this.name = name;
  },

  getName: function() {
    return this.name;
  },

  main: function(Person) {                       // 类作为第一个参数传递给 main()
    var p = new Person("Rika");

    p.getName();                                 // "Rika"
  }
});

单例类

var Util = Class({
  $singleton: true,

  echo: function(obj) {
    return obj;
  }
});

Util.echo(2012);                                 // 2012

静态属性

var Person = Class({
  $statics: {
    MIN_AGE:   1,
    MAX_AGE: 150,

    isValidAge: function(age) {
      return age >= this.MIN_AGE && age <= this.MAX_AGE;
    }
  },

  constructor: function(name, age) {
    this.name = name;
    this.age  = age;
  }
});

Person.MIN_AGE === 1;                            // true
Person.MAX_AGE === 150;                          // true
Person.isValidAge(0);                            // false

常量

常量与静态属性类似，但不可变。

var Person = Class({
  $const: {
    MIN_AGE: 1,
    MAX_AGE: 150
  },

  constructor: function(name, age) {
    this.name = name;
    this.age  = age;
  }
});

Person.MIN_AGE = -1;
Person.MIN_AGE === 1;                            // true, MIN_AGE 是不可变的

私有属性

JSFace 支持私有静态属性，这些属性在实例之间共享。

var Person = Class(function() {
  var MIN_AGE =   1,                             // 私有变量
      MAX_AGE = 150;

  function isValidAge(age) {                     // 私有方法
    return age >= MIN_AGE && age <= MAX_AGE;
  }

  return {
    constructor: function(name, age) {
      if ( !isValidAge(age)) {
        throw "Invalid parameter";
      }

      this.name = name;
      this.age  = age;
    }
  };
});

混入

JSFace 提供了一个强大的机制来支持混入。可重用的代码可以混入到几乎任何地方。

在定义类时绑定混入

var Options = Class({
  setOptions: function(opts) {
    this.opts = opts;
  }
});

var Events = Class({
  bind: function(event, fn) {
    return true;
  },
  unbind: function(event, fn) {
    return false;
  }
});

var Person = Class({
  constructor: function(name, age) {
    this.name = name;
    this.age  = age;
  }
});

// Student 继承 Person 并扩展 Options 和 Events 的属性
var Student = Class([ Person, Options, Events ], {
  constructor: function(id, name, age) {}
});

var student = new Student(1, "Rika", 20);
student.setOptions({ foo: true });               // student.opts === { foo: true }
student.bind();                                  // true
student.unbind();                                // false

在定义类后绑定混入

var Student = Class(Person, {
  constructor: function(id, name, age) {
});

extend(Student, [ Options, Events ]);

混入实例

var person = new Person("Rika", 20);

extend(person, Options);
person.setOptions({ foo: true });

混入原生类

extend(String.prototype, {
  trim: function() {
    return this.replace(/^\s+|\s+$/g, "");
  }
});

"   Hello World    ".trim();                     // "Hello World"

无冲突模式

在浏览器环境中，如果其他库也使用了全局命名空间 Class，可以通过调用 jsface.noConflict() 恢复原始的 Class。

jsface.noConflict();

// 使用其他库的 Class 的代码可以继续
// ...

// 通过 jsface.Class 直接定义类
var Person = jsface.Class({
});

3. 项目 API 使用文档

类定义 API

• Class(definition): 定义一个新类。
• Class(parent, definition): 定义一个继承自 parent 的子类。
• Class([parent1, parent2, ...], definition): 定义一个继承自多个父类的子类。

混入 API

• extend(target, mixin): 将 mixin 混入到 target 中。

单例 API

• $singleton: true: 定义一个单例类。

静态属性 API

• $statics: { ... }: 定义类的静态属性。

常量 API

• $const: { ... }: 定义类的常量。

私有属性 API

• Class(function() { ... }): 定义类的私有属性。

主方法 API

• main: function(Class) { ... }: 定义类的主方法。

插件 API

• jsface.pointcut(Class, advisor): 应用切面编程（AOP）插件。
• jsface.$ready(clazz, parent, api): 拦截子类的创建。

4. 项目安装方式

浏览器环境

• 使用 Bower 安装：bower install jsface
• 使用 CDN：https://cdn.jsdelivr.net/jsface/2.4.9/jsface.min.js
• 手动下载 jsface.js 文件并在 HTML 中引入。

Node.js 环境

• 使用 npm 安装：npm install jsface
• 在代码中使用：var jsface = require("jsface")