Vinyl

一种虚拟文件格式。当 src() 读取文件时，会生成一个 Vinyl 对象来表示该文件 - 包括路径、内容和其他元数据。

¥A virtual file format. When a file is read by src(), a Vinyl object is generated to represent the file - including the path, contents, and other metadata.

Vinyl 对象可以使用 plugins 应用变换。它们也可以使用 dest() 持久保存到文件系统中。

¥Vinyl objects can have transformations applied using plugins. They may also be persisted to the file system using dest().

创建自己的 Vinyl 对象时 - 而不是用 src() 生成 - 使用外部 vinyl 模块，如下使用所示。

¥When creating your own Vinyl objects - instead of generating with src() - use the external vinyl module, as shown in Usage below.

用法

¥Usage

const Vinyl = require('vinyl');

const file = new Vinyl({

cwd: '/',

base: '/test/',

path: '/test/file.js',

contents: new Buffer('var x = 123')

});

file.relative === 'file.js';

file.dirname === '/test';

file.dirname = '/specs';

file.path === '/specs/file.js';

file.basename === 'file.js';

file.basename = 'file.txt';

file.path === '/specs/file.txt';

file.stem === 'file';

file.stem = 'foo';

file.path === '/specs/foo.txt';

file.extname === '.txt';

file.extname = '.js';

file.path === '/specs/foo.js';

签名

¥Signature

new Vinyl([options])

参数

¥Parameters

参数	type	note
options	object	详细见下文 选项。

返回

¥Returns

代表单个虚拟文件的 Vinyl 类的实例，在下面的 Vinyl 实例 中详细介绍。

¥An instance of the Vinyl class representing a single virtual file, detailed in Vinyl instance below.

错误

¥Errors

当任何传递的选项不符合表中定义的 实例属性定义（例如 path 设置为数字）时，将抛出异常。

¥When any passed options don't conform to the instance property definitions (like if path is set to a number) throws as defined in the table.

选项

¥Options

name	type	default	note
cwd	string	process.cwd()	将派生相对路径的目录。将是 normalized 并删除尾随分隔符。
base	string		用于计算 relative 实例属性。如果未设置，则回退到 cwd 的值。通常设置为 通配符基础。将是 normalized 并删除尾随分隔符。
path	string		完整的绝对文件路径。将是 normalized 并删除尾随分隔符。
history	array	[ ]	用于预填充 Vinyl 实例的 history 的路径数组。通常来自于从先前的 Vinyl 对象派生出新的 Vinyl 对象。如果 path 和 history 都通过，则 path 附加到 history 后面。每个项目都是 normalized 并且删除了尾随分隔符。
stat	object		fs.Stats 的实例，通常是对文件调用 fs.stat() 的结果。用于确定 Vinyl 对象是否表示目录或符号链接。
contents	ReadableStream 缓冲区 null	null	文件的内容。如果 contents 是 ReadableStream，则它被封装在 cloneable-readable 流中。

options 上的任何其他属性都将直接分配给 Vinyl 实例。

¥Any other properties on options will be directly assigned to the Vinyl instance.

const Vinyl = require('vinyl');

const file = new Vinyl({ foo: 'bar' });

file.foo === 'bar';

Vinyl 实例

¥Vinyl instance

Vinyl 对象的每个实例都将具有用于访问和/或修改有关虚拟文件的信息的属性和方法。

¥Each instance of a Vinyl object will have properties and methods to access and/or modify information about the virtual file.

实例属性

¥Instance properties

所有内部管理路径 - 除 contents 和 stat 之外的任何实例属性 - 已标准化并删除了尾随分隔符。请参阅 标准化和串联 了解更多信息。

¥All internally managed paths - any instance property except contents and stat - are normalized and have trailing separators removed. See Normalization and concatenation for more information.

property	type	description	throws
contents	ReadableStream 缓冲区 null	获取和设置虚拟文件的内容。如果设置为 ReadableStream，它将封装在 cloneable-readable 流中。	如果设置为 ReadableStream、Buffer 或 null 以外的任何值。
stat	object	获取和设置 fs.Stats 的实例。在确定 Vinyl 对象是否表示目录或符号链接时使用。
cwd	string	获取和设置当前工作目录。用于导出相对路径。	如果设置为空字符串或任何非字符串值。
base	string	获取和设置基本目录。用于计算 relative 实例属性。在由 src() 生成的 Vinyl 对象上，将设置为 通配符基础。如果设置为 null 或 undefined，则回退到 cwd 实例属性的值。	如果设置为空字符串或任何非字符串值（null 或 undefined 除外）。
path	string	获取和设置完整的绝对文件路径。设置为与当前 path 不同的值会将新路径附加到 history 实例属性。	如果设置为任何非字符串值。
history	array	Vinyl 对象已分配的所有 path 值的数组。第一个元素是原始路径，最后一个元素是当前路径。该属性及其元素应被视为只读，并且只能通过设置 path 实例属性来间接更改。
relative	string	获取 base 和 path 实例属性之间的相对路径段。	如果设置为任意值。如果在 path 不可用时访问。
dirname	string	获取和设置 path 实例属性的目录。	如果在 path 不可用时访问。
stem	string	获取和设置 path 实例属性的主干（不带扩展名的文件名）。	如果在 path 不可用时访问。
extname	string	获取和设置 path 实例属性的扩展名。	如果在 path 不可用时访问。
basename	string	获取和设置 path 实例属性的文件名 (stem + extname)。	如果在 path 不可用时访问。
symlink	string	获取和设置符号链接的引用路径。	如果设置为任何非字符串值。

实例方法

¥Instance methods

method	返回类型	returns
isBuffer()	boolean	如果 contents 实例属性是 Buffer，则返回 true。
isStream()	boolean	如果 contents 实例属性是 Stream，则返回 true。
isNull()	boolean	如果 contents 实例属性为 null，则返回 true。
isDirectory()	boolean	如果实例代表一个目录，则返回 true。当 isNull() 返回 true、stat 实例属性是对象且 stat.isDirectory() 返回 true 时，实例被视为目录。这假设 Vinyl 对象是用有效的（或正确模拟的）fs.Stats 对象构造的。
isSymbolic()	boolean	如果实例表示符号链接，则返回 true。当 isNull() 返回 true、stat 实例属性是对象且 stat.isSymbolicLink() 返回 true 时，实例被视为符号。这假设 Vinyl 对象是用有效的（或正确模拟的）fs.Stats 对象构造的。
clone([options])	object	克隆了所有属性的新 Vinyl 对象。默认情况下，自定义属性是深度克隆的。如果 deep 选项为 false，自定义属性将进行浅克隆。如果 contents 选项为 false 并且 contents 实例属性是 Buffer，则该 Buffer 将被重用而不是克隆。
inspect()	string	返回 Vinyl 对象的格式化解释。由 Node 的 console.log 自动调用。

标准化和串联

¥Normalization and concatenation

所有路径属性均由其设置器标准化。使用 / 连接路径，而不是使用 path.join()，并且规范化将在所有平台上正确发生。切勿与 \ 连接 - 它是 POSIX 系统上的有效文件名字符。

¥All path properties are normalized by their setters. Concatenate paths with /, instead of using path.join(), and normalization will occur properly on all platforms. Never concatenate with \ - it is a valid filename character on POSIX system.

const file = new File();

file.path = '/' + 'test' + '/' + 'foo.bar';

console.log(file.path);

// posix => /test/foo.bar

// win32 => \\test\\foo.bar