Edit in GitHubLog an issue

require('uxp').storage.FileSystemProvider

Provides access to files and folders on a file system. You'll never instantiate this directly; instead you'll use an instance of one that has already been created for you by UXP.

isFileSystemProvider#

Indicates that this is a FileSystemProvider. Useful for type-checking.

supportedDomains#

An array of the domains this file system supports. If the file system can open a file picker to the user's documents folder, for example, then userDocuments will be in this list.

Example

Copied to your clipboard
1if (fs.supportedDomains.contains(domains.userDocuments)) {
2 console.log("We can open a picker to the user's documents.")
3}

getFileForOpening(options)#

Gets a file (or files) from the file system provider for the purpose of opening them. Files are read-only.

Multiple files can be returned if the allowMultiple optionistrue`.

Returns: File | Array.<File> - based on allowMultiple is true or false, or empty if no file were selected.

ParamTypeDefaultDescription
options*
[options.initialDomain]Symbolthe preferred initial location of the file picker. If not defined, the most recently used domain from a file picker is used instead.
[options.types]Array.<string>[&#x27;.*&#x27;]array of file types that the file open picker displays.
[options.initialLocation]File | Folderthe initial location of the file picker. You can pass an existing file or folder entry to suggest the picker to start at this location. If this is a file entry then the method will pick its parent folder as initial location. This will override initialDomain option.
[options.allowMultiple]booleanfalseif true, multiple files can be returned (as an array)

Example

Copied to your clipboard
1const folder = await fs.getFolder({initialDomain = domains.userDocuments});
2const file = await fs.getFileForOpening({initialLocation = folder});
3if (!file) {
4 // no file selected
5 return;
6}
7const text = await file.read();

Example

Copied to your clipboard
1const files = await fs.getFileForOpening({allowMultiple: true, types: fileTypes.images});
2if (files.length === 0) {
3 // no files selected
4}

getFileForSaving(options)#

Gets a file reference suitable for saving. The file is read-write. Any file picker displayed will be of the "save" variety.

If the user attempts to save a file that doesn't exist, the file is created automatically.

If the act of writing to the file would overwrite it, the file picker should prompt the user if they are OK with that action. If not, the file should not be returned.

Returns: File - returns the selected file, or null if no file were selected.

ParamTypeDescription
options*
[options.initialDomain]Symbolthe preferred initial location of the file picker. If not defined, the most recently used domain from a file picker is used instead.
[options.types]Array.<string>array of valid file types that the user can choose to assign to a file.

Example

Copied to your clipboard
1const [file] = await fs.getFileForSaving({ types = [ "txt" ]});
2if (!file) {
3 // no file selected, or the user didn't want to overwrite one they did select
4 return;
5}
6await file.write("It was a dark and stormy night");

getFolder(options)#

Gets a folder from the file system via a folder picker dialog. The files and folders within can be accessed via Folder#getEntries. Any files within are read-write.

If the user dismisses the picker, null is returned instead.

Returns: Folder - the selected folder or null if no folder is selected.

ParamTypeDescription
optionsany
[options.initialDomain]Symbolthe preferred initial location of the file picker. If not defined, the most recently used domain from a file picker is used instead.

Example

Copied to your clipboard
1const folder = await fs.getFolder();
2const myNovel = (await fs.getEntries()).filter(entry => entry.name.indexOf('novel') > 0);
3const text = await myNovel.read();

getTemporaryFolder()#

Returns a temporary folder. The contents of the folder will be removed when the extension is disposed.

Example

Copied to your clipboard
const temp = await fs.getTemporaryFolder();

getDataFolder()#

Returns a folder that can be used for extension's data storage without user interaction. It is persistent across host-app version upgrades.

getPluginFolder()#

Returns an plugin's folder – this folder and everything within it are read only. This contains all the Plugin related packaged assets.

getFsUrl()#

Returns the fs url of given entry.

getNativePath()#

Returns the platform native file system path of given entry.

createSessionToken(entry)#

Returns a token suitable for use with certain host-specific APIs (such as Photoshop). This token is valid only for the current plugin session. As such, it is of no use if you serialize the token to persistent storage, as the token will be invalid in the future.

Note: When using the Photoshop DOM API, pass the instance of the file instead of a session token -- Photoshop will convert the entry into a session token automatically on your behalf.

Returns: string - the session token for the given entry

ParamType
entryEntry

Example

Copied to your clipboard
1const fs = require('uxp').storage.localFileSystem;
2let entry = await fs.getFileForOpening();
3let token = fs.createSessionToken(entry);
4let result = await require('photoshop').action.batchPlay([{
5 _obj: "open",
6 "target": {
7 _path: token, // Rather than a system path, this expects a session token
8 _kind: "local",
9 }
10}], {});

getEntryForSessionToken(token)#

Returns the file system Entry that corresponds to the session token obtained from createSessionToken. If an entry cannot be found that matches the token, then a Reference Error: token is not defined error is thrown.

Returns: Entry - the corresponding entry for the session token

ParamType
tokenstring

createPersistentToken(entry)#

Returns a token suitable for use with host-specific APIs (such as Photoshop), or for storing a persistent reference to an entry (useful if you want to only ask for permission to access a file or folder once). A persistent token is not guaranteed to last forever -- certain scenarios can cause the token to longer work (including moving files, changing permissions, or OS-specific limitations). If a persistent token cannot be reused, you'll get an error at the time of use.

Returns: string - the persistent token for the given entry

ParamType
entryEntry

Example

Copied to your clipboard
1const fs = require('uxp').storage.localFileSystem;
2let entry = await fs.getFileForOpening();
3let token = fs.createPersistentToken(entry);
4localStorage.setItem("persistent-file", token);

getEntryForPersistentToken(token)#

Returns the file system Entry that corresponds to the persistent token obtained from createPersistentToken. If an entry cannot be found that matches the token, then a Reference Error: token is not defined error is thrown.

Note: retrieving an entry for a persistent token does not guarantee that the entry is valid for use. You'll need to properly handle the case where the entry no longer exists on the disk, or the permissions have changed by catching the appropriate errors. If that occurs, the suggested practice is to prompt the user for the entry again and store the new token.

Returns: Entry - the corresponding entry for the persistent token

ParamType
tokenstring

Example

Copied to your clipboard
1const fs = require('uxp').storage.localFileSystem;
2let entry, contents, tries = 3, success = false;
3while (tries > 0) {
4 try {
5 entry = await fs.getEntryForPersistentToken(localStorage.getItem("persistent-file"));
6 contents = await entry.read();
7 tries = 0;
8 success = true;
9 } catch (err) {
10 entry = await fs.getFileForOpening();
11 localStorage.setItem("persistent-token", await fs.createPersistentToken(entry));
12 tries--;
13 }
14}
15if (!success) {
16 // fail gracefully somehow
17}

isFileSystemProvider(fs)#

Checks if the supplied object is a FileSystemProvider. It's safe to use even if the object is null or undefined. Useful for type checking.

Returns: boolean - If true, the object is a file system provider

ParamTypeDescription
fsanythe object to check
Copyright © 2021 Adobe. All rights reserved.