Interface WorkspaceService

The open workspace folders, and where a resource sits among them.

Which folder a resource is in, and how its path is written relative to it, are VS Code's answers: with folders nested the innermost wins, letter case is compared the way the resource's file system compares it, and with more than one folder open a relative path starts with the folder's name — the same text the Explorer shows. Asking VS Code rather than comparing paths here is what keeps a multi-root or remote workspace from being a special case.

Its shape is the workspace capability's, so createFakeWorkspace from /testing stands in for it in a unit test of a feature that takes the service, with no test host around it.

Example

module.commands.handle(Export, {
  inject: { workspace: Workspace },
  execute: async (context, [target], { workspace }) => {
    if (workspace.folderOf(target) === undefined) {
      await context.notify.warn(context.l10n.t('Choose a folder inside the workspace.'));
      return;
    }
    await context.notify.info(
      context.l10n.t('Exported to {0}', workspace.relativePath(target))
    );
  },
});

interface WorkspaceService {
    folderOf(uri: ResourceUri): WorkspaceFolderLike | undefined;
    folders(): readonly WorkspaceFolderLike[];
    onDidChangeFolders(listener: () => void): PlatformRegistration;
    relativePath(uri: WatchedUri, includeFolderName?: boolean): string;
}

Index

Methods

folderOf folders onDidChangeFolders relativePath

Methods

folderOf

folderOf(uri: ResourceUri): WorkspaceFolderLike | undefined
The folder uri is in, the innermost when folders nest, or undefined.
Parameters
- uri: ResourceUri
Returns WorkspaceFolderLike | undefined
- Defined in src/capabilities/workspace/workspace.ts:45

folders

folders(): readonly WorkspaceFolderLike[]
The open folders, in the order VS Code lists them, read when called.

Returns readonly WorkspaceFolderLike[]
- Defined in src/capabilities/workspace/workspace.ts:43

onDidChangeFolders

onDidChangeFolders(listener: () => void): PlatformRegistration
Calls listener after folders are added, removed or changed.

The caller owns the subscription. One still open when the application stops is released with it, so a forgotten one lasts for the session rather than past it.
Parameters
- listener: () => void
Returns PlatformRegistration
- Defined in src/capabilities/workspace/workspace.ts:65

relativePath

relativePath(uri: WatchedUri, includeFolderName?: boolean): string
uri relative to the folder it is in, with / between segments.

A resource in no folder comes back as its file system path. A folder itself is looked up from the directory it sits in, so it is named relative to a folder around that directory, or comes back as its file system path when there is none.
Parameters
- uri: WatchedUri
- OptionalincludeFolderName: boolean
  Start with the folder's name. When omitted, it does exactly when more than one folder is open, as the Explorer does.
Returns string
- Defined in src/capabilities/workspace/workspace.ts:57

Interface WorkspaceService

Example

Index

Methods

Methods

folderOf

Parameters

Returns WorkspaceFolderLike | undefined

folders

Returns readonly WorkspaceFolderLike[]

onDidChangeFolders

Parameters

Returns PlatformRegistration

relativePath

Parameters

Returns string

Settings

On This Page