文件系统

导入

通过如下方式导入文件系统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
	 */
	getFile(subpath: string, errorIfNotExists?: boolean): File

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

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

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

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

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

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

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

	/** 拷贝other文件的内容到本文件。如果本文件不存在，这里会自动创建它 */
	copy(other: File): void;

	/**  读取文件内容并以字符串形式返回，采用默认编码utf8 */
	readString(): string;

	/**
	 * 读取文件内容并以字符串形式返回
	 * @param encoding  文件内容编码，可传递：
	 * 	1. utf-8 
	 * 	2. gbk
	 */
	readString(encoding: string): string;

	/** 将文件内容读取为字节数组 */
	readBytes(): number[];

	/**
	 * 写入一个字符串到文件中，会覆盖文件原有内容
	 * 
	 * @param content 要写入的内容。
	 * @param encoding  文件内容编码，可传递：
	 * 	1. utf-8 目标文件用utf-8编码
	 * 	2. gbk 目标文件用gbk编码
	 */
	writeString(content: string, encoding?: string): void

	/**
	 * 文件读取出来时用base64编码返回，一般用于返回二进制文件的base64编码形式
	 */
	readBase64(): string;

	/**
	 * 将base64编码的内容解码后写入文件，一般用于写二进制文件。
	 * 
	 * @param base64 
	 */
	writeBase64(base64: string): void;

	/**
	 * 读取一个名値对文件，返回一个Map
	 * 如果没有找到名值对，则返回一个空Map
	 * 如果读取文件出错，则返回null
	 * 
	 * @param encoding 文件内容编码，此参数传null或空字符串时采用默认编码utf8
	 * @return
	 */
	readJson(encoding?: string): JSONObject;

	/**
	 * 写一个json文件写入数据为null或空json时，将清空文件内容
	 * @param data
	 * @param encoding 文件内容编码，此参数传null或空字符串时采用默认编码utf8
	 * @return 操作是否成功
	 * @throws IOException
	 */
	writeJson(data: JSONObject, encoding?: string): void;

	/**
	 * 读取一个多行文本文件，返回一个字符串数组，采用默认编码utf8
	 * 如果文件内容为空，则返回空数组
	 * 如果读取文件出错，则返回null
	 * @return
	 */
	readLines(): string[];

	/**
	 * 读取一个多行文本文件，返回一个字符串数组
	 * 如果文件内容为空，则返回空数组
	 * 如果读取文件出错，则返回null
	 * @param encoding 文件内容编码，此参数传null或空字符串时采用默认编码utf8
	 * @return
	 */
	readLines(encoding: string): string[];

	/**
	 * 写一个多行文本文件
	 * 传入的文件内容为null或空数组时，将清空文件内容
	 * @param data
	 * @param encoding 文件内容编码，此参数传null或空字符串时采用默认编码utf8
	 * @return 操作是否成功
	 */
	writeLines(data: string[], encoding?: string): void;

	/**
	 * 读取文件内容并转换为一个dom4j的Document对象
	 * 如果读取文件出错或转换为xml出错，则返回null
	 * @return
	 */
	readXML(): XMLDocument;

	/**
	 * 将dom4j的Document对象形式的xml写到文件中（未格式化）
	 * 传入的文件内容为null时，将清空文件内容
	 * @param doc
	 * @return 操作是否成功
	 */
	writeXML(xml: XMLDocument): void;

	/**
	 * 将dom4j的Document对象形式的xml写到文件中（已格式化过，有换行，tab缩进）
	 * 传入的文件内容为null时，将清空文件内容
	 * @param doc
	 * @return 操作是否成功
	 */
	writeFormatedXML(xml: XMLDocument): void;

	/**
	 * 读取一个CSV文件，返回字符串二维数组
	 * @param encoding 文件内容编码，此参数传null或空字符串时采用默认编码utf8
	 * @param separator 分隔符，此参数传null或空字符串时默认为英文逗号
	 * @return
	 */
	readCSV(encoding?: string, separator?: string): string[][];

	/**
	 * 写入一个CSV文件
	 * @param data 文件内容
	 * @param encoding 文件内容编码，此参数传null或空字符串时采用默认编码utf8
	 * @param separator 分隔符，此参数传null或空字符串时默认为英文逗号
	 * @return
	 */
	writeCSV(data: string[][], encoding?: string, separator?: string): void;

	/**
	 * 删除目录或文件
	 * @return 操作是否成功
	 */
	delete(): boolean;

	/**
	 * 清空文件夹
	 * 如果当前对象不是目录，则不进行任何操作，并返回true
	 * @return 操作是否成功
	 */
	cleanDir(): boolean;

	/**
	 * 创建文件夹，如果文件夹的任何父目录没有创建，都会被创建
	 * 如果当前路径已存在一个目录或文件，则不会进行操作，返回false
	 * @return 操作是否成功
	 */
	mkdirs(): boolean;

	/**
	 * 确保当前文件对象代表的文件或文件夹是存在的。
	 * 如果文件或文件夹存在则不做任何处理；如果不存在，则创建一个空文件，如果父目录不存在，会先创建父目录。
	 * @return 操作是否成功
	 */
	touch(): boolean

	/**
	 * 按指定的扩展名列表列出目录下的文件，不会列出子目录，可指定是否查询子目录下面的文件
	 * 如果当前对象不是目录，则返回空数组
	 * 如果没有找到符合条件的文件，则返回空数组
	 * @param extensions 扩展名过滤，比如“txt,jpg”，如果传入null或空字符串，则列出所有类型的文件
	 * @param recursive 是否递归查询子目录
	 * @return
	 */
	listFiles(extensions?: string, recursive?: boolean): File[];

	/**
	 * 列出所有直接子目录
	 * 如果当前对象不是目录，则返回空数组
	 * 如果没有找到子目录，则返回空数组
	 * @return
	 */
	listDirs(): File[];

	/**
	 * 获取文件的带缓冲的输入流，调用者使用完这个流之后，必须自行关闭流。
	 */
	openInputStream(): InputStream;

	/**
	 * 获取文件的带缓冲的输出流，调用者使用完这个流之后，必须自行关闭流。
	 */
	openOutputStream(): OutputStream;

	/**
	 * 获取文件的带缓冲的字符输入流，调用者使用完这个流之后，必须自行关闭流。
	 */
	openReader(): Reader;

	/**
	 * 获取文件的带缓冲的字符输出流对象，调用者使用完这个流之后，必须自行关闭。
	 * @return
	 */
	openWriter(): Writer;

	/**
	 * 压缩文件或者目录为一个zip文件
	 * 
	 * 如果本文件是一个目录，则只会压缩本文件下级文件或目录到zip包中
	 * 
	 * @param file 目标zip文件，如果不存在，则会创建；如果为空，则创建一个临时文件；
	 * @returns 返回zip文件
	 */
	zip(file?: File): File;

	/**
	 * 压缩文件或者目录为一个zip
	 * 
	 * 与 {@link #zip(File)} 不同的是，如果本文件是个目录也会将本文件压缩到zip中
	 * 
	 * @param file 目标zip文件，如果不存在，则会创建；如果为空，则创建一个临时文件；
	 * @returns 返回zip文件
	 */
	zipFiles(file?: File): File;
}

