Variables
read onlyfs:FileSystem
A {@link FileSystem file system} instance that allows to interact with local and remote
files, e.g. vscode.workspace.fs.readDirectory(someUri) allows to retrieve all entries
of a directory or vscode.workspace.fs.stat(anotherUri) returns the meta data for a
file.
read onlyname:Null<String>
The name of the workspace. undefined when no workspace
has been opened.
Refer to https://code.visualstudio.com/docs/editor/workspaces for more information on the concept of workspaces.
read onlynotebookDocuments:ReadOnlyArray<NotebookDocument>
All notebook documents currently known to the editor.
read onlyonDidChangeConfiguration:Event<ConfigurationChangeEvent>
An event that is emitted when the {@link WorkspaceConfiguration configuration} changed.
read onlyonDidChangeTextDocument:Event<TextDocumentChangeEvent>
An event that is emitted when a {@link TextDocument text document} is changed. This usually happens when the {@link TextDocument.getText contents} changes but also when other things like the {@link TextDocument.isDirty dirty}-state changes.
read onlyonDidChangeWorkspaceFolders:Event<WorkspaceFoldersChangeEvent>
An event that is emitted when a workspace folder is added or removed.
read onlyonDidCloseNotebookDocument:Event<NotebookDocument>
An event that is emitted when a {@link NotebookDocument notebook} is disposed.
Note 1: There is no guarantee that this event fires when an editor tab is closed.
Note 2: A notebook can be open but not shown in an editor which means this event can fire for a notebook that has not been shown in an editor.
read onlyonDidCloseTextDocument:Event<TextDocument>
An event that is emitted when a {@link TextDocument text document} is disposed or when the language id of a text document {@link languages.setTextDocumentLanguage has been changed}.
Note 1: There is no guarantee that this event fires when an editor tab is closed, use the {@linkcode window.onDidChangeVisibleTextEditors onDidChangeVisibleTextEditors}-event to know when editors change.
Note 2: A document can be open but not shown in an editor which means this event can fire for a document that has not been shown in an editor.
read onlyonDidCreateFiles:Event<FileCreateEvent>
An event that is emitted when files have been created.
Note: This event is triggered by user gestures, like creating a file from the explorer, or from the {@linkcode workspace.applyEdit}-api, but this event is not fired when files change on disk, e.g triggered by another application, or when using the {@linkcode FileSystem workspace.fs}-api.
read onlyonDidDeleteFiles:Event<FileDeleteEvent>
An event that is emitted when files have been deleted.
Note 1: This event is triggered by user gestures, like deleting a file from the explorer, or from the {@linkcode workspace.applyEdit}-api, but this event is not fired when files change on disk, e.g triggered by another application, or when using the {@linkcode FileSystem workspace.fs}-api.
Note 2: When deleting a folder with children only one event is fired.
read onlyonDidGrantWorkspaceTrust:Event<Void>
Event that fires when the current workspace has been trusted.
read onlyonDidOpenNotebookDocument:Event<NotebookDocument>
An event that is emitted when a {@link NotebookDocument notebook} is opened.
read onlyonDidOpenTextDocument:Event<TextDocument>
An event that is emitted when a {@link TextDocument text document} is opened or when the language id of a text document {@link languages.setTextDocumentLanguage has been changed}.
To add an event listener when a visible text document is opened, use the {@link TextEditor} events in the {@link window} namespace. Note that:
- The event is emitted before the {@link TextDocument document} is updated in the {@link window.activeTextEditor active text editor}
- When a {@link TextDocument text document} is already open (e.g.: open in another {@link window.visibleTextEditors visible text editor}) this event is not emitted
read onlyonDidRenameFiles:Event<FileRenameEvent>
An event that is emitted when files have been renamed.
Note 1: This event is triggered by user gestures, like renaming a file from the explorer, and from the {@linkcode workspace.applyEdit}-api, but this event is not fired when files change on disk, e.g triggered by another application, or when using the {@linkcode FileSystem workspace.fs}-api.
Note 2: When renaming a folder with children only one event is fired.
read onlyonDidSaveTextDocument:Event<TextDocument>
An event that is emitted when a {@link TextDocument text document} is saved to disk.
read onlyonWillCreateFiles:Event<FileWillCreateEvent>
An event that is emitted when files are being created.
Note 1: This event is triggered by user gestures, like creating a file from the explorer, or from the {@linkcode workspace.applyEdit}-api. This event is not fired when files change on disk, e.g triggered by another application, or when using the {@linkcode FileSystem workspace.fs}-api.
Note 2: When this event is fired, edits to files that are are being created cannot be applied.
read onlyonWillDeleteFiles:Event<FileWillDeleteEvent>
An event that is emitted when files are being deleted.
Note 1: This event is triggered by user gestures, like deleting a file from the explorer, or from the {@linkcode workspace.applyEdit}-api, but this event is not fired when files change on disk, e.g triggered by another application, or when using the {@linkcode FileSystem workspace.fs}-api.
Note 2: When deleting a folder with children only one event is fired.
read onlyonWillRenameFiles:Event<FileWillRenameEvent>
An event that is emitted when files are being renamed.
Note 1: This event is triggered by user gestures, like renaming a file from the explorer, and from the {@linkcode workspace.applyEdit}-api, but this event is not fired when files change on disk, e.g triggered by another application, or when using the {@linkcode FileSystem workspace.fs}-api.
Note 2: When renaming a folder with children only one event is fired.
read onlyonWillSaveTextDocument:Event<TextDocumentWillSaveEvent>
An event that is emitted when a {@link TextDocument text document} will be saved to disk.
Note 1: Subscribers can delay saving by registering asynchronous work. For the sake of data integrity the editor might save without firing this event. For instance when shutting down with dirty files.
Note 2: Subscribers are called sequentially and they can {@link TextDocumentWillSaveEvent.waitUntil delay} saving by registering asynchronous work. Protection against misbehaving listeners is implemented as such: there is an overall time budget that all listeners share and if that is exhausted no further listener is called listeners that take a long time or produce errors frequently will not be called anymore
The current thresholds are 1.5 seconds as overall time budget and a listener can misbehave 3 times before being ignored.
read onlyrootPath:Null<String>
Use {
The uri of the first entry of {@linkcode workspace.workspaceFolders workspaceFolders}
as string. undefined if there is no first entry.
Refer to https://code.visualstudio.com/docs/editor/workspaces for more information on workspaces.
@linkcode workspace.workspaceFolders workspaceFolders} instead.
read onlyworkspaceFile:Null<Uri>
The location of the workspace file, for example:
file:///Users/name/Development/myProject.code-workspace
or
untitled:1555503116870
for a workspace that is untitled and not yet saved.
Depending on the workspace that is opened, the value will be:
undefined when no workspace is opened
the path of the workspace file as Uri otherwise. if the workspace
is untitled, the returned URI will use the untitled: scheme
The location can e.g. be used with the vscode.openFolder command to
open the workspace again after it has been closed.
Example:
vscode.commands.executeCommand('vscode.openFolder', uriOfWorkspace);Refer to https://code.visualstudio.com/docs/editor/workspaces for more information on the concept of workspaces.
Note: it is not advised to use workspace.workspaceFile to write
configuration data into the file. You can use workspace.getConfiguration().update()
for that purpose which will work both when a single folder is opened as
well as an untitled or saved workspace.
read onlyworkspaceFolders:Null<ReadOnlyArray<WorkspaceFolder>>
List of workspace folders (0-N) that are open in the editor. undefined when no workspace
has been opened.
Refer to https://code.visualstudio.com/docs/editor/workspaces for more information on workspaces.
Methods
applyEdit(edit:WorkspaceEdit):Thenable<Bool>
Make changes to one or many resources or create, delete, and rename resources as defined by the given {@link WorkspaceEdit workspace edit}.
All changes of a workspace edit are applied in the same order in which they have been added. If multiple textual inserts are made at the same position, these strings appear in the resulting text in the order the 'inserts' were made, unless that are interleaved with resource edits. Invalid sequences like 'delete file a' -> 'insert text in file a' cause failure of the operation.
When applying a workspace edit that consists only of text edits an 'all-or-nothing'-strategy is used. A workspace edit with resource creations or deletions aborts the operation, e.g. consecutive edits will not be attempted, when a single edit fails.
Parameters:
edit | A workspace edit. |
|---|
Returns:
A thenable that resolves when the edit could be applied.
asRelativePath(pathOrUri:EitherType<String, Uri>, ?includeWorkspaceFolder:Bool):String
Returns a path that is relative to the workspace folder or folders.
When there are no {@link workspace.workspaceFolders workspace folders} or when the path is not contained in them, the input is returned.
@link Uri.fsPath fsPath} is used.
Parameters:
pathOrUri | A path or uri. When a uri is given its { |
|---|---|
includeWorkspaceFolder | When |
Returns:
A path relative to the root or the input.
createFileSystemWatcher(globPattern:GlobPattern, ?ignoreCreateEvents:Bool, ?ignoreChangeEvents:Bool, ?ignoreDeleteEvents:Bool):FileSystemWatcher
Creates a file system watcher.
A glob pattern that filters the file events on their absolute path must be provided. Optionally, flags to ignore certain kinds of events can be provided. To stop listening to events the watcher must be disposed.
Note that only files within the current {@link workspace.workspaceFolders workspace folders} can be watched. Note that when watching for file changes such as '**/*.js', notifications will not be sent when a parent folder is moved or deleted (this is a known limitation of the current implementation and may change in the future).
@link GlobPattern glob pattern} that is applied to the absolute paths of created, changed, and deleted files. Use a {@link RelativePattern relative pattern} to limit events to a certain {@link WorkspaceFolder workspace folder}.
Parameters:
globPattern | A { |
|---|---|
ignoreCreateEvents | Ignore when files have been created. |
ignoreChangeEvents | Ignore when files have been changed. |
ignoreDeleteEvents | Ignore when files have been deleted. |
Returns:
A new file system watcher instance.
findFiles(include:GlobPattern, ?exclude:GlobPattern, ?maxResults:Int, ?token:CancellationToken):Thenable<Array<Uri>>
Find files across all {@link workspace.workspaceFolders workspace folders} in the workspace.
@example findFiles('**/.js', '/node_modules/*', 10)
@link GlobPattern glob pattern} that defines the files to search for. The glob pattern
will be matched against the file paths of resulting matches relative to their workspace. Use a {@link RelativePattern relative pattern}
to restrict the search results to a {@link WorkspaceFolder workspace folder}.
@link GlobPattern glob pattern} that defines files and folders to exclude. The glob pattern
will be matched against the file paths of resulting matches relative to their workspace. When undefined, default excludes and the user's
configured excludes will apply. When null, no excludes will apply.
@link workspace.workspaceFolders workspace folders} are opened.
Parameters:
include | A { |
|---|---|
exclude | A { |
maxResults | An upper-bound for the result. |
token | A token that can be used to signal cancellation to the underlying search engine. |
Returns:
A thenable that resolves to an array of resource identifiers. Will return no results if no {
getConfiguration(?section:String, ?scope:ConfigurationScope):WorkspaceConfiguration
Get a workspace configuration object.
When a section-identifier is provided only that part of the configuration
is returned. Dots in the section-identifier are interpreted as child-access,
like { myExt: { setting: { doIt: true }}} and getConfiguration('myExt.setting').get('doIt') === true.
When a scope is provided configuration confined to that scope is returned. Scope can be a resource or a language identifier or both.
Parameters:
section | A dot-separated identifier. |
|---|---|
scope | A scope for which the configuration is asked for. |
Returns:
The full configuration or a subset.
getWorkspaceFolder(uri:Uri):Null<WorkspaceFolder>
Returns the {@link WorkspaceFolder workspace folder} that contains a given uri.
returns undefined when the given uri doesn't match any workspace folder
returns the input when the given uri is a workspace folder itself
Parameters:
uri | An uri. |
|---|
Returns:
A workspace folder or undefined
openNotebookDocument(uri:Uri):Thenable<NotebookDocument>
openNotebookDocument(notebookType:String, ?content:NotebookData):Thenable<NotebookDocument>
Open a notebook. Will return early if this notebook is already {@link notebook.notebookDocuments loaded}. Otherwise the notebook is loaded and the {@linkcode notebook.onDidOpenNotebookDocument onDidOpenNotebookDocument}-event fires.
Note that the lifecycle of the returned notebook is owned by the editor and not by the extension. That means an {@linkcode notebook.onDidCloseNotebookDocument onDidCloseNotebookDocument}-event can occur at any time after.
Note that opening a notebook does not show a notebook editor. This function only returns a notebook document which can be showns in a notebook editor but it can also be used for other things.
Open an untitled notebook. The editor will prompt the user for a file path when the document is to be saved.
@link NotebookDocument notebook}
Parameters:
uri | The resource to open. |
|---|---|
notebookType | The notebook type that should be used. |
content | The initial contents of the notebook. |
Returns:
A promise that resolves to a {
openTextDocument(uri:Uri):Thenable<TextDocument>
openTextDocument(?options:{language:Null<String>, content:Null<String>}):Thenable<TextDocument>
openTextDocument(fileName:String):Thenable<TextDocument>
Opens a document. Will return early if this document is already open. Otherwise the document is loaded and the {@link workspace.onDidOpenTextDocument didOpen}-event fires.
The document is denoted by an {@link Uri}. Depending on the {@link Uri.scheme scheme} the
following rules apply:
file-scheme: Open a file on disk (openTextDocument(Uri.file(path))). Will be rejected if the file
does not exist or cannot be loaded.
untitled-scheme: Open a blank untitled file with associated path (openTextDocument(Uri.file(path).with({ scheme: 'untitled' }))).
The language will be derived from the file name.
* For all other schemes contributed {@link TextDocumentContentProvider text document content providers} and
{@link FileSystemProvider file system providers} are consulted.
Note that the lifecycle of the returned document is owned by the editor and not by the extension. That means an {@linkcode workspace.onDidCloseTextDocument onDidClose}-event can occur at any time after opening it.
A short-hand for openTextDocument(Uri.file(fileName)).
Opens an untitled text document. The editor will prompt the user for a file
path when the document is to be saved. The options parameter allows to
specify the language and/or the content of the document.
@link TextDocument document}.
Parameters:
uri | Identifies the resource to open. |
|---|---|
fileName | A name of a file on disk. |
options | Options to control how the document will be created. |
Returns:
A promise that resolves to a {
registerFileSystemProvider(scheme:String, provider:FileSystemProvider, options:{isReadonly:Null<Bool>, isCaseSensitive:Null<Bool>}):Disposable
Register a filesystem provider for a given scheme, e.g. ftp.
There can only be one provider per scheme and an error is being thrown when a scheme has been claimed by another provider or when it is reserved.
@link Uri.scheme scheme} the provider registers for. @link Disposable} that unregisters this provider when being disposed.
Parameters:
scheme | The uri-{ |
|---|---|
provider | The filesystem provider. |
options | Immutable metadata about the provider. |
Returns:
A {
registerNotebookSerializer(notebookType:String, serializer:NotebookSerializer, ?options:NotebookDocumentContentOptions):Disposable
Register a {@link NotebookSerializer notebook serializer}.
A notebook serializer must be contributed through the notebooks extension point. When opening a notebook file, the editor will send
the onNotebook:<notebookType> activation event, and extensions must register their serializer in return.
@link Disposable} that unregisters this serializer when being disposed.
Parameters:
notebookType | A notebook. |
|---|---|
serializer | A notebook serialzier. |
options | Optional context options that define what parts of a notebook should be persisted |
Returns:
A {
registerTaskProvider<T>(type:String, provider:TaskProvider<T>):Disposable
Use the corresponding function on the tasks namespace instead
Register a task provider.
@link Disposable} that unregisters this provider when being disposed.
Parameters:
type | The task kind type this provider is registered for. |
|---|---|
provider | A task provider. |
Returns:
A {
registerTextDocumentContentProvider(scheme:String, provider:TextDocumentContentProvider):Disposable
Register a text document content provider.
Only one provider can be registered per scheme.
@link Disposable} that unregisters this provider when being disposed.
Parameters:
scheme | The uri-scheme to register for. |
|---|---|
provider | A content provider. |
Returns:
A {
saveAll(?includeUntitled:Bool):Thenable<Bool>
Save all dirty files.
Parameters:
includeUntitled | Also save files that have been created during this session. |
|---|
Returns:
A thenable that resolves when the files have been saved.
updateWorkspaceFolders(start:Int, deleteCount:Null<Int>, workspaceFoldersToAdd:Rest<{uri:Uri, name:Null<String>}>):Bool
This method replaces deleteCount {@link workspace.workspaceFolders workspace folders} starting at index start
by an optional set of workspaceFoldersToAdd on the vscode.workspace.workspaceFolders array. This "splice"
behavior can be used to add, remove and change workspace folders in a single operation.
If the first workspace folder is added, removed or changed, the currently executing extensions (including the
one that called this method) will be terminated and restarted so that the (deprecated) rootPath property is
updated to point to the first workspace folder.
Use the {@linkcode onDidChangeWorkspaceFolders onDidChangeWorkspaceFolders()} event to get notified when the workspace folders have been updated.
Example: adding a new workspace folder at the end of workspace folders
workspace.updateWorkspaceFolders(workspace.workspaceFolders ? workspace.workspaceFolders.length : 0, null, { uri: ...});Example: removing the first workspace folder
workspace.updateWorkspaceFolders(0, 1);Example: replacing an existing workspace folder with a new one
workspace.updateWorkspaceFolders(0, 1, { uri: ...});It is valid to remove an existing workspace folder and add it again with a different name to rename that folder.
Note: it is not valid to call {@link updateWorkspaceFolders updateWorkspaceFolders()} multiple times without waiting for the {@linkcode onDidChangeWorkspaceFolders onDidChangeWorkspaceFolders()} to fire.
@link WorkspaceFolder workspace folders} from which to start deleting workspace folders.
Parameters:
start | the zero-based location in the list of currently opened { |
|---|---|
deleteCount | the optional number of workspace folders to remove. |
workspaceFoldersToAdd | the optional variable set of workspace folders to add in place of the deleted ones. Each workspace is identified with a mandatory URI and an optional name. |
Returns:
true if the operation was successfully started and false otherwise if arguments were used that would result in invalid workspace folder state (e.g. 2 folders with the same URI).