转载自:https://github.com/spmjs/spm/wiki/Hello-spm%EF%BC%9A%E4%BD%BF%E7%94%A8-spm-%E5%92%8C-SeaJS-%E5%BC%80%E5%8F%91%E4%B8%80%E4%B8%AA%E4%B8%AD%E5%9E%8B%E9%A1%B9%E7%9B%AE
现在我们要正儿八经开始开发一个叫 hello-spm 的项目了,别笑,虽然只是个为了让你更好的了解 SPM 而杜撰出来的项目,但也五脏俱全。
我们提供了在线演示:http://fool2fish.github.com/hello-spm 。 毫不犹豫的猛击空格键,就会有有趣的事情发生了。
你可以检出源码:https://github.com/fool2fish/hello-spm 。
在正式开始之前,我还是要啰嗦一句,所有的范例代码都是基于 SeaJS 的, 请确保你已经知道该怎么使用 SeaJS 了。
创建项目目录
我们先来看看项目的整体结构
hello-spm/ assets/ hello/ util/ sea-modules/ package.json index.html
- 考虑到真实的项目通常包含前后端的代码,所有前端代码放在 assets/ 。
- hello 和 util 是为本项目编写的模块。
- sea-modules/ 用于存放安装和部署的模块。如果你的项目基本都是基于 SeaJS 和 SPM 的,你可以把这个目录放置在和项目目录平级的路径下,以便各项目公用。
- package.json 为模块打包部署的总体配置。
- index.html 为项目页面。
安装需要的模块
显然,我们需要用到 seajs 和 jquery,所以要使用 spm install 来安装他们。
打开命令行工具,将路径切换至 sea-modules/ ,运行:
spm install seajs spm install gallery.jquery@1.8.3
创建模块
回想一下 index.html 运行的效果,多处用到了随机数,例如 "hello spm !" 的单个字符大小,字符串出现在页面中的位置以及字符串在页面上停留的时间。
我们把这样一个可产生指定范围的随机整数的工具方法放到 util 模块中。
下面我们来 初始化 这个模块。
命令行工具路径切换至 util/ ,运行:
spm init
util/ examples/ src/ tests/ package.json README.md
- examples/ 用于存放演示文件。
- src/ 为模块源码,打包后的文件会存放到和 src/ 平级的 dist/ 目录下。
- test/ 用于存放测试用例,你可以使用 jasmine 等工具来保障代码的质量。
- package.json 为本模块打包部署的配置。
我们的 hello-spm 实在有点简单,所以演示代码仅保留了 src/ 和 package.json 这两个必备部分。
src/ 中只有 util.js 一个文件, 源码非常简单,如下:
define(function(require, exports) { exports.random = function(min, max){ return min + Math.round(Math.random() * (max - min)) } })
拆分子模块
接下来我们处理相对复杂一些的 hello 模块,他要做这么几件事情:
- 创建字符大小随机的 "Hello SPM !" 字符串。
- 随机显示到页面上。
- 一段时间后自动消失。
这个模块复杂到需要拆分成多个子模块来进行开发 (好吧,我承认这纯粹是教程需要)。使用 spm init 初始化后,在 src/ 中除了默认创建的 hello.js,还需要手工创建一个 handle-text.js 文件。
hello.js 完成大部分的主体功能,而 handle-text.js 专门负责处理传入字符串的随机字符大小。
hello.js 的源码如下:
define(function(require, exports, module) { var $ = require('$') var random = require('util').random var handleText= require('./handle-text') function Hello(){ this.render() this.bindAction() seajs.log('new Hello() called.') } Hello.prototype.render = function(){ this.el = $('<div style="position:fixed;' + 'left:' + random(0,70) + '%;' + 'top:' + random(10,80)+ '%;">' + handleText('Hello SPM !') + '</div>').appendTo('body') } Hello.prototype.bindAction = function(){ var el = this.el setTimeout(function(){ el.fadeOut() }, random(500,5000)) } module.exports = Hello })
注意 :
- var random = require('util').random 是模块方法的引用。
- var handleText= require('./handle-text') 是子模块的引用。
- 在 Hello 类的构造器中,我们还使用 seajs.log 打了一句日志。
更多 require 的说明可查看 SeaJS 的 模块标识
handle-text.js 的源码如下:
define(function(require, exports, module) { var $ = require('$') var random = require('util').random function handleText(text){ var min = random(30,70) var max = random(50,120) var rt = '' for(var i = 0, len = text.length; i < len; i++){ rt += '<span style="font-size:' + random(min, max) + 'px;">' + text[i] + '</span>' } return rt } module.exports = handleText })
编写开发时页面
开发过程中,我们就常常需要编写一些测试用例,或者演示页面。
这种情况下我们希望模块是不需要打包的,并且可以查看日志,以便调试。
本例中,我们并没有为单个模块创建单元测试或者演示页面。简单起见,我们在 index.html 页面中编写了一些开发时的代码,代码如下:
<div style="text-align:center;font-size:48px;color:#999;"> Press the space key !</div> <script src="assets/sea-modules/seajs/1.3.0/sea-debug.js"></script> <script> seajs.config({ alias:{ '$':'gallery/jquery/1.8.3/jquery.js', 'util':'../../util/src/util.js' } }) seajs.use(['$','./assets/hello/src/hello.js'],function($, Hello){ $(document).keypress(function(ev){ if(ev.which == 32){ new Hello() } }) }) </script>
注意:
- 引用 sea-debug.js,可以开启 debug 功能。
- jquery(即 $ )作为 DOM 操作最常使用的模块,总是需要通过 seajs.config 手工配置别名,确保项目内的统一。比如 1.8.3 版本。
- seajs.use 中的 '$' 为顶级 模块标识,相对于 seajs 的 base 路径, './assets/hello/src/hello.js' 为相对标识,相对于当前页面 url。
现在运行 indexg.html 就能看到效果了,源码上做任何的改动也能立马体现,打开调试工具,你还能看到打出的 log。
打包部署
打包配置
结束编码测试工作后,我们就要准备将模块打包部署,以供正式环境使用了。打包相关的配置都写在每个模块的 package.json 中了。
先来看看 util 模块的 package.json
{ "name":"util", "parent":"../package.json", "output":{"util.js":"."} }
- name 为模块名
- parent 指定用于继承的父级配置,路径相对于该配置文件。当你项目中的模块有大量公共配置的时候推荐使用此项.
- output 指定了将 src/util.js 及其模块内的依赖打包为 dist/util.js 。当然,这里 src/util.js 没有模块内依赖。
再接着看 hello 模块的 package.json
{ "name":"hello", "parent":"../package.json", "output":{"hello.js":"."}, "dependencies": { "$": "$", "util":"hellospm/util/0.0.1/util" } }
然后我们还有一个 parent package.json
{ "root": "hellospm", "version": "0.0.1" }
绝大部分和 util 模块的配置一样,只是多了一项 dependencies,需要注意的是:
jquery 作为一个特殊的模块,打包的时候并不指定具体的依赖,仅写上 "$": "$" 即可。
回顾一下,就是因为这个原因,我们在刚刚创建的 index-debug.html 中,还需要为 jquery 配置别名: '$':'gallery/jquery/1.8.3/jquery.js' 。
接下来我们将以 util 模块为例讲解模块的打包部署(hello 模块的打包部署方式完全一样)。
打包
命令行进入到 util/ ,运行:
spm build
SPM 会在 util/dist/ 目录创建 util.js 和 util-debug.js 两个文件。有兴趣的读者可以打开 util-debug.js 看看打包后的文件和源码有何不同。
部署
为了方便演示,我们准备把打包好的模块部署到本地。
进入 util/ ,运行命令:
spm deploy --to=../sea-modules
sea-modules/ hellospm/ util/ 0.0.1/ util.js util-debug.js ...
编写正式页面
胜利就在眼前,我们终于要完成这个项目了。现在我们要把测试用的 index.html 转换成线上正式运行的 index.html,代码如下:
<div style="text-align:center;font-size:48px;color:#999;"> Press the space key !</div> <script src="assets/sea-modules/seajs/1.3.0/sea.js"></script> <script> seajs.config({ alias:{ '$':'gallery/jquery/1.8.3/jquery.js' } }) seajs.use(['$','./assets/sea-modules/hellospm/hello/0.0.1/hello.js'],function($, Hello){ $(document).keypress(function(ev){ if(ev.which == 32){ new Hello() } }) }) </script>
注意 index.html 前后的一些区别:
- index 引用的是 sea.js。
- SPM 在对模块进行打包部署后,依赖关系已经处理好了,所以这里我们只用在 seajs.config 中配置 jquery($) 。