SimCube中JavaScript编程接口

4年前浏览5269

概述

本期继续介绍SimCube中的JavaScript编程接口，重点介绍与写文件相关的功能，这些功能不是标准JavaScript具有的，而是SimCube对其扩展而得的。介绍写文本文件以及Xlsx文件的相关接口。

path对象

path对象中的各个属性与方法用于处理和转换文件路径，如下表所示：

接口	说明
path.normalize(path)	对路径path进行正规化，返回的路径中没有“..”和“.”部分。
path.join(path1, path2, […])	接受两个或更多的参数，连接所有参数中的路径，并把最终的路径正规化后返回。
path.dirname(path)	返回路径path的目录名称，不包含文件名。
path.basename(path)	返回路径path的文件名称，不包括文件名后缀。
path.filename(path)	返回路径path的文件名称。
path.extname(path)	返回路径path的扩展名，从最后一个“.”开始的路径path后面部分。如果path中没有“.”则返回空字符串。
path.sep	该属性返回平台相关的文件分隔符，“\”或“/”，在Windows系统下返回前者，其它系统返回后者。
path.delimiter	该属性返回平台相关的路径分隔符，“;”或“:”，在Windows系统下返回前者，其它系统返回后者。

要注意的是，path对象操作的所有路径都可以并不存在，也即它纯粹是字符串上的操作而已，同时它是跨平台的。

fs对象

fs对象中的各个方法用于处理文件系统中的文件与目录，如下表所示：

接口	说明
fs.copy(fileName, newName)	拷贝文件fileName至newName。如果成功返回true，否则返回false。如果文件newName已经存在，那么拷贝将失败并返回false。
fs.copyDirectory(srcFilePath, targetFilePath)	递归地拷贝目录srcFilePath中的内容至目录targetFilePath中，若后者不存在则将创建。如果成功返回true，否则返回false。
fs.exists(path)	判断path是否是一个存在的文件或目录，如果是则返回true，否则返回false。
fs.link(srcPath, dstPath)	创建文件srcPath的链接，新的链接是dstPath，在Windows系统下是快捷方式，Unix类系统下是符号链接。如果成功则返回true，否则返回false。
fs.mkdir(path)	创建path中指定的目录，path中所有的父目录都将创建。如果成功则返回true，否则返回false。
fs.openUrl(url)	以操作系统默认的方式打开url，此参数可以是一个本地文件，也可以是一个网址，例如fs.openUrl('http://cn.bing.com/search?q=pera.simcube')，将打开浏览器并使用必应搜索pera.simcube。另外也可以使用它打开关联的邮件客户端发送邮件，例如fs.openUrl('mailto:SimCube@peraglobal.com?subject=SimCube软件使用反馈&body=反馈如下：')，打开邮件客户端发送邮件给SimCube@peraglobal.com反馈软件的使用情况。
fs.readdir(path)	返回path中指定目录中所有的文件名与子目录名的数组。如果路径path不存在则返回空数组。
fs.removeDirectory(path)	递归删除目录path及其子目录中的所有内容。如果成功返回true，否则返回false。
fs.rename(oldPath, newPath)	对文件或目录重命名，如果成功则返回true，否则返回false。
fs.rmdir(path)	删除path中指定的目录，包括所有的子目录，目录必须为空才可删除。如果成功返回true，否则返回false。
fs.stat(path)	以一个对象返回path中指定目录或文件的信息，如果path指定的文件或目录不存在，则返回一个空对象。对象中包含6个键值对：isFile，isDir，size，atime，ctime，mtime。
fs.truncate(path, len)	对文件path进行截断操作，操作成功后的文件长度是len，以字节为单位。如果成功返回true，否则返回false。
fs.unlink(path)	删除文件path。如果成功则返回true，否则返回false。
fs.unzip(zipFile, unzipDir)	把以通用的zip格式文件zipFile解压缩到目录unzipDir中，如果该目录不存在则会先创建。如果操作成功返回true，否则返回false。
fs.zip(zipFile, zipPaths)	把zipPaths数组中包含的的所有文件和目录以通用的zip压缩格式压缩为文件zipFile，参数zipPaths是一个字符数组，数组元素既可以是一个文件，也可以是一个目录。如果操作成功返回true，否则返回false。

