插件开发API

插件开发中需要用到的一些接口。

如果说明还是不够清晰,nodejs里面查看方法最好最容易的方法就是require这个包,并console.log出来。这样就可以一个一个尝试效果。

#打开node交互命令行。$ node> var fis = require("fis");> console.log(fis.file);

Object-Oriented

FIS在OO这块扩展了Object,给其添加了一个派生方法Object.derive。细节就不说了,直接来看使用。

定义一个Object

  1. var Foo = Object.derive(function() {
  2. //constructor
  3. }, {
  4. //extend
  5. });

使用Object

  1. var foo = new Foo();

fis.util

fis.util包含了很多有用的工具方法,比如转码、读取文件、map等。

is(source, type)

  1. fis.util.is('fis', 'String');
  2. // => true

map(obj, callback)

  1. var arr = [1, 2, 3];
  2. fis.util.map(arr, function(key, value) {
  3. console.log(key + ' => ' + value);
  4. })
  5. // =>
  6. // 0 => 1
  7. // 1 => 2
  8. // 2 => 3

pad(str, len, fill, pre)

  1. fis.util.pad('aaa', 5, '.');
  2. // => aaa..
  3. fis.util.pad('aaa', 5, '.', true);
  4. // => ..aaa

merge(source, target)

  1. var a = {
  2. key: 'value';
  3. };
  4. var b = {
  5. key1: 'value1'
  6. };
  7. var ab = fis.util.merge(a, b);
  8. // => {key: 'value', key1: 'value1'}

clone(source)

  1. var a = {data: 'string'};
  2. var b = fis.util.clone(a);
  3. assert(a == b, 'a != b');
  4. // => AssertionError: a != b

escapeReg(str)

  1. fis.util.escapeReg('/home/fis/a.js');
  2. // => \\/home\\/fis\\/a\\.js

escapeShellCmd(str)

escapeShellArg(str)

stringQuote(str [, quotes])

  • str String 字符串
  • quotes String 引号
  1. fis.util.stringQuote('"fis"');
  2. // => { origin: '"fis"', rest: 'fis', quote: '"' }

getMimeType(ext)

  • ext String 文件后缀获取对于文件后缀的 MIME
  1. fis.util.getMimeType('png')
  2. // => image/png

realpath(path)

  • path String
  1. //cwd: /home/fis
  2. fis.util.realpath('..');
  3. // => /home

realpathSafe(path)

  • path String 路径安全得获取文件的实际路径,有别于 realpath 的是,其如果文件或者目录不存在返回 false 而此如果不存在返回传入的 path 。如果存在文件或者路径才返回实际路径。
  1. //cwd: /home/fis
  2. fis.util.realpathSafe('../a.js');
  3. ///home/a.js不存在
  4. // => ../a.js

isAbsolute(path)

  • path String 路径判别给定路径是否是绝对路径,是返回 true 不是返回 false
  1. fis.util.isAbsolute('/usr/');
  2. // => true
  3. fis.util.isAbsolute('/usr');
  4. // => false
  5. fis.util.isAbsolute('usr/');
  6. // => false

isFile(path)

  • path String 路径判别给定路径是否是一个文件,如果是返回 true 不是返回 false
  1. console.log(file.util.isFile('path/to/exist/file'));
  2. // => true

isDir(path)

  • path String 路径判别给定路径是否是一个文件夹,如果是返回 true 不是返回 false
  1. console.log(file.util.isDir('/tmp'));
  2. // => true

mtime(path)

  • path String 文件路径获取文件的最后修改时间
  1. fis.util.mtime('/tmp/debug/log.log');
  2. // => Tue Jun 16 2015 15:36:13 GMT+0800 (CST)
  3. var mtime = fis.util.mtime('/tmp/debug/log.log');
  4. console.log(mtime instanceof Date);
  5. // => true

touch(path, mtime)

  • path String 文件路径
  • mtime Date 时间修改文件的最后修改时间,如果 mtime 未指定,使用当前时间;

isWin()

这个函数返回是否是 Windows 系统,如果是返回 true 如果不是返回 false

isTextFile()

这个函数返回一个文件是否是文本文件,是返回 true 不是返回 false。FIS 中文件类型的判别是通过文件后缀做的。相关配置project.fileType.text

isImageFile()

这个函数返回一个文件是否是图片文件,是返回 true 不是返回 false,FIS 中文件类型的判别是通过文件后缀做的。相关配置project.fileType.image

md5(data, len)

  • data String 文件内容
  • len Int 最后获取文件的 md5 长度,默认长度为 7
  1. fis.util.md5('fis'); //不设定len,默认7个。最长32个
  2. // => 37ab815
  3. fis.util.md5('fis', 32);
  4. // => 37ab815c056b5c5f600f6ac93e486a78

base64(data)

mkdir(path, mode)

toEncoding(str, encoding)

  1. fis.util.toEncoding('中文', 'gbk');
  2. // => <Buffer d6 d0 ce c4>

isUtf8(bytes)

readBuffer(buffer)

read(path, convert)

write(path, data, charset, append)