/**
 * 创建一个临时文件
 * 
 * 调用者还是应该尽量在不使用此文件后及时删除它,
 * 但调用者也可以不必担心在极少数情况下此文件不会被删除，
 * 因为内部有机制会在系统初始化或关闭时对所有生成的临时文件进行处理
 * 
 * 注意：这个临时文件没有被直接创建，仅构建了一个File 对象，在磁盘上是不存在的,请根据需求使用{@link File.mkdirs()} 创建
 * @param name 文件名称
 * @returns
 */
export function createTempFile(name?: string): File;

/**
 * 创建一个临时目录
 * 
 * 调用者还是应该尽量在不使用此文件后及时删除它,
 * 但调用者也可以不必担心在极少数情况下此文件不会被删除，
 * 因为内部有机制会在系统初始化或关闭时对所有生成的临时文件进行处理
 * 
 * 注意：这个临时文件夹没有被直接创建，仅构建了一个File 对象，在磁盘上是不存在的,请根据需求使用{@link File.mkdirs()} 创建
 * @param name 后缀名
 * @returns
 */
export function createTempDir(name?: string): File;

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

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

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

/**
 * 获取之前上传的文件。
 *
 * @param tempName 传入之前通过{@link this#createTempFile(String, String)}函数获得文件对象的文件名。
 * @return 只要不是非法的文件，不管文件存不存在都会返回{@link File}对象，外部无需判空
 * @throws IllegalArgumentException 当文件为非法路径文件（文件不在临时目录下）时抛出异常，如果抛出异常，需要检查代码写法，是否传入了非法的tempName
 */
