nsIFilePicker 编辑

widget/nsIFilePicker.idlScriptable 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. Inherits from: nsISupports Last changed in Gecko 17.0 (Firefox 17.0 / Thunderbird 17.0 / SeaMonkey 2.14)

Implemented by: @mozilla.org/filepicker;1. To create an instance, use:

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

Method overview

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);

short show(); Obsolete since Gecko 57.0

Attributes

Attribute	Type	Description
addToRecentDocs	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 before calling open() or show(). Exceptions thrown NS_ERROR_FAILURE If you try to read this attribute.
displayDirectory	nsILocalFile	The directory that the file picker dialog should initially display. This should be set this before calling open() or show() to specify a starting point.
file	nsILocalFile	The currently selected file or directory. Read only.
files	nsISimpleEnumerator	An enumerator of the currently selected files. Read only. Note: Only works with modeOpenMultiple mode.
fileURL	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.

Constants

Mode constants

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

Constant	Value	Description
modeOpen	0	Load a file.
modeSave	1	Save a file.
modeGetFolder	2	Select a folder/directory.
modeOpenMultiple	3	Load multiple files.

Return value constants

These values are returned by show() or passed as an argument to open()'s callback, 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

Filter constants

These constants are used to create filters for commonly-used file types. For the most up to date list see 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.
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.
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.

Methods

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 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.

open()

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 nsIFilePickerShownCallback to be called on completion.

show()

Obsolete since Gecko 57.0 (Firefox 57.0 / Thunderbird 57.0 / SeaMonkey 2.54)

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

short show();

Parameters

None.

Return value

One of the return constants.

Example

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);
fp.open(function (rv) {
  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 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);
    }