Files - 文件系统
<p>[TOC]</p>
<h1>Files</h1>
<blockquote>
<p>Stability: 2 - Stable</p>
</blockquote>
<p>files模块提供了一些常见的文件处理，包括文件读写、移动、复制、删掉等。</p>
<p>一次性的文件读写可以直接使用<code>files.read()</code>, <code>files.write()</code>, <code>files.append()</code>等方便的函数，但如果需要频繁读写或随机读写，则使用<code>open()</code>函数打开一个文件对象来操作文件，并在操作完毕后调用<code>close()</code>函数关闭文件。</p>
<h2>files.isFile(path)</h2>
<ul>
<li><code>path</code> {string} 路径</li>
<li>返回 {boolean}</li>
</ul>
<p>返回路径path是否是文件。</p>
<pre><code>log(files.isDir("/sdcard/文件夹/")); //返回false
log(files.isDir("/sdcard/文件.txt")); //返回true</code></pre>
<h2>files.isDir(path)</h2>
<ul>
<li><code>path</code> {string} 路径</li>
<li>返回 {boolean}</li>
</ul>
<p>返回路径path是否是文件夹。</p>
<pre><code>log(files.isDir("/sdcard/文件夹/")); //返回true
log(files.isDir("/sdcard/文件.txt")); //返回false</code></pre>
<h2>files.isEmptyDir(path)</h2>
<ul>
<li><code>path</code> {string} 路径</li>
<li>返回 {boolean}</li>
</ul>
<p>返回文件夹path是否为空文件夹。如果该路径并非文件夹，则直接返回<code>false</code>。</p>
<h2>files.join(parent, child)</h2>
<ul>
<li><code>parent</code> {string} 父目录路径</li>
<li><code>child</code> {string} 子路径</li>
<li>返回 {string}</li>
</ul>
<p>连接两个路径并返回，例如<code>files.join("/sdcard/", "1.txt")</code>返回"/sdcard/1.txt"。</p>
<h2>files.create(path)</h2>
<ul>
<li><code>path</code> {string} 路径</li>
<li>返回 {boolean}</li>
</ul>
<p>创建一个文件或文件夹并返回是否创建成功。如果文件已经存在，则直接返回<code>false</code>。</p>
<pre><code>files.create("/sdcard/新文件夹/");</code></pre>
<h2>files.createWithDirs(path)</h2>
<ul>
<li><code>path</code> {string} 路径</li>
<li>返回 {boolean}</li>
</ul>
<p>创建一个文件或文件夹并返回是否创建成功。如果文件所在文件夹不存在，则先创建他所在的一系列文件夹。如果文件已经存在，则直接返回<code>false</code>。</p>
<pre><code>files.createWithDirs("/sdcard/新文件夹/新文件夹/新文件夹/1.txt");</code></pre>
<h2>files.exists(path)</h2>
<ul>
<li><code>path</code> {string} 路径</li>
<li>返回 {boolean}</li>
</ul>
<p>返回在路径path处的文件是否存在。</p>
<h2>files.ensureDir(path)</h2>
<ul>
<li><code>path</code> {string} 路径</li>
</ul>
<p>确保路径path所在的文件夹存在。如果该路径所在文件夹不存在，则创建该文件夹。</p>
<p>例如对于路径"/sdcard/Download/ABC/1.txt"，如果/Download/文件夹不存在，则会先创建Download，再创建ABC文件夹。</p>
<h2>files.read(path[, encoding = "utf-8"])</h2>
<ul>
<li><code>path</code> {string} 路径</li>
<li><code>encoding</code> {string} 字符编码，可选，默认为utf-8</li>
<li>返回 {string}</li>
</ul>
<p>读取文本文件path的所有内容并返回。如果文件不存在，则抛出<code>FileNotFoundException</code>。</p>
<pre><code>log(files.read("/sdcard/1.txt"));</code></pre>
<h2>files.readBytes(path)</h2>
<ul>
<li><code>path</code> {string} 路径</li>
<li>返回 {byte[]}</li>
</ul>
<p>读取文件path的所有内容并返回一个字节数组。如果文件不存在，则抛出<code>FileNotFoundException</code>。</p>
<p>注意，该数组是Java的数组，不具有JavaScript数组的forEach, slice等函数。</p>
<p>一个以16进制形式打印文件的例子如下:</p>
<pre><code>var data = files.readBytes("/sdcard/1.png");
var sb = new java.lang.StringBuilder();
for(var i = 0; i < data.length; i++){
sb.append(data[i].toString(16));
}
log(sb.toString());</code></pre>
<h2>files.write(path, text[, encoding = "utf-8"])</h2>
<ul>
<li><code>path</code> {string} 路径</li>
<li><code>text</code> {string} 要写入的文本内容</li>
<li><code>encoding</code> {string} 字符编码</li>
</ul>
<p>把text写入到文件path中。如果文件存在则覆盖，不存在则创建。</p>
<pre><code>var text = "文件内容";
//写入文件
files.write("/sdcard/1.txt", text);
//用其他应用查看文件
app.viewFile("/sdcard/1.txt");</code></pre>
<h2>files.writeBytes(path, bytes)</h2>
<ul>
<li><code>path</code> {string} 路径</li>
<li><code>bytes</code> {byte[]} 字节数组，要写入的二进制数据</li>
</ul>
<p>把bytes写入到文件path中。如果文件存在则覆盖，不存在则创建。</p>
<h2>files.append(path, text[, encoding = 'utf-8'])</h2>
<ul>
<li><code>path</code> {string} 路径</li>
<li><code>text</code> {string} 要写入的文本内容</li>
<li><code>encoding</code> {string} 字符编码</li>
</ul>
<p>把text追加到文件path的末尾。如果文件不存在则创建。</p>
<pre><code>var text = "追加的文件内容";
files.append("/sdcard/1.txt", text);
files.append("/sdcard/1.txt", text);
//用其他应用查看文件
app.viewFile("/sdcard/1.txt");</code></pre>
<h2>files.appendBytes(path, text[, encoding = 'utf-8'])</h2>
<ul>
<li><code>path</code> {string} 路径</li>
<li><code>bytes</code> {byte[]} 字节数组，要写入的二进制数据</li>
</ul>
<p>把bytes追加到文件path的末尾。如果文件不存在则创建。</p>
<h2>files.copy(fromPath, toPath)</h2>
<ul>
<li><code>fromPath</code> {string} 要复制的原文件路径</li>
<li><code>toPath</code> {string} 复制到的文件路径</li>
<li>返回 {boolean}</li>
</ul>
<p>复制文件，返回是否复制成功。例如<code>files.copy("/sdcard/1.txt", "/sdcard/Download/1.txt")</code>。</p>
<h2>files.move(fromPath, toPath)</h2>
<ul>
<li><code>fromPath</code> {string} 要移动的原文件路径</li>
<li><code>toPath</code> {string} 移动到的文件路径</li>
<li>返回 {boolean}</li>
</ul>
<p>移动文件，返回是否移动成功。例如<code>files.move("/sdcard/1.txt", "/sdcard/Download/1.txt")</code>会把1.txt文件从sd卡根目录移动到Download文件夹。</p>
<h2>files.rename(path, newName)</h2>
<ul>
<li><code>path</code> {string} 要重命名的原文件路径</li>
<li><code>newName</code> {string} 要重命名的新文件名</li>
<li>返回 {boolean}</li>
</ul>
<p>重命名文件，并返回是否重命名成功。例如<code>files.rename("/sdcard/1.txt", "2.txt")</code>。</p>
<h2>files.renameWithoutExtension(path, newName)</h2>
<ul>
<li><code>path</code> {string} 要重命名的原文件路径</li>
<li><code>newName</code> {string} 要重命名的新文件名</li>
<li>返回 {boolean}</li>
</ul>
<p>重命名文件，不包含拓展名，并返回是否重命名成功。例如<code>files.rename("/sdcard/1.txt", "2")</code>会把"1.txt"重命名为"2.txt"。</p>
<h2>files.getName(path)</h2>
<ul>
<li><code>path</code> {string} 路径</li>
<li>返回 {string}</li>
</ul>
<p>返回文件的文件名。例如<code>files.getName("/sdcard/1.txt")</code>返回"1.txt"。</p>
<h2>files.getNameWithoutExtension(path)</h2>
<ul>
<li><code>path</code> {string} 路径</li>
<li>返回 {string}</li>
</ul>
<p>返回不含拓展名的文件的文件名。例如<code>files.getName("/sdcard/1.txt")</code>返回"1"。</p>
<h2>files.getExtension(path)</h2>
<ul>
<li><code>path</code> {string} 路径</li>
<li>返回 {string}</li>
</ul>
<p>返回文件的拓展名。例如<code>files.getExtension("/sdcard/1.txt")</code>返回"txt"。</p>
<h2>files.remove(path)</h2>
<ul>
<li><code>path</code> {string} 路径</li>
<li>返回 {boolean}</li>
</ul>
<p>删除文件或<strong>空文件夹</strong>，返回是否删除成功。</p>
<h2>files.removeDir(path)</h2>
<ul>
<li><code>path</code> {string} 路径</li>
<li><code>path</code> {string} 路径</li>
<li>返回 {boolean}</li>
</ul>
<p>删除文件夹，如果文件夹不为空，则删除该文件夹的所有内容再删除该文件夹，返回是否全部删除成功。</p>
<h2>files.getSdcardPath()</h2>
<ul>
<li>返回 {string}</li>
</ul>
<p>返回SD卡路径。所谓SD卡，即外部存储器。</p>
<h2>files.cwd()</h2>
<ul>
<li>返回 {string}</li>
</ul>
<p>返回脚本的"当前工作文件夹路径"。该路径指的是，如果脚本本身为脚本文件，则返回这个脚本文件所在目录；否则返回<code>null</code>获取其他设定路径。</p>
<p>例如，对于脚本文件"/sdcard/脚本/1.js"运行<code>files.cwd()</code>返回"/sdcard/脚本/"。</p>
<h2>files.path(relativePath)</h2>
<ul>
<li><code>relativePath</code> {string} 相对路径</li>
<li>返回 {string}</li>
</ul>
<p>返回相对路径对应的绝对路径。例如<code>files.path("./1.png")</code>，如果运行这个语句的脚本位于文件夹"/sdcard/脚本/"中，则返回<code>"/sdcard/脚本/1.png"</code>。</p>
<h2>files.listDir(path[, filter])</h2>
<ul>
<li><code>path</code> {string} 路径</li>
<li><code>filter</code> {Function} 过滤函数，可选。接收一个<code>string</code>参数（文件名），返回一个<code>boolean</code>值。</li>
</ul>
<p>列出文件夹path下的满足条件的文件和文件夹的名称的数组。如果不加filter参数，则返回所有文件和文件夹。</p>
<p>列出sdcard目录下所有文件和文件夹为:</p>
<pre><code>var arr = files.listDir("/sdcard/");
log(arr);</code></pre>
<p>列出脚本目录下所有js脚本文件为:</p>
<pre><code>var dir = "/sdcard/脚本/";
var jsFiles = files.listDir(dir, function(name){
return name.endsWith(".js") && files.isFile(files.join(dir, name));
});
log(jsFiles);</code></pre>
<h2>open(path[, mode = "r", encoding = "utf-8", bufferSize = 8192])</h2>
<ul>
<li><code>path</code> {string} 文件路径，例如"/sdcard/1.txt"。</li>
<li><code>mode</code> {string} 文件打开模式，包括:
<ul>
<li>"r": 只读文本模式。该模式下只能对文件执行<strong>文本</strong>读取操作。</li>
<li>"w": 只写文本模式。该模式下只能对文件执行<strong>文本</strong>覆盖写入操作。</li>
<li>"a": 附加文本模式。该模式下将会把写入的文本附加到文件末尾。 </li>
<li>"rw": 随机读写文本模式。该模式下将会把写入的文本附加到文件末尾。<br />
目前暂不支持二进制模式，随机读写模式。</li>
</ul></li>
<li><code>encoding</code> {string} 字符编码。</li>
<li><code>bufferSize</code> {number} 文件读写的缓冲区大小。</li>
</ul>
<p>打开一个文件。根据打开模式返回不同的文件对象。包括：</p>
<ul>
<li>"r": 返回一个ReadableTextFile对象。</li>
<li>"w", "a": 返回一个WritableTextFile对象。</li>
</ul>
<p>对于"w"模式，如果文件并不存在，则会创建一个，已存在则会清空该文件内容；其他模式文件不存在会抛出FileNotFoundException。</p>
<h1>ReadableTextFile</h1>
<p>可读文件对象。</p>
<h2>ReadableTextFile.read()</h2>
<p>返回该文件剩余的所有内容的字符串。</p>
<h2>ReadableTextFile.read(maxCount)</h2>
<ul>
<li><code>maxCount</code> {Number} 最大读取的字符数量</li>
</ul>
<p>读取该文件接下来最长为maxCount的字符串并返回。即使文件剩余内容不足maxCount也不会出错。</p>
<h2>ReadableTextFile.readline()</h2>
<p>读取一行并返回（不包含换行符）。</p>
<h2>ReadableTextFile.readlines()</h2>
<p>读取剩余的所有行，并返回它们按顺序组成的字符串数组。</p>
<h2>close()</h2>
<p>关闭该文件。</p>
<p><strong>打开一个文件不再使用时务必关闭</strong></p>
<h1>PWritableTextFile</h1>
<p>可写文件对象。</p>
<h2>PWritableTextFile.write(text)</h2>
<ul>
<li><code>text</code> {string} 文本</li>
</ul>
<p>把文本内容text写入到文件中。</p>
<h2>PWritableTextFile.writeline(line)</h2>
<ul>
<li><code>text</code> {string} 文本</li>
</ul>
<p>把文本line写入到文件中并写入一个换行符。</p>
<h2>PWritableTextFile.writelines(lines)</h2>
<ul>
<li><code>lines</code> {Array} 字符串数组</li>
</ul>
<p>把很多行写入到文件中....</p>
<h2>PWritableTextFile.flush()</h2>
<p>把缓冲区内容输出到文件中。</p>
<h2>PWritableTextFile.close()</h2>
<p>关闭文件。同时会被缓冲区内容输出到文件。</p>
<p><strong>打开一个文件写入后，不再使用时务必关闭，否则文件可能会丢失</strong></p>