文件系统

导入

通过如下方式导入文件系统api

import fs from "svr-api/fs";

方法

/**
 * 文件系统相关API
 */

declare class File {
	/**根据路径创建文件对象 */
	// constructor(path: string);

	/** 获取文件或目录的完整路径 */
	getPath(): string;

	/** 获取文件或目录名称 */
	getName(): string;

	/** 获取文件或目录不包含扩展名的主名称， 例如： “d:\word\文档1.doc”将返回“文档1” */
	getBaseName(): string;

	/** 获取文件扩展名 */
	getExtension(): string;

	/** 获取文件父目录 */
	getParent(): string;

	/** 获取文件的父目录的文件对象 */
	getParentFile(): File;

	/**
	 * 获取指定路径的文件对象。
	 * 
	 * @param subpath  文件路径，可以为文件的绝对路径或相对路径。
	 * @param errorIfNotExists 可选，文件不存在时是否抛出异常，默认为false。
	 * @return 
	 */
	getFile(subpath: string, errorIfNotExists?: boolean): File

	/** 判断文件是否是一个目录,只有文件存在且是一个目录时才返回true */
	isDir(): boolean;

	/** 判断文件是否是一个文件，只有文件存在且不是一个目录时才返回true */
	isFile(): boolean;

	/** 判断文件或目录是否已存在 */
	exists(): boolean;

	/** 该文件是否能被修改 */
	canWrite(): boolean;

	/** 该文件是否能被本Web应用程序读取 */
	canRead(): boolean;

	/**
	 * 获取文件的大小。
	 * 
	 * @return 单位为byte(如46080，表示45k)，若文件不存在、为目录则返回0。
	 */
	length(): number;

	/**
	 * 文件最后一次被修改的时间。
	 * 
	 * @return 文件不存在、获取时间时发生错误，则返回null。
	 */
	lastModifiedTime(): Date;

	/**
	 * 拷贝other文件的内容到本文件。
	 * 
	 * 注意：如果本文件不存在，会自动创建。
	 * 
	 * @param other 要复制的文件，可以传入文件或者文件的完整路径。
	 */

	copy(other: File | string): void;

	/**
	 * 从文件中读取所有字节返回一个字符数组。
	 * 
	 * @return 空文件返回空数组，文件不存在、为目录时抛异常。
	 */
	readBytes(): number[];

	/**
	 * 写入一个byte数组到文件中。
	 *
	 * 若文件不存在则创建新文件，否则覆盖现有文件。
	 *
	 * @param bytes 为null、空数组时将清空文件。
	 */
	writeBytes(bytes: number[]): void;

	/**
	 * 读取文件内容并以字符串形式返回。
	 *
	 * @param encoding 可选，文件内容编码，默认编码UTF-8。
	 * @return 空文件返回空字符串，为目录、文件不存在抛异常。
	 */
	readString(encoding?: string): string;

	/**
	 * 写入一个字符串到文件中。
	 * 
	 * 若文件不存在则创建新文件，否则覆盖现有文件。
	 * 
	 * @param content 为null、空字符串时将清空文件。
	 * @param encoding 可选，文件内容编码，默认编码UTF-8。
	 */
	writeString(content: string, encoding?: string): void

	/**
	 * 文件读取出来时用base64编码返回，一般用于返回二进制文件的base64编码形式。
	 * 
	 * @return 空文件返回空字符串，文件不存在、为目录时抛异常。
	 */
	readBase64(): string;

	/**
	 * 将base64编码的内容解码后写入文件，一般用于写二进制文件。
	 * 
	 * 若文件不存在则创建新文件，否则覆盖现有文件。
	 * 
	 * @param base64 为null、空字符串时将清空文件内容。
	 */
	writeBase64(base64: string): void;

	/**
	 * 读取一个名値对文件，返回一个JSON对象。
	 * 
	 * @param encoding 可选，文件内容编码，默认编码UTF-8。
	 * @return 找不到名値对则返回一个空JSON对象，文件不存在则抛出异常。
	 */
	readJson(encoding?: string): JSONObject;

