SRLIB: A JavaScript repository from Samlv9

前言

这是一个偏向底层的 Javascript 类库，旨在解决目前（2015年）许多高级类库不断的编写重复代码的问题。如果你需要的是一个适用于特定领域的类库或者框架（比如 DOM 操作，Ajax 数据交互，Tween 动画等），那么或许该类库并不合适你。

参考这样一个例子：

1，开发人员 A 需要实现一个计时器功能的类型。
2，开发人员 B 需要实现一个 Tween 动画功能的类型。
3，他们每个人都需要通过使用 setTimeout/requestAnimationFrame 来首先实现一个 Timer 的基础类型。然后通过 Timer 类型提供的更新事件（update）来更新计时器的值或者更新动画的当前状态。

在上面的例子中，我们完全可以通过封装 setTimeout/requestAnimation 来实现一个公共的 Timer 类型，然后开发人员 A 和 B 在他们的项目的中引用这个公共的 Timer 类型，从而达到消除重复代码的目的。这也是目前许多人开发人员采用的方式。

为了保证项目中的模块具备良好的通用的性质，因此项目采用最小化设计的原则。通过尽量减少模块之间的依赖性，来保证模块被引用到多个其他的项目中时，不会发生代码冲突。

分支

该项目使用 Git 分支来管理项目中的源代码、文档、以及扩展工具等。下面简要介绍这些分支的功能和用途。

docs：文档分支，用于编写帮助文档/使用手册等。
master：主分支，其他分支的合并后的分支。用于发布功能，版本管理等。
source：源码代码分支，用于编写源代码文件。
toolkit：工具分支，用于提供辅助开发的工具。

你可以在 Branches 页面找到所有分支的详细情况。通过使用工作分支来管理工作内容，这样可以使得整个项目不会看起来那样的杂乱无章。每一个分支的作用都是独立并且是唯一的。最终，所有的分支中的文件都会被合并至 master 主分支。然后进行发布。如果你只需要源码文件，可以在你获得仓库的副本后，运行下面这条 git 命令来检出 source 分支：

git checkout source

概览

下面这个表列出了项目当前的部分功能模块，完整的功能模块定义可以在 src 目录中找到：

_{注：这里显示的并不是实时状态的数据。如果你需要最新的状态数据，请移步提交日志。}

模块	状态	更新日期	描述
core	Pending...	2015/11/05	用于提供最顶层核心的函数/类型。
codec	Working...	2015/11/16	用于提供编码和解码（encoder/decoder）类。包括：UTF8/Base64/Hex，JPEG/PNG/BMP，AAC/MP3，H.264/VP8 等文本，图片，音频，视频解码类型。
crypto	N/A	N/A	用于提供安全加密的类。包括：MD4/MD5/SHA-1，RSA，DES/AES 等哈希函数，对称/非对称加密函数。
events	N/A	N/A	用于提供对 DOM Level 3 Events 定义的事件系统的 Javascript 版本的实现。
network	N/A	N/A	用于提供网络通信的类型。包括：Http 下载/上传、流处理、Socket 连接、P2P 连接等。

开发指南

1，使用 Git Shell、Github Windows 或者 Microsoft Visual Studio 的团队资源管理器来获取该项目的副本。

Git Shell： git clone https://github.com/Samlv9/SRLIB.git
Github Windows： Clone in Desktop
团队资源管理器： 点击页面右侧栏的 Open in Visual Studio 按钮

2，将当前目录切换至 解决方案 目录中：

_{注：所有的 git 操作都是在解决方案目录中进行的。如：git checkout source。}

cd ./SRLIB

3，从 解决方案 目录切换至 项目 目录中：

_{注：所有针对项目的编译和测试都是在项目目录中进行的。如：npm build。}

cd ./SRLIB

4，安装 NodeJS 依赖项：

npm install

5，编译 src/main.js 文件：

npm build

6，将 dist/main.js 文件引入你的项目中。

<script src="dist/main.js"></script>

7，你可以通过 npm test 命令来确保你下载的副本是通过编译的。但通常情况这是不必要的。因为该项目使用 TRAVIS-CI 进行持续化集成，当项目编译失败时，我们会第一时间收到通知并处理：

npm test

通过在 src/main.js 文件添加 <reference> 来将项目中的模块编译进 dist/main.js 文件中，并在你自己的项目中使用。例如，假设你打算使用 core/derive 方法来作为你项目的原型继承函数，编辑 src/main.js 添加下面这条 <reference> 引用语句，并使用 npm build^[步骤5]重新编译 src/main.js。

/// <reference path='core/derive.js' />
/// 由于 <reference> 标记只是导入一个局部变量至当前作用域中，因此你可以使用任意一种方式将局部变量 
/// `derive` 公开，比如： `window.derive = derive;`

window.SRLib = { 
    derive: derive
};

然后就可以在你的项目中像下面这样使用 derive 函数：

/// MyProject.js

function SuperClass() {
    /// 父类
}

function ChildClass() {
    /// 子类
}

SRLib.derive(SuperClass, ChildClass);

如果你希望直接包含 SRLib 项目中的模块，这样你就不需要通过 window 对象来公开局部变量。可以像这样编辑 src/main.js：

/// src/main.js
/// <reference path='core/derive.js' />

function SuperClass() {
    /// 父类
}

/// `derive` 函数存在于当前作用域中。
function ChildClass() {
    /// 子类
}

derive(SuperClass, ChildClass);

src/main.js 不需要添加函数闭包块，因为在执行 npm build 编译时，会自动给该文件前后添加下面这段：

(function main( domain, undefined ) { 'use strict';
/// 这里会被 `src/main.js` 中的内容替换。
}(this || window));

下面是一个完整的例子：

/// src/main.js
/// <reference path='core/derive.js' />

function SuperClass() {
    /// 父类
}

SuperClass.prorotype.say = function say() {
    console.log("ctor:", this.constructor);
}

function ChildClass() {
    /// 子类
}

derive(SuperClass, ChildClass);

var obj = new ChildClass();
obj.say();

执行 npm build 后输出的 dist/main.js：

/// dist/main.js

(function main( domain, undefined ) { 'use strict';
    /// `derive` 函数的源代码会被编译进来。
    function derive() { ... }

    function SuperClass() {
        /// 父类
    }

    SuperClass.prorotype.say = function say() {
        console.log("ctor:", this.constructor);
    }

    function ChildClass() {
        /// 子类
    }

    derive(SuperClass, ChildClass);

    var obj = new ChildClass();
    obj.say();
}(this || window));

使用 <reference> 标记注意事项：

标记中使用的单行注释是 3 个斜杠（///）。
标记需要放在 src/main.js 文件的头部（该标记之前不能有任何可执行的代码）。
更多详情请参考：Microsoft Javascript Intellisense。

工具

名称	状态	更新日期	描述
reference	v1.1.2	2015/11/16	用于解析模块的引用以及基于引用关系生成最终代码。

问题

1，如果你在使用过程中遇到任何问题，可以将你的问题提交至 Issus 中。
2，如果你希望改进项目中的某个功能，可以参考开发指南中的步骤拷贝一份副本至本地，并使用你改进后的代码发起一个 Pull Request 来将你的代码合并至当前项目中。

Samlv9/SRLIB

前言

分支

概览

开发指南

工具

问题