UXP Toolkit
    Preparing search index...

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

    These APIs work with UXP Manifest version v5 and above.

    https://developer.adobe.com/photoshop/uxp/2022/uxp-api/reference-js/Modules/uxp/Persistent%20File%20Storage/FileSystemProvider/

    Hierarchy (View Summary)

    Index

    Constructors

    constructor

    Properties

    isFileSystemProvider supportedDomains

    Methods

    createEntryWithUrl createPersistentToken createSessionToken getDataFolder getEntryForPersistentToken getEntryForSessionToken getEntryWithUrl getFileForOpening getFileForSaving getFolder getFsUrl getNativePath getPluginFolder getTemporaryFolder isFileSystemProvider

    Constructors

    Properties

    isFileSystemProvider: boolean

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

    supportedDomains: DomainSymbol[]

    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.

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

    Methods

    • Creates an entry for the given url and returns the appropriate instance.

      Parameters

      • url: string

        The url to create an Entry object. Note that file: scheme has limited support in UWP due to the strict File access permissions.

      • Optionaloptions: { overwrite?: boolean; type?: TypeSymbol }

        Options for the create operation (all properties are optional)

        • Optionaloverwrite?: boolean

          If true, the create attempt can overwrite an existing file.

        • Optionaltype?: TypeSymbol

          Indicates which kind of entry to create. Pass types.folder to create a new folder. Note that if the type is file then this method just creates a file entry object and not the actual file on the disk. File on the storage is created when data is written into the file. eg: call write method on the file entry object.

      Returns Promise<Folder | File>

      The File or Folder object which is created for the given url.

      Error if invalid file url format or value is passed. if the parent folder of the file/folder to be created does not exist. if a folder already exists at the url. if a file already exists at the url and it is requested to create a folder. if a file already exists at the url and the overwrite option is not set to true to create a file.

      https://developer.adobe.com/photoshop/uxp/2022/uxp-api/reference-js/Modules/uxp/Persistent%20File%20Storage/FileSystemProvider/#createentrywithurlurl-options

      const newImgFolder = await fs.createEntryWithUrl("plugin-temp:/img", {type: types.folder});
      const newTmpFolder = await fs.createEntryWithUrl("file:/Users/user/Documents/tmp", {type: types.folder});

      const newDatFile = await fs.createEntryWithUrl("plugin-temp:/tmp/test.dat", {overwrite: true});
      const newTxtFile = await fs.createEntryWithUrl("file:/Users/user/Documents/test.txt", {overwrite: true});

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

      Parameters

      Returns Promise<string>

      The persistent token for the given entry.

      https://developer.adobe.com/photoshop/uxp/2022/uxp-api/reference-js/Modules/uxp/Persistent%20File%20Storage/FileSystemProvider/#createpersistenttokenentry

      const fs = require('uxp').storage.localFileSystem;
      let entry = await fs.getFileForOpening();
      let token = await fs.createPersistentToken(entry);
      localStorage.setItem("persistent-file", token);

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

      Parameters

      Returns string

      The session token for the given entry.

      https://developer.adobe.com/photoshop/uxp/2022/uxp-api/reference-js/Modules/uxp/Persistent%20File%20Storage/FileSystemProvider/#createsessiontokenentry

      const fs = require('uxp').storage.localFileSystem;
      let entry = await fs.getFileForOpening();
      let token = fs.createSessionToken(entry);
      let result = await require('photoshop').action.batchPlay([{
        _obj: "open",
        "target": {
          _path: token, // Rather than a system path, this expects a session token
          _kind: "local",
        }
      }], {});

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

      Parameters

      • token: string

      Returns Promise<Entry>

      The corresponding entry for the persistent token.

      https://developer.adobe.com/photoshop/uxp/2022/uxp-api/reference-js/Modules/uxp/Persistent%20File%20Storage/FileSystemProvider/#getentryforpersistenttokentoken

      const fs = require('uxp').storage.localFileSystem;
      let entry, contents, tries = 3, success = false;
      while (tries > 0) {
        try {
          entry = await fs.getEntryForPersistentToken(localStorage.getItem("persistent-file"));
          contents = await entry.read();
          tries = 0;
          success = true;
        } catch(err) {
          entry = await fs.getFileForOpening();
          localStorage.setItem("persistent-token", await fs.createPersistentToken(entry));
          tries--;
        }
      }
      if (!success) {
        // fail gracefully somehow
      }

    • 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 option is true.

      Parameters

      • Optionaloptions: {
            allowMultiple?: boolean;
            initialDomain?: DomainSymbol;
            initialLocation?: Folder | File;
            types?: string[];
        }

        Options for the file picker (all properties are optional)

        • OptionalallowMultiple?: boolean

          If true, multiple files can be returned (as an array).

        • OptionalinitialDomain?: DomainSymbol

          The preferred initial location of the file picker. If not defined, the most recently used domain from a file picker is used instead.

        • OptionalinitialLocation?: Folder | File

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

        • Optionaltypes?: string[]

          Array of file types that the file open picker displays.

      Returns Promise<File | File[]>

      Based on allowMultiple is true or false, or empty if no file were selected.

      https://developer.adobe.com/photoshop/uxp/2022/uxp-api/reference-js/Modules/uxp/Persistent%20File%20Storage/FileSystemProvider/#getfileforopeningoptions

      const folder = await fs.getFolder({initialDomain: domains.userDocuments});
      const file = await fs.getFileForOpening({initialLocation: folder});
      if (!file) {
        // no file selected
        return;
      }
      const text = await file.read();

      const files = await fs.getFileForOpening({allowMultiple: true, types: fileTypes.images});
      if (files.length === 0) {
        // no files selected
      }

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

      Parameters

      • suggestedName: string

        Required when options.types is not defined.

      • Optionaloptions: { initialDomain?: DomainSymbol; types?: string[] }

        Options for the file picker (all properties are optional)

        • OptionalinitialDomain?: DomainSymbol

          The preferred initial location of the file picker. If not defined, the most recently used domain from a file picker is used instead.

        • Optionaltypes?: string[]

          Allowed file extensions, with no "." prefix.

      Returns Promise<File>

      Returns the selected file, or null if no file were selected.

      https://developer.adobe.com/photoshop/uxp/2022/uxp-api/reference-js/Modules/uxp/Persistent%20File%20Storage/FileSystemProvider/#getfileforsavingsuggestedname-options

      const file = await fs.getFileForSaving("output.txt", {types: ["txt"]});
      if (!file) {
        // file picker was cancelled
        return;
      }
      await file.write("It was a dark and stormy night");

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

      Parameters

      Returns boolean

      If true, the object is a file system provider.

    Settings

    Member Visibility

    On This Page

    Constructors
    Properties
    Methods