mozilla

Revision 374427 of nsIFilePicker

  • Revision slug: XPCOM_Interface_Reference/nsIFilePicker
  • Revision title: nsIFilePicker
  • Revision id: 374427
  • Created:
  • Creator: zbinlin
  • Is current revision? No
  • Comment

Revision Content

{{ IFSummary("widget/nsIFilePicker.idl", "nsISupports", "Scriptable", "17.0", "The file picker component is used to display standard user interface for selecting files and directories, as well as for selecting destinations for, and naming, new files.") }}

实现: @mozilla.org/filepicker;1。要创建一个实例,使用以下代码:

var filePicker = Components.classes["@mozilla.org/filepicker;1"]
                 .createInstance(Components.interfaces.nsIFilePicker);

方法概述

void appendFilter(in AString title, in AString filter);
void appendFilters(in long filterMask);
void init(in nsIDOMWindow parent, in AString title, in short mode);
void open(in nsIFilePickerShownCallback aFilePickerShownCallback); {{gecko_minversion_inline("17.0")}}
short show(); {{deprecated_inline("gecko17.0")}}

属性

属性 类型 说明
addToRecentDocs {{ gecko_minversion_inline("6.0") }} boolean If true, the file is added to the operating system's "recent documents" list (if the operating system has one; nothing happens if there is no such concept on the user's platform). This attribute has no effect if private browsing mode is in effect.
defaultExtension AString The extension for the type of files you want to work with. On some platforms, this is automatically appended to filenames the user enters, if required.  Specify it without a leading dot, for example "jpg".
defaultString AString The filename, including extension, that should be suggested to the user as a default. This should be set this before calling {{ manch("open") }} or {{ manch("show") }}.
Exceptions thrown
NS_ERROR_FAILURE
If you try to read this attribute.
displayDirectory {{ Interface("nsILocalFile") }} The directory that the file picker dialog should initially display. This should be set this before calling {{ manch("open") }} or {{ manch("show") }} to specify a starting point.
file {{ Interface("nsILocalFile") }} The currently selected file or directory. Read only.
files {{ Interface("nsISimpleEnumerator") }}

An enumerator of the currently selected files. Read only.

{{ note("Only works with modeOpenMultiple mode.") }}
fileURL {{ Interface("nsIURI") }} The URI of the currently selected file or directory. Read only.
filterIndex long The (0-based) index of the filter which is currently selected in the file picker dialog. Set this to choose a particular filter to be selected by default.

常量

模式常量

These constants are used to specify the type of file picker to create when calling {{ manch("init") }}.

常量 说明
modeOpen 0 Load a file or directory.
modeSave 1 Save a file or directory.
modeGetFolder 2 Select a folder/directory.
modeOpenMultiple 3 Load multiple files.

返回值常量

These values are returned by {{ manch("show") }}, indicating the result of the file picker activity.

Constant Value Description
returnOK 0 The file picker dialog was closed by the user hitting 'Ok'
returnCancel 1 The file picker dialog was closed by the user hitting 'Cancel'
returnReplace 2 The user chose an existing file and acknowledged that they want to overwrite the file

筛选器常量

These constants are used to create filters for commonly-used file types. For the most up to date list see {{source("toolkit/content/filepicker.properties","filepicker.properties")}}.

Constant Value Description
filterAll 0x001 Corresponds to the *.* filter for file extensions. All files will pass through the filter.
filterHTML 0x002 Corresponds to the *.html, *.htm, *.shtml and *.xhtml filters for file extensions.
filterText 0x004 Corresponds to the *.txt and *.text filter for file extensions.
filterImages 0x008 Corresponds to the *.jpe, *.jpg, *.jpeg, *.gif, *.png, *.bmp, *.ico, *.svg, *.svgz, *.tif, *.tiff, *.ai, *.drw, *.pct, *.psp, *.xcf, *.psd and *.raw filters for file extensions.
filterXML 0x010 Corresponds to the *.xml filter for file extensions.
filterXUL 0x020 Corresponds to the *.xul filter for file extensions.
filterApps 0x040 Corresponds to the platform specific application filter for file extensions. Application files for the user's platform will pass through the filter.
filterAllowURLs 0x80 Allow URLs. {{ gecko_minversion_inline("1.9") }}
filterAudio 0x100 Corresponds to the *.aac, *.aif, *.flac, *.iff, *.m4a, *.m4b, *.mid, *.midi, *.mp3, *.mpa, *.mpc, *.oga, *.ogg, *.ra, *.ram, *.snd, *.wav and *.wma filters for file extensions. {{ gecko_minversion_inline("2.0") }}
filterVideo 0x200 Corresponds to the *.avi, *.divx, *.flv, *.m4v, *.mkv, *.mov, *.mp4, *.mpeg, *.mpg, *.ogm, *.ogv, *.ogx, *.rm, *.rmvb, *.smil, *.webm, *.wmv and *.xvid filters for file extensions. {{ gecko_minversion_inline("2.0") }}

