Seajs学习（4）- seajs.config() 配置

seajs.config()可以对 Sea.js 进行配置，让模块编写、开发调试更方便。

语法：seajs.config(options)

用来进行配置的方法。

  seajs.config({

    // 别名配置
    alias: {
      'es5-safe': 'gallery/es5-safe/0.9.3/es5-safe',
      'json': 'gallery/json/1.0.2/json',
      'jquery': 'jquery/jquery/1.10.1/jquery'
    },

    // 路径配置
    paths: {
      'gallery': 'https://a.alipayobjects.com/gallery'
    },

    // 变量配置
    vars: {
      'locale': 'zh-cn'
    },

    // 映射配置
    map: [
      ['http://example.com/js/app/', 'http://localhost/js/app/']
    ],

    // 预加载项
    preload: [
      Function.prototype.bind ? '' : 'es5-safe',
      this.JSON ? '' : 'json'
    ],

    // 调试模式
    debug: true,

    // Sea.js 的基础路径
    base: 'http://example.com/path/to/base/',

    // 文件编码
    charset: 'utf-8'
  });

支持以下配置选项：

1.alias Object

当模块标识很长时，可以使用 alias 来简化。

  seajs.config({
    alias: {
      'jquery': 'jquery/jquery/1.10.1/jquery',
      'app/biz': 'http://path/to/app/biz.js',
    }
  });

  define(function(require, exports, module) {

     var $ = require('jquery');
       //=> 加载的是 http://path/to/base/jquery/jquery/1.10.1/jquery.js

     var biz = require('app/biz');
       //=> 加载的是 http://path/to/app/biz.js

  });

使用 alias，可以让文件的真实路径与调用标识分开，有利于统一维护。

2.paths Object

当目录比较深，或需要跨目录调用模块时，可以使用 paths 来简化书写。

  seajs.config({
    paths: {
      'gallery': 'https://a.alipayobjects.com/gallery',
      'app': 'path/to/app',
    }
  });

  define(function(require, exports, module) {

     var underscore = require('gallery/underscore');
       //=> 加载的是 https://a.alipayobjects.com/gallery/underscore.js

     var biz = require('app/biz');
       //=> 加载的是 path/to/app/biz.js

  });

paths 配置可以结合 alias 配置一起使用，让模块引用非常方便。

3.vars Object

有些场景下，模块路径在运行时才能确定，这时可以使用 vars 变量来配置。

  seajs.config({
    vars: {
      'locale': 'zh-cn'
    }
  });

  define(function(require, exports, module) {
    var lang = require('./i18n/{locale}.js');
       //=> 加载的是 path/to/i18n/zh-cn.js
  });

vars 配置的是模块标识中的变量值，在模块标识中用 {key} 来表示变量。

4.map Array

该配置可对模块路径进行映射修改，可用于路径转换、在线调试等。

  seajs.config({
    map: [
      [ '.js', '-debug.js' ]
    ]
  });

  define(function(require, exports, module) {
    var a = require('./a');
       //=> 加载的是 path/to/a-debug.js
  });

更多用法可参考：调试实践（https://github.com/seajs/seajs/issues/263）

5.preload Array

使用 preload 配置项，可以在普通模块加载前，提前加载并初始化好指定模块。

  // 在老浏览器中，提前加载好 ES5 和 json 模块
  seajs.config({
    preload: [
      Function.prototype.bind ? '' : 'es5-safe',
      this.JSON ? '' : 'json'
    ]
  });

preload 中的空字符串会被忽略掉。

注意：preload 中的配置，需要等到 use 时才加载。比如：

  seajs.config({
    preload: 'a'
  });

  // 在加载 b 之前，会确保模块 a 已经加载并执行好
  seajs.use('./b');

preload 配置不能放在模块文件里面：

  seajs.config({
    preload: 'a'
  });

  define(function(require, exports) {
    // 此处执行时，不能保证模块 a 已经加载并执行好
  });

6.debug Boolean

值为 true 时，加载器不会删除动态插入的 script 标签。插件也可以根据 debug 配置，来决策 log 等信息的输出。

7.base String

Sea.js 在解析顶级标识时，会相对 base 路径来解析。详情请参阅模块标识

注意：一般请不要配置 base 路径，把 sea.js 放在合适的路径往往更简单一致。

模块标识是一个字符串，用来标识模块。在 require、 require.async 等加载函数中，第一个参数都是模块标识。

Sea.js 中的模块标识是 CommonJS 模块标识的超集:

1.一个模块标识由斜线（/）分隔的多项组成。

2.每一项必须是小驼峰字符串、 . 或 .. 。

3.模块标识可以不包含文件后缀名，比如 .js 。

4.模块标识可以是相对或顶级标识。如果第一项是 . 或 ..，则该模块标识是相对标识。

5.顶级标识根据模块系统的基础路径来解析。

6.相对标识相对 require 所在模块的路径来解析。

注意，符合上述规范的标识肯定是 Sea.js 的模块标识，但 Sea.js 能识别的模块标识不需要完全符合以上规范。比如，除了大小写字母组成的小驼峰字符串，Sea.js 的模块标识字符串还可以包含下划线（_）和连字符（-），甚至可以是 http://、https://、file:/// 等协议开头的绝对路径。

（1）相对标识