	/**
	 * 将json数据写入文件。
	 * 
	 * 若文件不存在则创建新文件，否则覆盖现有文件。
	 * 
	 * @param data 为null、空json时将清空文件内容。
	 * @param encoding 可选，文件内容编码，默认编码UTF-8。
	 * @param pretty 可选，是否格式化，默认false。
	 */
	writeJson(data: any, encoding?: string, pretty?: boolean): void;

	/**
	 * 从文件中读取所有行。
	 * 
	 * @param encoding 可选，文件内容编码，默认编码UTF-8。
	 * @return 空文件返回空数组，文件不存在、为目录时抛异常。
	 */
	readLines(encoding?: string): string[];

	/**
	 * 将文本行写入文件。 
	 * 
	 * 若文件不存在则创建新文件，否则覆盖现有文件。
	 * 
	 * @param data 为null、空数组时将清空文件内容。
	 * @param encoding 可选，文件内容编码，默认编码UTF-8。
	 */
	writeLines(data: string[], encoding?: string): void;

	/**
	 * 读取文件内容并转换为一个dom4j的Document对象。
	 * 
	 * @param encoding 可选，文件内容编码，默认编码UTF-8。
	 * @param stripWhitespaceText 可选，是否移除xml中的一些节点之间的空白文本，这些文本内容默认也是Node节点，默认false。
	 * @return 空文件、为目录、文件不存在抛异常。
	 */
	readXML(encoding?: string, stripWhitespaceText?: boolean): Dom4j.Document;

	/**
	 * 将Document对象写到文件中。
	 * 
	 * 若文件不存在则创建新文件，否则覆盖现有文件。
	 * 
	 * @param doc 为null、空Document对象时将清空文件内容。
	 * @param encoding 可选，默认将使用Document内的的encoding设置，默认编码UTF-8。如果传递了明确的编
	 * 码，但是编码和Document中的不一致，那么文件内容编码依然使用传递的编码，会和xml内容中记录的不一致。
	 * @param pretty 可选，是否格式化，默认false，传递true时默认使用tab缩进。
	 * @param declaration 可选，默认true，可以传递：
	 * 	1. true 输出默认的xml头，如：<?xml version=\"1.0\" encoding=\"UTF-8\"?>，其中的编码会替换为指定的编码。
	 * 	2. false 不输出xml头。
	 * 	3. 其他字符串，输出指定的头。
	 */
	writeXML(doc: Dom4j.Document, encoding?: string
		, pretty?: boolean, declaration?: boolean | string): void;

	/**
	 * 读取一个CSV文件，返回字符串二维数组。
	 * 
	 * @param encoding 可选，文件内容编码，默认编码UTF-8。
	 * @param separator 可选，分隔符，此参数传null或空字符串时默认为英文逗号。
	 * @return 文件为null返回空数组。文件不存在、为目录时抛异常。
	 */
	readCSV(encoding?: string, separator?: string): string[][];

	/**
	 * 写入一个CSV文件。
	 * 
	 * 若文件不存在则创建新文件，否则覆盖现有文件。
	 * 
	 * @param data 为null、空二维数组时将清空文件内容。
	 * @param encoding 可选，文件内容编码，默认编码UTF-8。
	 * @param separator 可选，分隔符，此参数传null或空字符串时默认为英文逗号。
	 */
	writeCSV(data: any[][], encoding?: string, separator?: string): void;

	/**
	 * 写入任意一个对象到文件，支持字符串、流、bytes[]、json对象等。
	 * 
	 * @param o null时什么也不写入。
	 * @param encoding 可选，对于需要编码的内容实用，默认编码UTF-8。
	 */
	write(o: any, encoding?: string): void;

	/**
	 * 删除目录或文件。
	 * 
	 * 注意：目录为空才能被删除。
	 * 
	 * @return 操作是否成功。
	 */
	delete(): boolean;

	/**
	 * 清空目录。
	 * 
	 * 注意：不是目录，则不进行任何操作，并返回true。
	 * 
	 * @return 操作是否成功。
	 */
	cleanDir(): boolean;

	/**
	 * 创建目录。包括目录的任何父目录。
	 * 
	 * 注意：如果此操作失败，父目录可能已经被创建。
	 * 
	 * @return 目录不存在且创建成功后返回true，目录之前已经存在则返回false。
	 */
	mkdirs(): boolean;