方法

appendFilter()

Appends a custom file extension filter to the dialog. The filter appended first will be used to display the nsIFilePicker dialog, the user may then select another from the list.

void appendFilter(
  in AString title,
  in AString filter
);
Parameters
title
The title of the filter.
filter
The filter string. Multiple extensions may be included, separated by a semicolon and a space.
Example

Some example filter strings:

  • "*.ics"
  • "*.txt; *.doc; *.rtf"

appendFilters()

Appends a list of file extension filters, from the predefined list, to the dialog.

void appendFilters(
  in long filterMask
);
Parameters
Note: If appendFilters is the first (or only) call to set the file filters the filter with the smallest code will be used as default filter when displaying the nsIFilePicker dialog. If you would like to use another you must append it separately before the others you want to go into the drop down list.
filterMask
A combination of the filters you wish to use. You may OR multiple filters together; for example filterAll | filterHTML.

init()

Initialize the file picker widget. The file picker is not valid until this method is called.

void init(
  in nsIDOMWindow parent,
  in AString title,
  in short mode
);
Parameters
parent
The {{ Interface("nsIDOMWindow") }} parent. This dialog will be dependent on this parent. Must be non-null.
title
The file picker dialog title. If this is null, the dialog will have the default title.
mode
One of the mode constants, indicating the type of picker to create.

{{method_gecko_minversion("open","17.0")}}

Opens the file dialog asynchrounously. The passed in object's done method will be called upon completion.

void open(
  in nsIFilePickerShownCallback aFilePickerShownCallback
);
Parameters
aFilePickerShownCallback
The {{interface("nsIFilePickerShownCallback")}} to be called on completion.

{{method_deprecated("show","gecko 17.0")}}

Displays the file picker dialog. The dialog is displayed modally.

short show();
Parameters

None.

Return value

One of the return constants.

示例

Here's an example:

const nsIFilePicker = Components.interfaces.nsIFilePicker;

var fp = Components.classes["@mozilla.org/filepicker;1"]
	           .createInstance(nsIFilePicker);
fp.init(window, "Dialog Title", nsIFilePicker.modeOpen);
fp.appendFilters(nsIFilePicker.filterAll | nsIFilePicker.filterText);

var rv = fp.show();
if (rv == nsIFilePicker.returnOK || rv == nsIFilePicker.returnReplace) {
  var file = fp.file;
  // Get the path as string. Note that you usually won't 
  // need to work with the string paths.
  var path = fp.file.path;
  // work with returned nsILocalFile...
}

If your code is a component and window is not defined, you can get one using {{ Interface("nsIWindowMediator") }}.

When selecting multiple files:

    ....
    fp.init(window, "Dialog Title", nsIFilePicker.modeOpenMultiple);
    ....

    var files = fp.files;
    var paths = [];
    while (files.hasMoreElements()) 
    {
        var arg = files.getNext().QueryInterface(Components.interfaces.nsILocalFile).path;
        paths.push(arg);
    }

Revision Source

<p>{{ IFSummary("widget/nsIFilePicker.idl", "nsISupports", "Scriptable", "17.0", "The file picker component is used to display standard user interface for selecting files and directories, as well as for selecting destinations for, and naming, new files.") }}</p>
<p>实现: <code>@mozilla.org/filepicker;1</code>。要创建一个实例,使用以下代码:</p>
<pre class="eval">
var filePicker = Components.classes["@mozilla.org/filepicker;1"]
                 .createInstance(Components.interfaces.nsIFilePicker);
</pre>
<h2 id="Method_overview" name="Method_overview">方法概述</h2>
<table class="standard-table">
  <tbody>
    <tr>
      <td><code>void <a href="#appendFilter()">appendFilter</a>(in AString title, in AString filter);</code></td>
    </tr>
    <tr>
      <td><code>void <a href="#appendFilters()">appendFilters</a>(in long filterMask);</code></td>
    </tr>
    <tr>
      <td><code>void <a href="#init()">init</a>(in nsIDOMWindow parent, in AString title, in short mode);</code></td>
    </tr>
    <tr>
      <td><code>void <a href="#open()">open</a>(in nsIFilePickerShownCallback aFilePickerShownCallback);</code> {{gecko_minversion_inline("17.0")}}</td>
    </tr>
    <tr>
      <td><code>short <a href="#show()">show</a>();</code> {{deprecated_inline("gecko17.0")}}</td>
    </tr>
  </tbody>