相对标识以 . 开头，只出现在模块环境中（define 的 factory 方法里面）。相对标识永远相对当前模块的 URI 来解析：

  // 在 http://example.com/js/a.js 的 factory 中：
  require.resolve('./b');
    // => http://example.com/js/b.js

  // 在 http://example.com/js/a.js 的 factory 中：
  require.resolve('../c');
    // => http://example.com/c.js

（2）顶级标识

顶级标识不以点（.）或斜线（/）开始，会相对模块系统的基础路径（即 Sea.js 的 base 路径）来解析：

  // 假设 base 路径是：http://example.com/assets/
  // 在模块代码里：
  require.resolve('gallery/jquery/1.9.1/jquery');
    // => http://example.com/assets/gallery/jquery/1.9.1/jquery.js

模块系统的基础路径即 base 的默认值，与 sea.js 的访问路径相关：

  如果 sea.js 的访问路径是：
    http://example.com/assets/sea.js
  若未显式的配置base值，则 base 路径默认为：
    http://example.com/assets/

当 sea.js 的访问路径中含有版本号时，base 不会包含 seajs/x.y.z 字串。当 sea.js 有多个版本时，这样会很方便。

  如果 sea.js 的路径是：
    http://example.com/assets/seajs/1.0.0/sea.js
  则 base 路径是：
    http://example.com/assets/

当然，也可以手工配置 base 路径：

  seajs.config({
    base: 'http://code.jquery.com/'
  });

  // 在模块代码里：
  require.resolve('jquery');
    // => http://code.jquery.com/jquery.js

（3）普通路径

除了相对和顶级标识之外的标识都是普通路径。普通路径的解析规则，和 HTML 代码中的 <script src="..."></script> 一样，会相对当前页面解析。

  // 假设当前页面是 http://example.com/path/to/page/index.html

  // 绝对路径是普通路径：
  require.resolve('http://cdn.com/js/a');
    // => http://cdn.com/js/a.js

  // 根路径是普通路径：
  require.resolve('/js/b');
    // => http://example.com/js/b.js

  // use 中的相对路径始终是普通路径：
  seajs.use('./c');
    // => 加载的是 http://example.com/path/to/page/c.js
  seajs.use('../d');
    // => 加载的是 http://example.com/path/to/d.js

提示：

1.顶级标识始终相对 base 基础路径解析。

2.绝对路径和根路径始终相对当前页面解析。

3.require 和 require.async 中的相对路径相对当前模块路径来解析。

4.seajs.use 中的相对路径始终相对当前页面来解析。

（4）文件后缀的自动添加规则

Sea.js 在解析模块标识时，除非在路径中有问号（?）或最后一个字符是井号（#），否则都会自动添加 JS 扩展名（.js）。如果不想自动添加扩展名，可以在路径末尾加上井号（#）。

  // ".js" 后缀可以省略：
  require.resolve('http://example.com/js/a');
  require.resolve('http://example.com/js/a.js');
    // => http://example.com/js/a.js

  // ".css" 后缀不可省略：
  require.resolve('http://example.com/css/a.css');
    // => http://example.com/css/a.css

  // 当路径中有问号（"?"）时，不会自动添加后缀：
  require.resolve('http://example.com/js/a.json?callback=define');
    // => http://example.com/js/a.json?callback=define

  // 当路径以井号（"#"）结尾时，不会自动添加后缀，且在解析时，会自动去掉井号：
  require.resolve('http://example.com/js/a.json#');
    // => http://example.com/js/a.json

（5）设计原则

模块标识的规则就上面这些，设计的核心出发点是：

1.关注度分离。比如书写模块 a.js 时，如果需要引用 b.js，则只需要知道 b.js 相对 a.js 的相对路径即可，无需关注其他。

2.尽量与浏览器的解析规则一致。比如根路径（/xx/zz）、绝对路径、以及传给 use 方法的非顶级标识，都是相对所在页面的 URL 进行解析。

一旦理解了以上两点，一切都会很自然、很简单。不必刻意去记这些规则，多写写，自然就会。

8.charset String | Function

获取模块文件时，<script> 或 <link>标签的 charset 属性。默认是 utf-8

charset 还可以是一个函数：

  seajs.config({
    charset: function(url) {
      // xxx 目录下的文件用 gbk 编码加载
      if (url.indexOf('http://example.com/js/xxx') === 0) {
        return 'gbk';
      }

      // 其他文件用 utf-8 编码
      return 'utf-8';
    }
  });

9.提示

（1）多次配置自动合并

seajs.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']
  });

上面两处 config 运行的结果是：

   alias = {
     'jquery': 'path/to/jquery.js',
     'underscore': 'path/to/underscore.js',
     'a': 'path/to/biz/a.js'
   };
   preload = ['seajs-text', 'seajs-combo'];

即：config 会自动合并不存在的项，对存在的项则进行覆盖。

（2）插件的配置

插件可以给 Sea.js 添加配置项，请查看具体插件了解相关配置。

（3）配置文件

配置可以直接写在 html 页面上，也可以独立出来成为一个文件。

  config.js
  seajs.config({
    ...
  });

独立成一个文件时，一般通过 script 标签在页面中同步引入。

常用的配置项是 alias、paths、base，其他配置项有需要时，来查查文档就会用了。

原文地址：https://github.com/seajs/seajs/issues/262

posted @ 2014-12-02 21:39 South Wind Views(590) Comments(0) 收藏举报

刷新页面返回顶部

South Wind

Seajs学习（4）- seajs.config() 配置

公告