Browsersync API 中文文档

Browsersync 的 API 是难以置信的简单并且强大。你可以用它来创建你自己的微型 node 程序以辅助本地开发或者集成到其他工具中。使用 Browsersync 时，就像任何其他 node 模块一样，只需 require Browsersync 模块。然后你就可以调用下面所列出的 API 了。

2.0.0 版本之前的用法
以前的版本中，我们允许直接调用模块导出（export）的方法，如下：

// 像往常一样 require 此模块
var browserSync = require("browser-sync");

// 启动服务器
browserSync({server: "./app"});

// 调用方法，例如 reload
browserSync.reload("core.css");

2.0.0 版本之后的用法（推荐）
虽然上述方法仍然被支持，但现在我们推荐以下方式。调用 .create() 意味着你得到了一个唯一的引用（reference）并允许你创建多个服务器或代理。

// 像往常一样 require 此模块
var bs = require("browser-sync").create();

// .init 方法启动服务器
bs.init({
    server: "./app"
});

// 调用 bs 上的方法。注意不再是
// browserSync 模块导出（export）的方法了
bs.reload("*.html");

.create( name ) ^ TOP

创建 Browsersync 实例

name
类型： String
一个以后可用于检索的标识符

// create an unnamed instance
var bs = require("browser-sync").create();

// create a named instance
var bs = require("browser-sync").create('My server');


// create multiple
var bs1 = require("browser-sync").create('Server 1');
var bs2 = require("browser-sync").create('Server 2');

.get( name ) ^ TOP

按 name 获取单个实例。如果你的构建脚本位于独立的文件中，那么这将很有用

name
类型： String

// Create an named instance in one file...
var bs = require("browser-sync").create('My Server');

// Start the Browsersync server
bs.init({
    server: true
});

// now, retrieve the instance in another file...
var bs = require("browser-sync").get('My server');

// and call any methods on it.
bs.watch('*.html').on('change', bs.reload);

.has( name ) ^ TOP

检查是否已创建实例。

name
类型： String

.init( config, cb ) ^ TOP

启动 Browsersync 服务。这将启动一个服务器、代理或启动 snippet 模式，具体取决于您的用例。

config
类型： Object [可选]
这是 Browsersync 实例的主要配置，可以包含任何可用参数如果不传递配置参数，Browsersync 仍将运行，但是它将处于 snippet 模式

cb
类型： Function [可选]
如果传递的是回调函数，则当 Browsersync 完成所有任务并准备好可以使用时，回调函数将被调用。当你需要等待信息（例如：url、端口等）或同步执行其他任务时，这将非常有用。

var bs = require("browser-sync").create();

// Start a Browsersync static file server
bs.init({
    server: "./app"
});

// Start a Browsersync proxy
bs.init({
    proxy: "http://www.bbc.co.uk"
});

.reload( arg ) ^ TOP

The reload 方法将修改过的文件告知所有浏览器，并让浏览器刷新或在可能的情况下注入文件。

arg
类型： String | Array | Object [可选]
需要重新加载的一个或多个文件。

// browser reload
bs.reload();

// single file
bs.reload("styles.css");

// multiple files
bs.reload(["styles.css", "ie.css"]);

// Since 2.6.0 - wildcards to reload ALL css files
bs.reload("*.css");

.stream( opts ) ^ TOP

stream 方法返回一个转换流（transform stream）并且可以对一个或多个文件执行操作。

opts
类型： Object [可选]
针对 stream 方法的配置

注意： 支持的最低版本为 2.6.0

// Compile SASS & auto-inject into browsers
gulp.task('sass', function () {
    return gulp.src('scss/styles.scss')
        .pipe(sass({includePaths: ['scss']}))
        .pipe(gulp.dest('css'))
        .pipe(bs.stream());
});

// Provide `once: true` to restrict reloading to once per stream
gulp.task('templates', function () {
    return gulp.src('*.jade')
        .pipe(jade())
        .pipe(gulp.dest('app'))
        .pipe(bs.stream({once: true}));
});

// Provide a filter to stop unwanted files from being reloaded
gulp.task('less', function () {
    return gulp.src('*.less')
        .pipe(less())
        .pipe(gulp.dest('css'))
        .pipe(bs.stream({match: "**/*.css"}));
});

.notify( msg, timeout ) ^ TOP

浏览器通知的辅助方法

msg
类型： String | HTML
可以是一条简单的消息，例如 'Connected' 或 HTML

timeout
类型： Number [可选]
消息在浏览器中保留多长时间。 @从 1.3.0 版本开始支持

var bs = require("browser-sync").create();

// Text message
bs.notify("Compiling, please wait!");

// HTML message
bs.notify("HTML <span color='green'>is supported</span> too!");

// Since 1.3.0, specify a timeout
bs.notify("This message will only last a second", 1000);

.exit() ^ TOP

此方法将关闭任何正在运行的服务器，停止文件监视并退出当前进程。

var bs = require("browser-sync").create();

// Start the server
bs.init({server: "./app"});

// Quit the server after 5 seconds
setTimeout(function () {
    bs.exit();
}, 5000);

.watch( patterns, opts, fn ) ^ TOP

独立的文件监视程序。将其与 Browsersync 一起使用可以创建一个你属于自己的最小的构建系统

patterns
类型： String
需要监视的文件的 glob 通配符

opts
类型： Object [可选]
Options to be passed to传递给 Chokidar 的参数 - 检查他们的文档中可用的内容

fn
类型： Function [可选]
每个事件的回调函数

注意： 支持的最低版本为 2.6.0

// Create a Browsersync instance
var bs = require("browser-sync").create();

// Listen to change events on HTML and reload
bs.watch("*.html").on("change", bs.reload);

// Provide a callback to capture ALL events to CSS
// files - then filter for 'change' and reload all
// css files on the page.
bs.watch("css/*.css", function (event, file) {
    if (event === "change") {
        bs.reload("*.css");
    }
});

// Now init the Browsersync server
bs.init({
    server: "./app"
});

var bs = require("browser-sync").create();

// Listen for the `init` event
bs.emitter.on("init", function () {
    console.log("Browsersync is running!");
});

bs.init(config);

.active ^ TOP

一个简单的 true/false 标志，可用于确定当前是否有正在运行的 Browsersync 实例。

var bs = require("browser-sync").create();

// -> false as .init has not yet been called
console.log(bs.active);

bs.init(config, function (err, bs) {

    // -> now true since BS is running now
    console.log(bs.active);
});

.paused ^ TOP

一个简单的用于判断当前实例是否暂停的 true/false 标志

.sockets ^ TOP

用于访问客户端的 socket，用来发送事件

Jump to...

.create( name )
.get( name )
.has( name )
.init( config, cb )
.reload( arg )
.stream( opts )
.notify( msg, timeout )
.exit()
.watch( patterns, opts, fn )
.pause()
.resume()
.emitter
.active
.paused
.sockets