</table>
<h2 id="Attributes" name="Attributes">属性</h2>
<table class="standard-table">
  <tbody>
    <tr>
      <td class="header">属性</td>
      <td class="header">类型</td>
      <td class="header">说明</td>
    </tr>
    <tr>
      <td><code>addToRecentDocs</code> {{ gecko_minversion_inline("6.0") }}</td>
      <td><code>boolean</code></td>
      <td>If <code>true</code>, the file is added to the operating system's "recent documents" list (if the operating system has one; nothing happens if there is no such concept on the user's platform). This attribute has no effect if private browsing mode is in effect.</td>
    </tr>
    <tr>
      <td><code>defaultExtension</code></td>
      <td><code><a href="/en/AString" title="en/AString">AString</a></code></td>
      <td>The extension for the type of files you want to work with. On some platforms, this is automatically appended to filenames the user enters, if required.&nbsp; Specify it without a leading dot, for example "jpg".</td>
    </tr>
    <tr>
      <td><code>defaultString</code></td>
      <td><code><a href="/en/AString" title="en/AString">AString</a></code></td>
      <td>The filename, including extension, that should be suggested to the user as a default. This should be set this before calling {{ manch("open") }} or {{ manch("show") }}.
        <h6 id="Exceptions_thrown" name="Exceptions_thrown">Exceptions thrown</h6>
        <dl>
          <dt>
            <code>NS_ERROR_FAILURE</code></dt>
          <dd>
            If you try to read this attribute.</dd>
        </dl>
      </td>
    </tr>
    <tr>
      <td><code>displayDirectory</code></td>
      <td><code>{{ Interface("nsILocalFile") }}</code></td>
      <td>The directory that the file picker dialog should initially display. This should be set this before calling {{ manch("open") }} or {{ manch("show") }} to specify a starting point.</td>
    </tr>
    <tr>
      <td><code>file</code></td>
      <td><code>{{ Interface("nsILocalFile") }}</code></td>
      <td>The currently selected file or directory. <strong>Read only.</strong></td>
    </tr>
    <tr>
      <td><code>files</code></td>
      <td><code>{{ Interface("nsISimpleEnumerator") }}</code></td>
      <td>
        <p>An enumerator of the currently selected files. <strong>Read only.</strong></p>
        {{ note("Only works with <code>modeOpenMultiple</code> mode.") }}</td>
    </tr>
    <tr>
      <td><code>fileURL</code></td>
      <td><code>{{ Interface("nsIURI") }}</code></td>
      <td>The URI of the currently selected file or directory. <strong>Read only.</strong></td>
    </tr>
    <tr>
      <td><code>filterIndex</code></td>
      <td><code><a href="/en/long" title="en/long">long</a></code></td>
      <td>The (0-based) index of the filter which is currently selected in the file picker dialog. Set this to choose a particular filter to be selected by default.</td>
    </tr>
  </tbody>
</table>
<h2 id="Constants" name="Constants">常量</h2>
<h3 id="Mode_constants" name="Mode_constants">模式常量</h3>
<p>These constants are used to specify the type of file picker to create when calling {{ manch("init") }}.</p>
<table class="standard-table">
  <tbody>
    <tr>
      <td class="header">常量</td>
      <td class="header">值</td>
      <td class="header">说明</td>
    </tr>
    <tr>
      <td><code>modeOpen</code></td>
      <td><code>0</code></td>
      <td>Load a file or directory.</td>
    </tr>
    <tr>
      <td><code>modeSave</code></td>
      <td><code>1</code></td>
      <td>Save a file or directory.</td>
    </tr>
    <tr>
      <td><code>modeGetFolder</code></td>
      <td><code>2</code></td>
      <td>Select a folder/directory.</td>
    </tr>
    <tr>
      <td><code>modeOpenMultiple</code></td>
      <td><code>3</code></td>
      <td>Load multiple files.</td>
    </tr>
  </tbody>