	/**
	 * 确保当前文件对象代表的文件或目录是存在的。
	 * 
	 * 如果文件或目录存在则不做任何处理；如果不存在，则创建一个空文件，如果父目录不存在，会先创建父目录。
	 */
	touch(): void
	/**
	 * 按指定的扩展名列表列出目录下的文件，不会列出子目录，可指定是否查询子目录下面的文件。
	 * 
	 * @param extensions 可选，扩展名过滤，比如“txt,jpg”，如果传入null或空字符串，则列出所有类型的文件。
	 * @param recursive 可选，是否递归查询子目录。
	 * @return 不是目录、没有符合条件的文件、空目录返回空数组。
	 */
	listFiles(extensions?: string, recursive?: boolean): File[];

	/**
	 * 查找满足匹配模式的文件，如：
	 *
	 * 1. `findFiles("path/to/**\/*.csv")`  可以递归获取`path/to`目录下的所有csv文件。
	 * 2. `findFiles("path/to/**\/aaa.csv")`  可以递归搜索`path/to`目录下的名称为`aaa.csv`的文件。
	 * 3. `findFiles("path/to/*\/aaa.csv")`  可以搜索`path/to`目录的下一级目录（不递归）中的名称为
	 *    `aaa.csv`的文件。
	 *
	 * @see https://stackoverflow.com/questions/2952196/ant-path-style-patterns
	 * @param pathPattern 匹配模式，通常不以/开头，相对于当前目录。
	 * @returns 返回文件信息数组，如果找不到，返回空数组。
	 */
	findFiles(pathPattern: string): File[];

	/**
	 * 列出所有直接子目录。
	 * 
	 * @return 目录不存在、不是目录、空目录返回空数组。
	 */
	listDirs(): File[];

	/**
	 * 获取文件的带缓冲的输入流，调用者使用完这个流之后，必须自行关闭流。
	 * 
	 * @return 文件不存在、为目录抛异常。
	 */
	openInputStream(): InputStream;

	/**
	 * 获取文件的带缓冲的输出流，调用者使用完这个流之后，必须自行关闭流。
	 * 
	 * 父目录不存在则创建父目录。
	 * 
	 * @return 文件不存在、为目录抛异常。
	 */
	openOutputStream(): OutputStream;

	/**
	 * 获取文件的压缩输入流，调用者使用完这个流之后，必须自行关闭流。
	 * 
	 * @return 文件不存在、为目录抛异常。
	 */
	openGzipInputStream(): InputStream;

	/**
	 * 获取文件的压缩输出流，调用者使用完这个流之后，必须自行关闭流。
	 * 
	 * 父目录不存在则创建父目录。
	 * 
	 * @return 文件不存在、为目录抛异常。
	 */
	openGzipOutputStream(): OutputStream;

	/**
	 * 获取文件的带缓冲的字符输入流，调用者使用完这个流之后，必须自行关闭流。
	 * 
	 * @return 文件不存在、为目录时抛异常。
	 */
	openReader(): Reader;

	/**
	 * 获取文件的带缓冲的字符输出流对象，调用者使用完这个流之后，必须自行关闭。
	 * 
	 * 父目录不存在则创建父目录。
	 * 
	 * @return 文件不存在、为目录时抛异常。
	 */
	openWriter(): Writer;

	/**
	 * 获取文件的csvReader。
	 * 
	 * 使用后需要主动关闭，调用 {@link CSVReader.close}。
	 * 
	 * @param encoding 默认utf-8
	 * @param separator 默认逗号
	 */
	openCSVReader(encoding?: string, separator?: string): CSVReader;

	/**
	 * 获取文件的csvWriter。
	 * 
	 * 使用后需要主动关闭，调用 {@link CSVWriter.close}。
	 * 
	 * @param encoding 
	 * @param separator 
	 */
	openCSVWriter(encoding?: string, separator?: string): CSVWriter;