export function getUploadFile(userId: string, tempName: string, errorIfNotExists?: boolean): File

/**
 * 根据抽象路径名创建指定目录，创建不成功抛出异常
 * @param path 创建目录的抽象路径名
 */
export function mkdirs(path: string): void

/**
 * 删除文件或文件夹，如果是文件夹则会删除文件夹下所有内容
 * @param path 删除文件或文件夹的路径
 */
export function deleteFile(path: string): void

/**
 * 返回元数据路径to相对于元数据路径from的相对路径
 * 如果from和to相同，则返回一个零长度的字符串
 * @param from 以/开头的元数据路径
 * @param to 以/开头的元数据路径
 * 
 * @example
 * relativePath('/data/orandea/test/aaa', '/data/orandea/impl/bbb')='../../impl/bbb'
 */
export function relativePath(from: string, to: string): string

/**
 * 将一系列路径转换为解析为绝对路径。
 * 除非路径为根路径，否则路径末尾不带斜线。长度为0的路径会被忽略。
 * @param paths
 *
 * @example
 * resolvePath('/foo/bar', './baz')='/foo/bar/baz'
 * resolvePath('/foo/bar', '/tmp/file/')='/tmp/file/'
 * resolvePath('/wwwroot', 'static_files/png/', '../gif/image.gif')='/wwwroot/static_files/gif/image.gif'
 */
export function resolvePath(...paths: string[]): string

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

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

/**
 * 此方法将路径规范化为标准格式
 * 如：
 * /foo//                    /foo/
 * /foo/./                   /foo
 * /foo/../bar               /bar
 * /foo/../bar/              /bar/
 * /foo/../bar/../baz        /baz
 * //foo//./bar              /foo/bar
 * //foo//./bar     false    \\foo\\bar
 * /../                      null
 * ../foo                    null
 * foo/bar/..                foo
 * foo/../../bar             null
 * foo/../bar                bar
 * //server/foo/../bar       //server/bar
 * //server/../bar           null
 * C:\foo\..\bar    false    C:\bar
 * C:\..\bar                 null
 * ~/foo/../bar/             ~/bar/
 * ~/../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相关命令，请从http://rarlab.com下载rar命令
 * 2.解压后的输出目录若存在则覆盖，不存在则默认解压到临时目录下
 * @param rarfile rar文件
 * @param targetDir [可选]解压后的指定目录,不传递则默认解压到临时目录下
 * @returns 返回目标解压目录
 */
export function unrar(rarfile: File, targetDir?: File): File;


/**
 * 根据文件路径创建一个下载链接。下载文件的文件名为`downloadName`
 * @param filePathOrParams 文件路径或者参数
 * @param filePathOrParams              参数Map，包括以下参数：
 * @param filePathOrParams#file         本地磁盘文件路径或者FileObject对象。
 * @param filePathOrParams#contentType  文件内容类型。如果不指定，则通过文件的后缀自动获取
 * @param filePathOrParams#downloadName 浏览器下载对话框显示的文件名。如果不指定，则取文件原始名称
 * @param filePathOrParams#lifeCycle    下载链接保留多长时间有效，超过这个时间不保证能够再访问，最长是临时文件的清理周期——2天
 *                            如果不指定或设为0，将默认设置为临时文件的最大生命周期2天
 * @param filePathOrParams#temporary    临时文件，为true则是临时文件，下载一次后删除。
 * @param downloaderName 下载文件名, 当{@code filePathOrParams}是`JSONObject`的时候不能传这个参数。
 */
export function createDownloadURL(filePathOrParams: string| File | JSONObject, downloaderName?:string): string;