</table>
<h3 id="Return_value_constants" name="Return_value_constants">返回值常量</h3>
<p>These values are returned by {{ manch("show") }}, indicating the result of the file picker activity.</p>
<table class="standard-table">
  <tbody>
    <tr>
      <td class="header">Constant</td>
      <td class="header">Value</td>
      <td class="header">Description</td>
    </tr>
    <tr>
      <td><code>returnOK</code></td>
      <td><code>0</code></td>
      <td>The file picker dialog was closed by the user hitting 'Ok'</td>
    </tr>
    <tr>
      <td><code>returnCancel</code></td>
      <td><code>1</code></td>
      <td>The file picker dialog was closed by the user hitting 'Cancel'</td>
    </tr>
    <tr>
      <td><code>returnReplace</code></td>
      <td><code>2</code></td>
      <td>The user chose an existing file and acknowledged that they want to overwrite the file</td>
    </tr>
  </tbody>
</table>
<h3 id="Filter_constants" name="Filter_constants">筛选器常量</h3>
<p>These constants are used to create filters for commonly-used file types. For the most up to date list see {{source("toolkit/content/filepicker.properties","filepicker.properties")}}.</p>
<table class="standard-table">
  <tbody>
    <tr>
      <td class="header">Constant</td>
      <td class="header">Value</td>
      <td class="header">Description</td>
    </tr>
    <tr>
      <td><code>filterAll</code></td>
      <td><code>0x001</code></td>
      <td>Corresponds to the *.* filter for file extensions. All files will pass through the filter.</td>
    </tr>
    <tr>
      <td><code>filterHTML</code></td>
      <td><code>0x002</code></td>
      <td>Corresponds to the *.html, *.htm, *.shtml and *.xhtml filters for file extensions.</td>
    </tr>
    <tr>
      <td><code>filterText</code></td>
      <td><code>0x004</code></td>
      <td>Corresponds to the *.txt and *.text filter for file extensions.</td>
    </tr>
    <tr>
      <td><code>filterImages</code></td>
      <td><code>0x008</code></td>
      <td>Corresponds to the *.jpe, *.jpg, *.jpeg, *.gif, *.png, *.bmp, *.ico, *.svg, *.svgz, *.tif, *.tiff, *.ai, *.drw, *.pct, *.psp, *.xcf, *.psd and *.raw filters for file extensions.</td>
    </tr>
    <tr>
      <td><code>filterXML</code></td>
      <td><code>0x010</code></td>
      <td>Corresponds to the *.xml filter for file extensions.</td>
    </tr>
    <tr>
      <td><code>filterXUL</code></td>
      <td><code>0x020</code></td>
      <td>Corresponds to the *.xul filter for file extensions.</td>
    </tr>
    <tr>
      <td><code>filterApps</code></td>
      <td><code>0x040</code></td>
      <td>Corresponds to the platform specific application filter for file extensions. Application files for the user's platform will pass through the filter.</td>
    </tr>
    <tr>
      <td><code>filterAllowURLs</code></td>
      <td><code>0x80</code></td>
      <td>Allow URLs. {{ gecko_minversion_inline("1.9") }}</td>
    </tr>
    <tr>
      <td><code>filterAudio</code></td>
      <td><code>0x100</code></td>
      <td>Corresponds to the *.aac, *.aif, *.flac, *.iff, *.m4a, *.m4b, *.mid, *.midi, *.mp3, *.mpa, *.mpc, *.oga, *.ogg, *.ra, *.ram, *.snd, *.wav and *.wma filters for file extensions. {{ gecko_minversion_inline("2.0") }}</td>
    </tr>
    <tr>
      <td><code>filterVideo</code></td>
      <td><code>0x200</code></td>
      <td>Corresponds to the *.avi, *.divx, *.flv, *.m4v, *.mkv, *.mov, *.mp4, *.mpeg, *.mpg, *.ogm, *.ogv, *.ogx, *.rm, *.rmvb, *.smil, *.webm, *.wmv and *.xvid filters for file extensions. {{ gecko_minversion_inline("2.0") }}</td>
    </tr>
  </tbody>
</table>
<h2 id="Methods" name="Methods">方法</h2>
<h3 id="appendFilter()" name="appendFilter()">appendFilter()</h3>
<p>Appends a custom file extension filter to the dialog. The filter appended first will be used to display the <code>nsIFilePicker</code> dialog, the user may then select another from the list.</p>
<pre class="eval">
void appendFilter(
  in AString title,
  in AString filter
);
</pre>
<h6 id="Parameters" name="Parameters">Parameters</h6>
<dl>
  <dt>
    <code>title</code></dt>
  <dd>
    The title of the filter.</dd>
  <dt>
    <code>filter</code></dt>
  <dd>
    The filter string. Multiple extensions may be included, separated by a semicolon and a space.</dd>