	/**
	 * 转换为一个文件数据源，用于批量读写自定义格式文件中的数据。
	 *
	 * 系统支持一些常见的格式，如csv、dbf、xlsx，其他自定义的格式需要扩展支持，见
	 * {@link ExtendPoint.dataFile} 扩展点。
	 *
	 * @param format 文件类型，可以传入和文件后缀名不一样的格式，例如可以把一个txt文件当作csv来读，
	 *        或者使用扩展的csv读取方式来读取一个非标准的csv。
	 * @param options 文件选项，可能设置的属性见{@link BulkDataOption}。
	 * @returns 没有对应文件类型的扩展则返回`null`，返回的对象已调用了{@link BulkDataReader.open}方
	 *        法。
	 */
	toDataFile(format?: string, options?: BulkDataOptions): BulkDataSource;
}

/**
 * 创建一个临时文件。
 *
 * 调用者还是应该尽量在不使用此文件后及时删除它，但调用者也可以不必担心在极少数情况下此文件不会被删
 * 除，因为内部有机制会在系统初始化或关闭时对所有生成的临时文件进行处理。
 *
 * 注意：这个临时文件没有被直接创建，仅构建了一个File 对象，在磁盘上是不存在的，请根据需求自己创建。
 * 
 * @param suffix 可选，后缀名，会自动带上点号拼接到文件名后面，文件名最终为：随机字符串 + suffix。
 * @returns 临时文件，在磁盘上还不存在，但其父目录是确定存在的。
 */
export function createTempFile(suffix?: string): File;

/**
 * 创建一个临时目录。
 *
 * 调用者还是应该尽量在不使用此文件后及时删除它，但调用者也可以不必担心在极少数情况下此文件不会被删
 * 除，因为内部有机制会在系统初始化或关闭时对所有生成的临时文件进行处理。
 *
 * 注意：这个临时目录已经被直接创建了，是存在的。
 *
 * @param suffix 可选，后缀名，会自动带上点号拼接到文件名后面，文件名最终为：随机字符串 + suffix。
 * @returns 临时目录，在磁盘上已经被直接创建了，是存在的。
 */
export function createTempDir(suffix?: string): File;

/**
 * 获得web目录下的某个文件。
 * 
 * @param path 要获取的文件，/开头，如`/dist/commons/images/avatar.png`。
 * @returns 文件不存在时抛异常。
 */
export function getWebResource(path: string): File;

/**
 * 获得classpath下的某个文件。
 * 
 * @param path 要获取的文件，/开头，如`/com/succez/dev/script/lib/fs/JSScriptModuleImpl_fs.class`。
 * @returns 文件不存在时抛异常。
 */
export function getClassPathResource(path: string): File;

/**
 * 获取指定路径的文件（包括目录）对象。
 *
 * @param path  文件路径，为文件的绝对路径。
 * @param errorIfNotExists 可选，文件不存在时是否抛出异常，默认为false。
 * @returns 
 */
export function getFile(path: string, errorIfNotExists?: boolean): File;

/**
 * 查找满足匹配模式的文件，如：
 *
 * 1. `findFiles("/path/to/**\/*.csv")`  可以递归获取`/path/to`目录下的所有csv文件。
 * 2. `findFiles("/path/to/**\/aaa.csv")`  可以递归搜索`/path/to`目录下的名称为`aaa.csv`的文件。
 * 3. `findFiles("/path/to/*\/aaa.csv")`  可以搜索`/path/to`目录的下一级目录（不递归）中的名称为
 *    `aaa.csv`的文件。
 *
 * @see https://stackoverflow.com/questions/2952196/ant-path-style-patterns
 * @param pathPattern 匹配模式，/开头。
 * @returns 返回文件信息数组，如果找不到，返回空数组。
 */
export function findFiles(pathPattern: string): File[];

/**
 * 获取指定路径的目录对象。
 *
 * @param path  目录的绝对路径。
 * @param errorIfNotExists 可选，不存在或者存在但不是目录时是否抛出异常，默认为false。
 * @returns 
 */
export function getDir(path: string, errorIfNotExists?: boolean): File;

/**
 * 根据抽象路径名创建指定目录，包括任何必要但不存在的父目录，创建不成功抛出异常。
 * 
 * 注意：如果此操作失败，父目录可能已经被创建。
 * 
 * @param path 创建目录的抽象路径名。
 */
export function mkdirs(path: string): File;

/**
 * 删除文件或目录，如果是目录则会删除目录下所有内容。
 * 
 * 注意：不是目录，则不进行任何操作。
 * 
 * @param path 删除文件或目录的路径。
 */