要注意的是，fs对象操作的是实际的文件或目录路径。

File类

类File为JavaScript解释器提供了与操作系统文件的输入输出（IO）能力，通过JavaScript的new运算符创建并初始化File新对象：

var file=newFile(filename);

使用一个字符串参数表示文件路径创建文件对象后，可以使用各种模式（只读，只写，可读可写等）打开该文件。正常打开文件后，即可对文件进行读取或写入操作等。File类与Buffer、DataStream、TextStream类在使用中紧密相关。下表是该类的部分常用接口：

接口	说明
atEnd()	如果文件当前的读写位置已在文件尾，则返回true，否则返回false。
close()	关闭文件并设置它的打开模式为File.NotOpen。
error()	返回文件的错误状态，返回值是文件错误常量值。
flush()	把缓冲区中的数据写入文件中，如果成功返回true，否则返回false。
open(flags)	以输入的flags模式打开文件，flags使用文件打开模式中的常量。如果文件打开成功则返回true，否则返回false。
pos()	返回读写文件的当前位置值。
read(maxSize)	最多从文件中读取maxSize个字节，并以Buffer对象返回读取的数据。该方法无法报告错误，如果返回一个空的Buffer对象，则表示当前无数据可读，或有错误发生。
readAll()	以Buffer对象返回所有可读取的数据。该方法无法报告错误，如果返回一个空的Buffer对象，则表示当前无数据可读，或有错误发生。
readLine([maxSize=0])	从文件中读取一行，最大不超过maxSize个字符，如果maxSize为0，读取的行可以是任意长度。默认值是0。返回字符串对象，返回的字符串中已经没有行尾符号’\n’或’\r\n’。
seek(pos)	设置读写文件的当前位置为pos，如果成功返回true，否则返回false。
writeString(str)	把字符串str以UTF8编码写入文件中。

上面提到的Buffer类可以表示字节数组，用于存储原始的二进制字节数据。它在接口上也类似于数组Array，如length属性获取数组的字节长度，可以使用操作符buffer[i]获取或设置索引i处的字节，数组中每个字节在0~255之间。当使用操作符[]设置的索引超过现有数组的长度时，Buffer对象将分配更大的空间；当使用操作符[]获取字节数据，但索引超出范围时，将返回undefined。

TextStream类

用于文本数据流。可以从Buffer、File对象中读取或写入文本数据流。下表是该类的部分常用接口：

接口	说明
atEnd()	如果到达了文件或流的尾部则返回true，否则返回false。
codecName ()	返回当前文本流的编码字符串名称。
flush()	把缓冲区中的数据写入文件中，如果成功返回true，否则返回false。
pos()	返回读写文件的当前位置值。
read(maxSize)	最多从文件中读取maxSize个字符，并以字符串对象返回读取的数据。
readAll()	以字符串形式返回文本流中所有的内容。当读取大文件时避免这样调用，将消耗大量内存。如果对数据量大小未知，使用readLine方法为好。
readLine([maxSize=0])	从文件中读取一行，最大不超过maxSize个字符，默认值是0，读取任意个字符，并以字符串对象返回读取的数据。该方法无法报告错误，如果返回一个空的Buffer对象，则表示当前无数据可读，或有错误发生。
seek(pos)	设置读写文件的当前位置为pos，如果成功返回true，否则返回false。
readNumber() writeString(num)	从文本流中读取一个数值并返回；写入一个数值num到文本流中。
setCodec(codec)	设置文本流的编码名称，如“utf-8”，“utf-16”，“iso 8859-1”等等。
setFieldWidth(width)	设置当前的字段宽度为width，缺省情况下是0。字段宽度等于文本流中生成的文本长度。调用后对接下来所有的操作都应用。
setRealNumberPrecision(p)	设置浮点数的精度为p，不能是一个负数，缺省值是6。