</dl>
<h6 id="appendFilter_example" name="appendFilter_example">Example</h6>
<p>Some example filter strings:</p>
<ul>
  <li>"*.ics"</li>
  <li>"*.txt; *.doc; *.rtf"</li>
</ul>
<h3 id="appendFilters()" name="appendFilters()">appendFilters()</h3>
<p>Appends a list of file extension filters, from the predefined list, to the dialog.</p>
<pre class="eval">
void appendFilters(
  in long filterMask
);
</pre>
<h6 id="Parameters" name="Parameters">Parameters</h6>
<div class="note">
  <strong>Note:</strong> If <code>appendFilters</code> is the first (or only) call to set the file filters the filter with the smallest code will be used as default filter when displaying the <code>nsIFilePicker</code> dialog. If you would like to use another you must append it separately before the others you want to go into the drop down list.</div>
<dl>
  <dt>
    <code>filterMask</code></dt>
  <dd>
    A combination of the <a class="internal" href="#Filter_constants" title="Filter constants">filters</a> you wish to use. You may OR multiple filters together; for example <code>filterAll | filterHTML</code>.</dd>
</dl>
<h3 id="init()" name="init()">init()</h3>
<p>Initialize the file picker widget. The file picker is not valid until this method is called.</p>
<pre class="eval">
void init(
  in nsIDOMWindow parent,
  in AString title,
  in short mode
);
</pre>
<h6 id="Parameters" name="Parameters">Parameters</h6>
<dl>
  <dt>
    <code>parent</code></dt>
  <dd>
    The {{ Interface("nsIDOMWindow") }} parent. This dialog will be dependent on this parent. Must be non-null.</dd>
  <dt>
    <code>title</code></dt>
  <dd>
    The file picker dialog title. If this is <code>null</code>, the dialog will have the default title.</dd>
  <dt>
    <code>mode</code></dt>
  <dd>
    One of the <a class="internal" href="#Mode_constants" title="Mode constants">mode constants</a>, indicating the type of picker to create.</dd>
</dl>
<p id="open()">{{method_gecko_minversion("open","17.0")}}</p>
<p>Opens the file dialog asynchrounously. The passed in object's done method will be called upon completion.</p>
<pre class="eval">
void open(
  in nsIFilePickerShownCallback aFilePickerShownCallback
);
</pre>
<h6 id="Parameters" name="Parameters">Parameters</h6>
<dl>
  <dt>
    <code>aFilePickerShownCallback</code></dt>
  <dd>
    The {{interface("nsIFilePickerShownCallback")}} to be called on completion.</dd>
</dl>
<p id="show()">{{method_deprecated("show","gecko 17.0")}}</p>
<p>Displays the file picker dialog. The dialog is displayed modally.</p>
<pre class="eval">
short show();
</pre>
<h6 id="Parameters" name="Parameters">Parameters</h6>
<p>None.</p>
<h6 id="Return_value" name="Return_value">Return value</h6>
<p>One of the <a class="internal" href="#Return_value_constants" title="Return value constants">return constants</a>.</p>
<h2 id="Example" name="Example">示例</h2>
<p>Here's an example:</p>
<pre>
const nsIFilePicker = Components.interfaces.nsIFilePicker;

var fp = Components.classes["@mozilla.org/filepicker;1"]
	           .createInstance(nsIFilePicker);
fp.init(window, "Dialog Title", nsIFilePicker.modeOpen);
fp.appendFilters(nsIFilePicker.filterAll | nsIFilePicker.filterText);

var rv = fp.show();
if (rv == nsIFilePicker.returnOK || rv == nsIFilePicker.returnReplace) {
  var file = fp.file;
  // Get the path as string. Note that you usually won't 
  // need to work with the string paths.
  var path = fp.file.path;
  // work with returned nsILocalFile...
}
</pre>
<p>If your code is a component and <code>window</code> is not defined, you can get one using {{ Interface("nsIWindowMediator") }}.</p>
<p>When selecting multiple files:</p>
<pre>
    ....
    fp.init(window, "Dialog Title", nsIFilePicker.modeOpenMultiple);
    ....

    var files = fp.files;
    var paths = [];
    while (files.hasMoreElements()) 
    {
        var arg = files.getNext().QueryInterface(Components.interfaces.nsILocalFile).path;
        paths.push(arg);
    }
</pre>
Revert to this revision