export function deleteFile(path: string): void

/**
 * 返回文件路径to相对于父路径from的相对路径。
 * 
 * @example
 *	1. `relativePath('/data/orandea/test/aaa', '/data/orandea/impl/bbb')='../../impl/bbb'`。
 * @param from 当前路径，应该是一个绝对路径。
 * @param to 目标路径，应该是一个绝对路径。
 * @returns 如果from和to相同，则返回一个零长度的空字符串。
 */
export function relativePath(from: string, to: string): string

/**
 * 将一系列路径转换为解析为绝对路径。
 * 
 * @example
 *	1. `resolvePath('/foo/bar', './baz')='/foo/bar/baz'`。
 *	2. `resolvePath('/foo/bar', '/tmp/file/')='/tmp/file/'`。
 *	3. `resolvePath('/wwwroot', 'static_files/png/', '../gif/image.gif')='/wwwroot/static_files/gif/image.gif'`。
 * @param paths
 * @returns 
 */
export function resolvePath(...paths: string[]): string

/**
 * 获取文件或目录的主名称，不包括扩展名。
 * 
 * @example
 *	1. `getBaseName("d:\word\文档1.doc") = "文档1"`。
 *	2. `getBaseName("d:\word\dir1") = "dir1"`。
 * @param path 文件的完整路径。
 * @return
 */
export function getBaseName(path: string): string;

/**
 * 获取文件或目录的所在的父目录的路径。
 * 
 * @example
 *	1. `getDirName("/path/to/文档1.doc") = "/path/to"`。
 *	2. `getDirName("/path/to/dir1") = "/path/to"`。
 * @param path 文件的完整路径。
 * @return
 */
export function getDirName(path: string): string;

/**
 * 获取文件或目录的名称，含扩展名。
 * 
 * @example
 *	1. `getBaseName("d:\word\文档1.doc") = "文档1.doc"`。
 *	2. `getBaseName("d:\word\dir1") = "dir1"`。
 * @param path 文件的完整路径。
 * @return
 */
export function getName(path: string): string;

/**
 * 获取文件扩展名，是一个字符串，没有点号作为前缀，如果是目录或没有扩展名的文件则返回空字符串。
 * 
 * @example
 *	1. `getExtension("d:\word\文档1.doc") = "doc"`。
 *	2. `getExtension("d:\word\dir1") = ""`。
 * @param path 文件的完整路径。
 * @return
 */
export function getExtension(path: string): string;

/**
 * 此方法将路径规范化为标准格式。
 * 
 * @example
 * 	1. /foo//                    /foo/
 * 	2. /foo/./                   /foo
 * 	3. /foo/../bar               /bar
 * 	4. /foo/../bar/              /bar/
 * 	5. /foo/../bar/../baz        /baz
 * 	6. //foo//./bar              /foo/bar
 * 	7. //foo//./bar     false    \\foo\\bar
 * 	8. /../                      null
 * 	9. ../foo                    null
 * 	10. foo/bar/..                foo
 * 	11. foo/../../bar             null
 * 	12. foo/../bar                bar
 * 	13. //server/foo/../bar       //server/bar
 * 	14. //server/../bar           null
 * 	15. C:\foo\..\bar    false    C:\bar
 * 	16. C:\..\bar                 null
 * 	17. ~/foo/../bar/             ~/bar/
 * 	18. ~/../bar                  null
 * @param filename 输入可包含Unix或Windows格式的分隔符。
 * @param unixSeparator 可选，默认为true，为true时是unix分隔符"/"，为false时是windows分隔符"\\"。
 * @return 输出包含指定格式的分隔符的规范化结果。
 */
export function normalize(filename: string, unixSeparator?: boolean): string;

/**
 * 解压rar文件，并输出到指定目录下，说明：
 *
 * 1. 要使用unrar，先确保电脑的环境变量的path路径下包含rar相关命令，请参考
 *    <https://docs.succbi.com/devops/install/unrar/>下载unrar命令。
 * 2. 解压后的输出目录若存在则覆盖，不存在则默认解压到临时目录下。
 *
 * @param rarfile rar文件。
 * @param targetDir 可选，解压后的指定目录，不传递则默认解压到临时目录下。
 * @returns 返回目标解压目录，如果传递了targetDir那么就是它了。
 */
