Microsoft/vscode
1
0
Fork 0
mirror of https://github.com/microsoft/vscode.git synced 2026-04-21 00:59:03 +01:00
Code Issues Packages Projects Releases Wiki Activity

Add more links in webview and custom editor docs

Browse Source 
Makes a pass through to make sure the docs use `@link` in more places
This commit is contained in:
Matt Bierner
2026-01-20 16:24:07 -08:00
parent 7dc2938029
commit 8a633618d7
1 changed files with 38 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

75
src/vscode-dts/vscode.d.ts vendored
View File

@@ -10063,7 +10063,7 @@ declare module 'vscode' {
}
/**
* A panel that contains a webview.
* A panel that contains a {@linkcode Webview}.
*/
export interface WebviewPanel {
/**
@@ -10115,7 +10115,7 @@ declare module 'vscode' {
/**
* Fired when the panel is disposed.
*
* This may be because the user closed the panel or because `.dispose()` was
* This may be because the user closed the panel or because {@linkcode WebviewPanel.dispose dispose} was
* called on it.
*
* Trying to use the panel after it has been disposed throws an exception.
@@ -10128,7 +10128,7 @@ declare module 'vscode' {
* A webview panel may only show in a single column at a time. If it is already showing, this
* method moves it to a new column.
*
* @param viewColumn View column to show the panel in. Shows in the current `viewColumn` if undefined.
* @param viewColumn View column to show the panel in. Shows in the current {@linkcode WebviewPanel.viewColumn} if undefined.
* @param preserveFocus When `true`, the webview will not take focus.
*/
reveal(viewColumn?: ViewColumn, preserveFocus?: boolean): void;
@@ -10138,17 +10138,17 @@ declare module 'vscode' {
*
* This closes the panel if it showing and disposes of the resources owned by the webview.
* Webview panels are also disposed when the user closes the webview panel. Both cases
* fire the `onDidDispose` event.
* fire the {@linkcode onDidDispose} event.
*/
dispose(): any;
}
/**
* Event fired when a webview panel's view state changes.
* Event fired when a {@linkcode WebviewPanel webview panel's} view state changes.
*/
export interface WebviewPanelOnDidChangeViewStateEvent {
/**
* Webview panel whose view state changed.
* {@linkcode WebviewPanel} whose view state changed.
*/
readonly webviewPanel: WebviewPanel;
}
@@ -10283,12 +10283,12 @@ declare module 'vscode' {
*
* To save resources, the editor normally deallocates webview documents (the iframe content) that are not visible.
* For example, when the user collapse a view or switches to another top level activity in the sidebar, the
* `WebviewView` itself is kept alive but the webview's underlying document is deallocated. It is recreated when
* {@linkcode WebviewView} itself is kept alive but the webview's underlying document is deallocated. It is recreated when
* the view becomes visible again.
*
* You can prevent this behavior by setting `retainContextWhenHidden` in the `WebviewOptions`. However this
* increases resource usage and should be avoided wherever possible. Instead, you can use persisted state to
* save off a webview's state so that it can be quickly recreated as needed.
* You can prevent this behavior by setting {@linkcode WebviewOptions.retainContextWhenHidden retainContextWhenHidden} in the {@linkcode WebviewOptions}.
* However this increases resource usage and should be avoided wherever possible. Instead, you can use
* persisted state to save off a webview's state so that it can be quickly recreated as needed.
*
* To save off a persisted state, inside the webview call `acquireVsCodeApi().setState()` with
* any json serializable object. To restore the state again, call `getState()`. For example:
@@ -10311,7 +10311,7 @@ declare module 'vscode' {
}
/**
* Provider for creating `WebviewView` elements.
* Provider for creating {@linkcode WebviewView} elements.
*/
export interface WebviewViewProvider {
/**
@@ -10335,7 +10335,7 @@ declare module 'vscode' {
*
* Text based custom editors use a {@linkcode TextDocument} as their data model. This considerably simplifies
* implementing a custom editor as it allows the editor to handle many common operations such as
* undo and backup. The provider is responsible for synchronizing text changes between the webview and the `TextDocument`.
* undo and backup. The provider is responsible for synchronizing text changes between the webview and the {@linkcode TextDocument}.
*/
export interface CustomTextEditorProvider {
@@ -10345,13 +10345,12 @@ declare module 'vscode' {
* This is called when a user first opens a resource for a `CustomTextEditorProvider`, or if they reopen an
* existing editor using this `CustomTextEditorProvider`.
*
*
* @param document Document for the resource to resolve.
*
* @param webviewPanel The webview panel used to display the editor UI for this resource.
*
* During resolve, the provider must fill in the initial html for the content webview panel and hook up all
* the event listeners on it that it is interested in. The provider can also hold onto the `WebviewPanel` to
* the event listeners on it that it is interested in. The provider can also hold onto the {@linkcode WebviewPanel} to
* use later for example in a command. See {@linkcode WebviewPanel} for additional details.
*
* @param token A cancellation token that indicates the result is no longer needed.
@@ -10399,7 +10398,7 @@ declare module 'vscode' {
*
* This is invoked by the editor when the user undoes this edit. To implement `undo`, your
* extension should restore the document and editor to the state they were in just before this
* edit was added to the editor's internal edit stack by `onDidChangeCustomDocument`.
* edit was added to the editor's internal edit stack by {@linkcode CustomEditorProvider.onDidChangeCustomDocument}.
*/
undo(): Thenable<void> | void;
@@ -10408,7 +10407,7 @@ declare module 'vscode' {
*
* This is invoked by the editor when the user redoes this edit. To implement `redo`, your
* extension should restore the document and editor to the state they were in just after this
* edit was added to the editor's internal edit stack by `onDidChangeCustomDocument`.
* edit was added to the editor's internal edit stack by {@linkcode CustomEditorProvider.onDidChangeCustomDocument}.
*/
redo(): Thenable<void> | void;
@@ -10440,7 +10439,7 @@ declare module 'vscode' {
/**
* Unique identifier for the backup.
*
* This id is passed back to your extension in `openCustomDocument` when opening a custom editor from a backup.
* This id is passed back to your extension in {@linkcode CustomReadonlyEditorProvider.openCustomDocument openCustomDocument} when opening a custom editor from a backup.
*/
readonly id: string;
@@ -10505,10 +10504,10 @@ declare module 'vscode' {
* Create a new document for a given resource.
*
* `openCustomDocument` is called when the first time an editor for a given resource is opened. The opened
* document is then passed to `resolveCustomEditor` so that the editor can be shown to the user.
* document is then passed to {@link resolveCustomEditor} so that the editor can be shown to the user.
*
* Already opened `CustomDocument` are re-used if the user opened additional editors. When all editors for a
* given resource are closed, the `CustomDocument` is disposed of. Opening an editor at this point will
* Already opened {@linkcode CustomDocument CustomDocuments} are re-used if the user opened additional editors. When all editors for a
* given resource are closed, the {@linkcode CustomDocument CustomDocuments} is disposed of. Opening an editor at this point will
* trigger another call to `openCustomDocument`.
*
* @param uri Uri of the document to open.
@@ -10558,18 +10557,18 @@ declare module 'vscode' {
* anything from changing some text, to cropping an image, to reordering a list. Your extension is free to
* define what an edit is and what data is stored on each edit.
*
* Firing `onDidChange` causes the editors to be marked as being dirty. This is cleared when the user either
* saves or reverts the file.
* Firing {@linkcode CustomEditorProvider.onDidChangeCustomDocument onDidChangeCustomDocument} causes the
* editors to be marked as being dirty. This is cleared when the user either saves or reverts the file.
*
* Editors that support undo/redo must fire a `CustomDocumentEditEvent` whenever an edit happens. This allows
* Editors that support undo/redo must fire a {@linkcode CustomDocumentEditEvent} whenever an edit happens. This allows
* users to undo and redo the edit using the editor's standard keyboard shortcuts. The editor will also mark
* the editor as no longer being dirty if the user undoes all edits to the last saved state.
*
* Editors that support editing but cannot use the editor's standard undo/redo mechanism must fire a `CustomDocumentContentChangeEvent`.
* Editors that support editing but cannot use the editor's standard undo/redo mechanism must fire a {@linkcode CustomDocumentContentChangeEvent}.
* The only way for a user to clear the dirty state of an editor that does not support undo/redo is to either
* `save` or `revert` the file.
*
* An editor should only ever fire `CustomDocumentEditEvent` events, or only ever fire `CustomDocumentContentChangeEvent` events.
* An editor should only ever fire {@linkcode CustomDocumentEditEvent} events, or only ever fire {@linkcode CustomDocumentContentChangeEvent} events.
*/
readonly onDidChangeCustomDocument: Event<CustomDocumentEditEvent<T>> | Event<CustomDocumentContentChangeEvent<T>>;
@@ -10579,14 +10578,14 @@ declare module 'vscode' {
* This method is invoked by the editor when the user saves a custom editor. This can happen when the user
* triggers save while the custom editor is active, by commands such as `save all`, or by auto save if enabled.
*
* To implement `save`, the implementer must persist the custom editor. This usually means writing the
* file data for the custom document to disk. After `save` completes, any associated editor instances will
* no longer be marked as dirty.
* The implementer must persist the custom editor. This usually means writing the
* file data for the custom document to disk. After {@linkcode saveCustomDocument} completes, any associated
* editor instances will no longer be marked as dirty.
*
* @param document Document to save.
* @param cancellation Token that signals the save is no longer required (for example, if another save was triggered).
*
* @returns Thenable signaling that saving has completed.
* @returns A {@linkcode Thenable} that saving has completed.
*/
saveCustomDocument(document: T, cancellation: CancellationToken): Thenable<void>;
@@ -10594,7 +10593,7 @@ declare module 'vscode' {
* Save a custom document to a different location.
*
* This method is invoked by the editor when the user triggers 'save as' on a custom editor. The implementer must
* persist the custom editor to `destination`.
* persist the custom editor to {@linkcode destination}.
*
* When the user accepts save as, the current editor is be replaced by an non-dirty editor for the newly saved file.
*
@@ -10602,7 +10601,7 @@ declare module 'vscode' {
* @param destination Location to save to.
* @param cancellation Token that signals the save is no longer required.
*
* @returns Thenable signaling that saving has completed.
* @returns A {@linkcode Thenable} signaling that saving has completed.
*/
saveCustomDocumentAs(document: T, destination: Uri, cancellation: CancellationToken): Thenable<void>;
@@ -10612,30 +10611,30 @@ declare module 'vscode' {
* This method is invoked by the editor when the user triggers `File: Revert File` in a custom editor. (Note that
* this is only used using the editor's `File: Revert File` command and not on a `git revert` of the file).
*
* To implement `revert`, the implementer must make sure all editor instances (webviews) for `document`
* The implementer must make sure all editor instances (webviews) for {@linkcode document}
* are displaying the document in the same state is saved in. This usually means reloading the file from the
* workspace.
*
* @param document Document to revert.
* @param cancellation Token that signals the revert is no longer required.
*
* @returns Thenable signaling that the change has completed.
* @returns A {@linkcode Thenable} signaling that the revert has completed.
*/
revertCustomDocument(document: T, cancellation: CancellationToken): Thenable<void>;
/**
* Back up a dirty custom document.
*
* Backups are used for hot exit and to prevent data loss. Your `backup` method should persist the resource in
* Backups are used for hot exit and to prevent data loss. Your {@linkcode backupCustomDocument} method should persist the resource in
* its current state, i.e. with the edits applied. Most commonly this means saving the resource to disk in
* the `ExtensionContext.storagePath`. When the editor reloads and your custom editor is opened for a resource,
* your extension should first check to see if any backups exist for the resource. If there is a backup, your
* extension should load the file contents from there instead of from the resource in the workspace.
*
* `backup` is triggered approximately one second after the user stops editing the document. If the user
* rapidly edits the document, `backup` will not be invoked until the editing stops.
* {@linkcode backupCustomDocument} is triggered approximately one second after the user stops editing the document. If the user
* rapidly edits the document, {@linkcode backupCustomDocument} will not be invoked until the editing stops.
*
* `backup` is not invoked when `auto save` is enabled (since auto save already persists the resource).
* {@linkcode backupCustomDocument} is not invoked when `auto save` is enabled (since auto save already persists the resource).
*
* @param document Document to backup.
* @param context Information that can be used to backup the document.
@@ -10643,6 +10642,8 @@ declare module 'vscode' {
* extension to decided how to respond to cancellation. If for example your extension is backing up a large file
* in an operation that takes time to complete, your extension may decide to finish the ongoing backup rather
* than cancelling it to ensure that the editor has some valid backup.
*
* @returns A {@linkcode Thenable} signaling that the backup has completed.
*/
backupCustomDocument(document: T, context: CustomDocumentBackupContext, cancellation: CancellationToken): Thenable<CustomDocumentBackup>;
}