find(rPath, include, exclude)

  1. fis.util.find('/home/fis', /.*\.js/); // all javascript file
  2. // => [...]

del(rPath, include, exclude)

copy(rSource, target, include, exclude)

ext(str)

query(str)

pathinfo(path)

fis.config

fis.config提供了一个比较灵活的设置配置的方式。在fis-conf.js里面进行配置都可以在插件中拿到。

  1. fis.config.set('a.b.c', {e:'0'});
  2. fis.config.get('a');
  3. // => {b:{c:{e:'0'}}}
  4. fis.config.get('a.b');
  5. // => {c:{e:'0'}}
  6. fis.config.get('a.b.c');
  7. // => {e:'0'}

fis.config.merge(obj)

  1. fis.config.merge({
  2. namespace: 'demo'
  3. });

fis.config.set(key, def)

  1. fis.config.set('namespace', 'demo');

fis.config.get(key)

  1. fis.config.get(); //获取全部的配置信息
  2. fis.config.get('namespace') //获取namespace

fis.project

getProjectPath()

获得项目路径

setProjectRoot(rPath)

  • rPath String 目录路径设置项目路径,如果设置的是一个不存在的目录路径,FIS 会自动创建它;

fis.file

fis.file是一个比较主要的类型,每一个文件进入fis处理都会指向一个fis.file对象。可以获取文件的各种信息。比如修改事件、后缀、是否是文本、图片亦或是产出路径等等。

整个 FIS 编译阶段都是以 File 对象为基础进行编译的,所以的文件进入 FIS 编译都会被实例化成一个 File 对象;

wrap(file)

  • file String 文件路径实例化一个file对象
  1. var file = fis.file.wrap('/home/fis/debug/static/demo.js');

File 对象

isHtmlLike

是否是类HTML文件,比如tpl

isJsLike

是否是类JS文件,比如coffeescript

isCssLike

是否是类CSS文件,比如less、sass

requires

文件依赖的id列表

extras

文件额外属性

useMap

是否记录到map.json

isMod

是否需要组件化

exists()

  1. file.exists();
  2. // => true or false

isText()

是否为一文本文件

  1. file.isText();
  2. // => true or false

isImage()

是否为一个图像文件

  1. file.isImage();
  2. // => true or false

toString()

file的真实路径

  1. file.toString();
  2. // => /home/fis/debug/static/demo.js

getMtime()

获取文件最后修改时间

  1. var mtime = file.getMtime();

setContent(c)

  • c String / Buffer 文件内容设置文件内容
  1. file.setContent('content');

getContent()

获取文件内容

  1. var content = file.getContent();

getHash()

获取文件内容hash

  1. var hash = file.getHash();

getBase64(prefix)

获取文件的base64

  1. var base64 = file.getBase64();

getId()

获取文件对应的ID

  1. var id = file.getId();

getUrl(withHash, withDomain)

  • withHash Boolean 文件 Url 是否包含 md5 戳
  • withDomain Boolean 文件 Url 是否包含设置的 domain获取文件的url
  1. var url = file.getUrl(true, true);

addRequire(id)

  • id String 文件 id,用 getId() 获得给文件添加依赖
  1. file.addRequire('a.js');
  2. // demo.js
  3. //依赖与a.js

removeRequire(id)

  • id String 文件 id,用 getId() 获得移除文件对某个其他文件的依赖
  1. file.removeRequire('a.js');
  2. // 移除对a.js的依赖

fis.compile

编译一个文件,注意文件的缓存控制;

注意,它是一个函数,而非对象

  1. var path = require('path');
  2. var file = fis.file.wrap(path.join(fis.project.getProjectPath(), 'a.js'));
  3. file.useCache = false; // @NOTICE
  4. fis.compile(file);
  5. console.log(file.getContent());

fis.log

打印log,适合调试报错等

debug(str)

  • str String 要输出的调试信息输出一些调试信息,当执行 release 时,后面带命令行参数 —verbose 输出这些调试信息;
  1. fis release --verbose
  1. fis.log.debug('debugMessage');
  2. // [DEBUG] 18:49:46.0958 debugMessage

notice(str)

  • str String 一些提示信息输出一些提示信息,调用了此方法会直接输出提示,不同于 fis.debug()
  1. fis.log.notice('noticeMessage');
  2. // [NOTICE] 18:49:46.0958 noticeMessage

warning(str)

  • str String 一些警告信息输出一些警告信息,调用了就会输出,不同于 fis.debug()
  1. fis.log.warning('warningMessage');
  2. // [WARNING] 18:49:46.0958 warningMessage

error(err)

  • err String / Error 错误信息输出错误信息接口,当 release 添加命令行参数 —verbose 会打出所有的错误堆栈信息。

调用此接口并被触发后,编译会中断,因为 Error 是一个不可挽回的错误。

  1. fis release --verbose
  1. fis.log.error('errorMessage');
  2. // [ERROR] 18:49:46.0958 errorMessage
  3. // 编译中断
有任何问题,请在 https://github.com/fex-team/fis/issues 讨论