export function unrar(rarfile: File, targetDir?: File): File;

/**
 * 压缩文件或者目录为一个zip文件。
 * 
 * 如果源文件只有一个且是一个目录，则只会压缩其下级文件或目录到zip包中。
 *
 * @param srcFiles 要压缩的文件或目录。
 * @param zipFile 目标zip文件，如果不存在，则会创建，如果不传递，则创建一个临时文件。
 * @param encoding 文件名使用的编码，默认使用`UTF-8`
 * @returns 返回zip文件。
 */
export function zip(srcFiles: File | File[], zipFile?: File | string, encoding?: string): File;

/**
 * 解压缩一个zip文件。
 *
 * 如果targetFile是一个目录，那么存放到目录内，如果targetFile并不存在则根据zip文件的内容决定创建目录
 * 还是文件，如果zip内只有一个文件，那么直接将文件也压缩到targetFile，如果有多个，那么创建目录并解压
 * 缩到目录。
 *
 * @param zipFile 要解压缩的zip文件。
 * @param targetFile 解压缩后存放的位置，如果不传递，则创建一个临时文件。
 * @param encoding 文件名使用的编码，默认会兼容的先使用`GB18030`尝试编码，如果有乱码，再转换为使用`UTF-8`
 * @param entry 传递后将只解压缩指定的entry
 */
export function unzip(zipFile: File | string, targetFile?: File | string, encoding?: string, entry?: string): File;

/**
 * 创建一个新的zip文件，通过返回的对象可以写入zip文件内部结构和文件内容。
 * 
 * 返回的是`com.succez.commons.util.zip.ZipArchive`对象，调用者需要自己关闭返回的对象。
 * 
 * @param zipFile 已存在的zip文件
 * @param encoding 默认utf8
 */
export function createZipArchive(zipFile?: File | string, encoding?: string): any;

/**
 * 打开一个zip文件，通过返回的对象可以读取zip文件内部结构和文件内容。
 * 
 * 返回的是`org.apache.commons.compress.archivers.zip.ZipFile`对象，调用者需要自己关闭返回的对象。
 * 
 * @param zipFile 已存在的zip文件
 * @param encoding 默认utf8
 */
export function openZipFile(zipFile?: File | string, encoding?: string): any;

/**返回的是`com.succez.commons.util.io.CSVReader`对象 */
export function openCSVReader(csvFile?: any, encoding?: string): any;

/**返回的是`com.succez.commons.util.io.CSVWriter`对象 */
export function openCSVWriter(csvFile?: any, encoding?: string): any;

/**
 * 文件压缩成gzip格式
 * 
 * @param srcFile 
 * @param targetFile 
 */
export function gzip(srcFile: File | string, targetFile?: File | string): File;

/**
 * 解压缩一个gz格式的文件。
 * 
 * @param gzFile 
 * @param targetFile 
 */
export function ungzip(gzFile: File | string, targetFile?: File | string): File;


/**
 * 根据文件路径创建一个下载链接。将这个链接提供给前端用户，用户点击后可以下载此文件。
 * 
 * @param fileInfo 可以是文件路径、文件对象{@link File}或者是一个json对象。
 * @param fileName 可选，指定用户下载到本地后的默认文件名, 当{@code fileInfo}是JSON的时候不能传这个参数。
 * @return 返回一个下载链接。
 */
export function createDownloadURL(fileInfo: string | File | {
	/**要下载的文件 */
	file: string | File;
	/**指定用户下载到本地后的默认文件名 */
	fileName?: string;
	/**文件内容类型，如`application/octet-stream`。如果不指定，则通过文件的后缀自动获取 */
	contentType?: string;
	/**下载链接保留多长时间有效，超过这个时间不保证能够再访问，最长是临时文件的清理周期——2天，默认2天 */
	maxAge?: number;
	/**若为true，则会在响应头上加上`Content-Encoding`: `gzip`，浏览器会按照gzip解压文件。文件内容需要调用者自己先压缩好 */
	gzip?: boolean;
	/**为true则是临时文件，下载一次后删除 */
	temp?: boolean;
}, fileName?: string): string;