FileSystemDirectoryHandle: getFileHandle() method
Baseline 2023
Newly available
Since March 2023, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.
Secure context: This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.
Note: This feature is available in Web Workers.
The getFileHandle()
method of the
FileSystemDirectoryHandle
interface returns a
FileSystemFileHandle
for a file with the specified name, within the
directory the method is called.
Syntax
getFileHandle(name)
getFileHandle(name, options)
Parameters
name
-
A string representing the
FileSystemHandle.name
of the file you wish to retrieve. options
Optional-
An object with the following properties:
create
Optional-
A
Boolean
. Defaultfalse
. When set totrue
if the file is not found, one with the specified name will be created and returned.
Return value
A Promise
which resolves with a FileSystemFileHandle
.
Exceptions
NotAllowedError
DOMException
-
Thrown if the
PermissionStatus.state
for the handle is not'granted'
inreadwrite
mode if thecreate
option is set totrue
or inread
mode if thecreate
option is set tofalse
. TypeError
-
Thrown if the name specified is not a valid string or contains characters that would interfere with the native file system.
TypeMismatchError
DOMException
-
Thrown if the named entry is a directory and not a file.
NotFoundError
DOMException
-
Thrown if the current entry is not found or if the file doesn't exist and the
create
option is set tofalse
.
Examples
The following example returns a file handle with the specified name, if the file does not exist it is created.
const fileName = "fileToGetName";
// assuming we have a directory handle: 'currentDirHandle'
const fileHandle = currentDirHandle.getFileHandle(fileName, { create: true });
Specifications
Specification |
---|
File System Standard # api-filesystemdirectoryhandle-getfilehandle |
Browser compatibility
BCD tables only load in the browser