使用指南

最后更新于:2022-04-01 02:01:59

刚才的示例很简单?实际上Sea.js本身小巧而不失灵活,让我们再来深入地了解下如何使用Sea.js! ## 定义模块 Sea.js是[CMD](https://github.com/cmdjs/specification/blob/master/draft/module.md)这个模块系统的一个运行时,Sea.js可以加载的模块,就是CMD规范里所指明的。那我们该如何编写一个CMD模块呢? Sea.js提供了一个全局方法——`define`,用来定义一个CMD模块。 #### `define(factory)` ~~~ define(function(require, exports, module) { // 模块代码 // 使用require获取依赖模块的接口 // 使用exports或者module来暴露该模块的对外接口 }) ~~~ `factory`是这样一个函数`function (require?, exports?, module?) {}`,如果模块本身既不依赖其他模块,也不提供接口,`require`、`exports`和`module`都可以省略。但通常会是以下两种形式: ~~~ define(function(require, exports) { var Vango = require('vango') exports.drawCircle = function () { var vango = new Vango(document.body, 100, 100) vango.circle(50, 50, 50, { fill: true, styles:{ fillStyle:"red" } }) } }) ~~~ 或者: ~~~ define(function(require, exports, module) { var Vango = require('vango'); module.exports = { drawCircle: function () { var vango = new Vango(document.body, 100, 100); vango.circle(50, 50, 50, { fill: true, styles:{ fillStyle:"red" } }); } }; }); ~~~ > **注意**:必须保证参数的顺序,即需要用到require, exports不能省略;在模块中exports对象不可覆盖,如果需要覆盖请使用`module.exports`的形式(这与node的用法一致,在后面的原理介绍会有相关的解释)。你可以使用`module.exports`来export任意的对象(包括字符串、数字等等)。 #### `define(id?, dependencies?, factory)` **id**:String 模块标识 **dependencies**:Array 模块依赖的模块标识 这种写法属于[Modules/Transport/D](http://wiki.commonjs.org/wiki/Modules/Transport/D)规范。 ~~~ define('drawCircle', ['vango'], function(require, exports) { var Vango = require('vango'); exports.drawCircle = function () { var vango = new Vango(document.body, 100, 100); vango.circle(50, 50, 50, { fill: true, styles:{ fillStyle:"red" } }); }; }) ~~~ 与CMD的`define`没有本质区别,我更情愿把它称作“具名模块”。Sea.js从用于生产的角度来说,必须支持具名模块,因为开发时模块拆得太小,生产环境必须把这些模块文件打包为一个文件,如果模块都是匿名的,那就傻逼了。([为什么会傻逼?](https://github.com/seajs/seajs/issues/930)) > 所以Sea.js支持具名模块也是无奈之举。 #### `define(anythingelse)` 除去以上两种形式,在CMD标准中,可以给define传入任意的字符串或者对象,表示接口就是对象或者字符串。不过这只是包含在标准中,在Sea.js并没有相关的实现。 ## 配置Sea.js Sea.js为了能够使用起来更灵活,提供了配置的接口。可配置的内容包括静态服务的位置,简化模块标识或路径。接下来我们来详细地了解下这些内容。 #### seajs.config(config) **config**:Object,配置键值对。 Sea.js通过`.config`API来进行配置。你甚至可以在多个地方调用seajs.config来配置。Sea.js会mix传入的多个config对象。 ~~~ seajs.config({ alias: { 'jquery': 'path/to/jquery.js', 'a': 'path/to/a.js' }, preload: ['seajs-text'] }) ~~~ ~~~ seajs.config({ alias: { 'underscore': 'path/to/underscore.js', 'a': 'path/to/biz/a.js' }, preload: ['seajs-combo'] }) ~~~ 上面两个配置会合并为: ~~~ { alias: { 'jquery': 'path/to/jquery.js', 'underscore': 'path/to/underscore.js', 'a': 'path/to/biz/a.js' }, preload: ['seajs-text', 'seajs-combo'] } ~~~ `config`可以配置的键入下: #### base **base**:String,在解析绝对路径标识的模块时所使用的base路径。 默认地,在不配置base的情况下,base与sea.js的引用路径。如果引用路径为`http://example.com/assets/sea.js`,则base为`http://example.com/assets/`。 > 在阅读Sea.js这份文档时看到: > _当 sea.js 的访问路径中含有版本号时,base 不会包含 seajs/x.y.z 字串。 当 sea.js 有多个版本时,这样会很方便。_ > 即如果sea.js的引用路径为[http://example.com/assets/1.0.0/sea.js,则base仍为http://example.com/assets/。这种方便性,我觉得过了点。](http://example.com/assets/1.0.0/sea.js%EF%BC%8C%E5%88%99base%E4%BB%8D%E4%B8%BAhttp://example.com/assets/%E3%80%82%E8%BF%99%E7%A7%8D%E6%96%B9%E4%BE%BF%E6%80%A7%EF%BC%8C%E6%88%91%E8%A7%89%E5%BE%97%E8%BF%87%E4%BA%86%E7%82%B9%E3%80%82) 使用base配置,根本上可以分离静态文件的位置,比如使用CDN等等。 ~~~ seajs.config({ base: 'http://g.tbcdn.cn/tcc/' }) ~~~ > 如果我们有三个CDN域名,如何将静态资源散列到这三个域名上呢? #### paths **paths**:Object,如果目录太深,可以使用paths这个配置项来缩写,可以在require时少写些代码。 如果: ~~~ seajs.config({ base: 'http://g.tbcdn.cn/tcc/', paths: { 'index': 's/js/index' } }) ~~~ 则: ~~~ define(function(require, exports, module) { // http://g.tbcdn.cn/tcc/s/js/index/switch.js var Switch = require('index/switch') }); ~~~ #### alias **alias**:Object,本质上看不出和paths有什么区别,区别就在使用的概念上。 ~~~ seajs.config({ alias: { 'jquery': 'jquery/jquery/1.10.1/jquery' } }) ~~~ 然后: ~~~ define(function(require, exports, module) { // jquery/jquery/1.10.1/jquery var $ = require('jquery'); }); ~~~ > 看出使用概念的区别了么? #### preload `preload`配置项可以让你在加载普通模块之前提前加载一些模块。既然所有模块都是在use之后才加载的,preload有何意义?然,看下面这段: ~~~ seajs.config({ preload: [ Function.prototype.bind ? '' : 'es5-safe', this.JSON ? '' : 'json' ] }); ~~~ preload比较适合用来加载一些核心模块,或者是shim模块。这是一个全局的配置,使用者无需关系核心模块或者是shim模块的加载,把注意力放在核心功能即可。 还有一些别的配置,比如`vars`、`map`等,可以参考[配置](https://github.com/seajs/seajs/issues/262)。 ## 使用模块 #### `seajs.use(id)` Sea.js通过use方法来启动一个模块。 ~~~ seajs.use('./main') ~~~ 在这里,`./main`是main模块的id,Sea.js在main模块LOADED之后,执行这个模块。 Sea.js还有另外一种启动模块的方式: #### seajs.use(ids, callbacks) ~~~ seajs.use('./main', function(main) { main.init() }) ~~~ Sea.js执行ids中的所有模块,然后传递给callback使用。 ## 插件 Sea.js官方提供了7个插件,对Sea.js的功能进行了补充。 * seajs-text:用来加载HTML或者模板文件; * seajs-style:提供了`importStyle`,动态地向页面中插入css; * seajs-combo:该插件提供了依赖combo的功能,能把多个依赖的模块uri combo,减少HTTP请求; * seajs-flush:该插件是对seajs-combo的补充,或者是大杀器,可以先hold住前面的模块请求,最后将请求的模块combo成一个url,一次加载hold住的模块; * seajs-debug:Fiddler用过么?这个插件基本就是提供了这样一种功能,可以通过修改config,将线上文件proxy到本地服务器,便于线上开发调试和排错; * seajs-log:提供一个seajs.log API,私觉得比较鸡肋; * seajs-health:目标功能是,分析当前网页的模块健康情况。 由此可见,Sea.js的插件主要是解决一些附加问题,或者是给Sea.js添加一些额外的功能。私觉得有些功能并不合适让Sea.js来处理。 #### 插件机制 总结一下,插件机制大概就是两种: * 使用Sea.js在加载过程中的事件,注入一些插件代码,修改Sea.js的运行流程,实现插件的功能; * 给seajs加入一些方法,提供一些额外的功能。 > 私还是觉得Sea.js应该保持纯洁;为了实现插件,在Sea.js中加入的代码,感觉有点不值;combo这种事情,更希望采取别的方式来实现。 Sea.js应该做好运行时。 ## 构建与部署 很多时候,某个工具或者类库,玩玩可以,但是一用到生产环境,就感觉力不从心了。就拿Sea.js来说,开发的时候根据业务将逻辑拆分到很多小模块,逻辑清晰,开发方便。但是上线后,模块太多,HTTP请求太多,就会拖慢页面速度。 所以我们必须对模块进行打包压缩。这也是SPM的初衷。 SPM是什么? 使用者认为SPM是Sea.js Package Manager,但是实际上代表的是Static Package Manager,及静态包管理工具。如果大家有用过npm,你可以认为SPM是一个针对前端模块的包管理工具。当然它不仅仅如此。 SPM包括: * 源服务:类似于npm源服务器的源服务; * 包管理工具:相当于npm的命令行,安装、发布模块,解决模块依赖; * 构建工具:模块CMD化、合并模块、压缩等;都是针对我们一开始提到的问题; * 配置管理:管理配置; * 辅助功能:比较像Yeoman,以插件提供一些便于平时开发的组件。 > SPM心很大,SPM囊括yo、bower和grunt这三个工具。 ### spm > spm is a package manager, it is not build tools. 这句话来自github上[spm2](https://github.com/spmjs/spm2)的README文件。`spm是一个包管理工具,不是构建工具!`,它与npm非常相似。 #### spm的包规范 一个spm的模块至少包含: ~~~ -- dist -- overlay.js -- overlay.min.js -- package.json ~~~ ##### package.json 在模块中必须提供一个package.json,该文件遵循[Common Module Definition](https://github.com/cmdjs/specification)模块标准。与node的`package.json`兼容。在此基础上添加了两个key。 * family,即是包发布者在spmjs.org上的用户名; * spm,针对spm的配置。 一个典型的`package.json`文件: ~~~ { "family": "arale", "name": "base", "version": "1.0.0", "description": "base is ....", "homepage": "http://aralejs.org/base/", "repository": { "type": "git", "url": "https://github.com/aralejs/base.git" }, "keywords": ["class"], "spm": { "source": "src", "output": ["base.js", "i18n/*"], "alias": { "class": "arale/class/1.0.0/class", "events": "arale/events/1.0.0/events" } } } ~~~ ##### dist `dist`目录包含了模块必要的模块代码;可能是使用spm-build打包的,当然只要满足两个条件,就是一个spm的包。 #### 安装 `$ npm install spm -g` 安装好了spm,那该如何使用spm呢?让我们从help命令开始: #### help 我们可以运行`spm help`查看`spm`所包含的功能: ~~~ $ spm help Static Package Manager Usage: spm <command> [options] Options: -h, --help output usage information -V, --version output the version number System Commands: plugin plugin system for spm config configuration for spm help show help information Package Commands: tree show dependencies tree info information of a module login login your account search search modules install install a module publish publish a module unpublish unpublish a module Plugin Commands: init init a template build Build a standar cmd module. ~~~ `spm`包含三种命令,**系统命令**,即与`spm`本身相关(配置、插件和帮助),**包命令**,与包管理相关,**插件命令**,插件并不属于`spm`的核心内容,目前有两个插件`init`和`build`。 也可以使用`help`来查看单个命令的用法: ~~~ $ spm help install Usage: spm-install [options] family/name[@version] Options: -h, --help output usage information -s, --source [name] the source repo name -d, --destination [dir] the destination, default: sea-modules -g, --global install the package to ~/.spm/sea-modules -f, --force force to download a unstable module -v, --verbose show more logs -q, --quiet show less logs --parallel [number] parallel installation --no-color disable colorful print Examples: $ spm install jquery $ spm install jquery/jquery arale/class $ spm install jquery/jquery@1.8.2 ~~~ #### config 我们可以使用`config`来配置用户信息、安装方式以及源。 ~~~ ; Config username $ spm config user.name island205 ; Or, config default source $ spm config source.default.url http://spmjs.org ~~~ #### search `spm`是一个包管理工具,与`npm`类似,有自己的源服务器。我们可以使用`search`命令来查看源提供的包。 > 由于`spm`在包规范中加入了`family`的概念,常常想运行`spm install backbone`,发现并没有backbone这个包。原因就是`backbone`是放在`gallery`这族下的。 ~~~ $ spm search backbone 1 result gallery/backbone keys: model view controller router server client browser desc: Give your JS App some Backbone with Models, Views, Collections, and Events. ~~~ #### install 然后我们就可以使用`install`来安装了,注意我们必须使用包的全名,即`族名/包名`。 ~~~ $ spm install gallery/backbone install: gallery/backbone@stable fetch: gallery/backbone@stable download: repository/gallery/backbone/1.0.0/backbone-1.0.0.tar.gz save: c:\Users\zhi.cun\.spm\cache\gallery\backbone\1.0.0\backbone-1.0.0.tar.gz extract: c:\Users\zhi.cun\.spm\cache\gallery\backbone\1.0.0\backbone-1.0.0.tar.gz found: dist in the package installed: sea-modules\gallery\backbone\1.0.0 depends: gallery/underscore@1.4.4 install: gallery/underscore@1.4.4 fetch: gallery/underscore@1.4.4 download: repository/gallery/underscore/1.4.4/underscore-1.4.4.tar.gz save: c:\Users\zhi.cun\.spm\cache\gallery\underscore\1.4.4\underscore-1.4.4.tar.gz extract: c:\Users\zhi.cun\.spm\cache\gallery\underscore\1.4.4\underscore-1.4.4.tar.gz found: dist in the package installed: sea-modules\gallery\underscore\1.4.4 ~~~ `spm`将模块安装在了`sea_modules`中,并且在`~/.spm/cache`中做了缓存。 ~~~ `~sea-modules/ `~gallery/ |~backbone/ | `~1.0.0/ | |-backbone-debug.js | |-backbone.js | `-package.json `~underscore/ `~1.4.4/ |-package.json |-underscore-debug.js `-underscore.js ~~~ `spm`还加载了`backbone`的依赖`underscore`。 当然,Sea.js也是一个模块,你可以通过下面的命令来安装: ~~~ $ spm install seajs/seajs ~~~ `seajs`的安装路径为`sea_modules/seajs/seajs/2.1.1/sea.js`,看到这里,结合seajs顶级模块定位的方式,对于seajs在计算base路径的时,去掉了`seajs/seajs/2.1.1/`的原因。 #### build `spm`并不是以构建工具为目标,它本身是一个包管理器。所以`spm`将构建的功能以插件的功能提供出来。我们可以通过plugin命令来安装`build`: ~~~ $ spm plugin install build ~~~ 安装好之后,如果你使用的是标准的`spm`包模式,就可以直接运行`spm build`来进行标准的打包。 **SPM2的功能和命令就介绍到这里,更多的命令在之后的实践中介绍。** ### spm与spm2 #### spm与spm2 其实之前介绍的spm是其第二个版本[spm2](https://github.com/spmjs/spm2)。spm的第一个版本可以在[这里](https://github.com/spmjs/spm)找到。 spm与spm2同样都是包管理工具,那它们之间有什么不同呢? * 从定位上,spm2更加强调该工具是一个CMD包管理工具; * 从提供的用户接口(cmd命令)spm2比起spm更加规范,作为包管理工具,在使用方式和命令都更趋同于npm; * 在spm2中,构建命令以插件的方式独立出来,并且分层清晰;Transport和Concat封装成了grunt,便于自定义build方式;基于基础的grunt,构建了一个标准的spm-build工具,用于构建标准的CMD模块; * 与此类似,deploy和init的功能都是以插件的形式提供的; * 修改了package.json规范。 为什么作者对spm进行了大量的重构? 之所以进行大量的重构,就是为了保持spm作为包管理工具的特征。如npm一般,只指定最少的规范(package.json),提供包管理的命令,但是这个包如何构建,代码如何压缩并不是spm关心的事情。 只有规则简单合理,只定义接口,不关心具体实现,才有更广的实用性。 > spm本身是从业务需求成长起来的一个包管理工具,spm1更多的是一些需求功能的堆砌,而spm2就是对这些功能的提炼,形成一套适用于业界的工具。 #### apm apm的全称是: > Alipay package manager 即支付宝的包管理工具。 apm是基于spm的一套专门为支付宝开发的工具集。我们可以这么看,spm2和apm是spm升级后的两个产物,spm2更加专注于包管理和普适性,而apm更加专注于支付宝业务。由于业务细节和规模的不同,apm可能并不适合其他公司所用,所以需要spm2,而又因为支付宝业务的特殊性和基因,必须apm。 谢谢 @lepture 的指正: > 不一定要用 apm,只是 apm 把所有要用到的插件都打包好了,同时相应的默认配置也为支付宝做了处理,方便内部员工使用,不用再配置了。
';