Skip to content

Commit 6b083b4

Browse files
mjbvzmjbvz
committed
Finalize the WebviewView Api
Fixes microsoft#46585 This new api allows extensions to contribute webviews to the sidebar or panel
1 parent a8581d6 commit 6b083b4

3 files changed

Lines changed: 157 additions & 164 deletions

File tree

‎src/vs/vscode.d.ts‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7127,6 +7127,129 @@ declare module 'vscode' {
71277127
deserializeWebviewPanel(webviewPanel: WebviewPanel, state: T): Thenable<void>;
71287128
}
71297129

7130+
/**
7131+
* A webview based view.
7132+
*/
7133+
export interface WebviewView {
7134+
/**
7135+
* Identifies the type of the webview view, such as `'hexEditor.dataView'`.
7136+
*/
7137+
readonly viewType: string;
7138+
7139+
/**
7140+
* The underlying webview for the view.
7141+
*/
7142+
readonly webview: Webview;
7143+
7144+
/**
7145+
* View title displayed in the UI.
7146+
*
7147+
* The view title is initially taken from the extension `package.json` contribution.
7148+
*/
7149+
title?: string;
7150+
7151+
/**
7152+
* Human-readable string which is rendered less prominently in the title.
7153+
*/
7154+
description?: string;
7155+
7156+
/**
7157+
* Event fired when the view is disposed.
7158+
*
7159+
* Views are disposed when they are explicitly hidden by a user (this happens when a user
7160+
* right clicks in a view and unchecks the webview view).
7161+
*
7162+
* Trying to use the view after it has been disposed throws an exception.
7163+
*/
7164+
readonly onDidDispose: Event<void>;
7165+
7166+
/**
7167+
* Tracks if the webview is currently visible.
7168+
*
7169+
* Views are visible when they are on the screen and expanded.
7170+
*/
7171+
readonly visible: boolean;
7172+
7173+
/**
7174+
* Event fired when the visibility of the view changes.
7175+
*
7176+
* Actions that trigger a visibility change:
7177+
*
7178+
* - The view is collapsed or expanded.
7179+
* - The user switches to a different view group in the sidebar or panel.
7180+
*
7181+
* Note that hiding a view using the context menu instead disposes of the view and fires `onDidDispose`.
7182+
*/
7183+
readonly onDidChangeVisibility: Event<void>;
7184+
7185+
/**
7186+
* Reveal the view in the UI.
7187+
*
7188+
* If the view is collapsed, this will expand it.
7189+
*
7190+
* @param preserveFocus When `true` the view will not take focus.
7191+
*/
7192+
show(preserveFocus?: boolean): void;
7193+
}
7194+
7195+
/**
7196+
* Additional information the webview view being resolved.
7197+
*
7198+
* @param T Type of the webview's state.
7199+
*/
7200+
interface WebviewViewResolveContext<T = unknown> {
7201+
/**
7202+
* Persisted state from the webview content.
7203+
*
7204+
* To save resources, VS Code normally deallocates webview documents (the iframe content) that are not visible.
7205+
* For example, when the user collapse a view or switches to another top level activity in the sidebar, the
7206+
* `WebviewView` itself is kept alive but the webview's underlying document is deallocated. It is recreated when
7207+
* the view becomes visible again.
7208+
*
7209+
* You can prevent this behavior by setting `retainContextWhenHidden` in the `WebviewOptions`. However this
7210+
* increases resource usage and should be avoided wherever possible. Instead, you can use persisted state to
7211+
* save off a webview's state so that it can be quickly recreated as needed.
7212+
*
7213+
* To save off a persisted state, inside the webview call `acquireVsCodeApi().setState()` with
7214+
* any json serializable object. To restore the state again, call `getState()`. For example:
7215+
*
7216+
* ```js
7217+
* // Within the webview
7218+
* const vscode = acquireVsCodeApi();
7219+
*
7220+
* // Get existing state
7221+
* const oldState = vscode.getState() || { value: 0 };
7222+
*
7223+
* // Update state
7224+
* setState({ value: oldState.value + 1 })
7225+
* ```
7226+
*
7227+
* VS Code ensures that the persisted state is saved correctly when a webview is hidden and across
7228+
* editor restarts.
7229+
*/
7230+
readonly state: T | undefined;
7231+
}
7232+
7233+
/**
7234+
* Provider for creating `WebviewView` elements.
7235+
*/
7236+
export interface WebviewViewProvider {
7237+
/**
7238+
* Revolves a webview view.
7239+
*
7240+
* `resolveWebviewView` is called when a view first becomes visible. This may happen when the view is
7241+
* first loaded or when the user hides and then shows a view again.
7242+
*
7243+
* @param webviewView Webview view to restore. The provider should take ownership of this view. The
7244+
* provider must set the webview's `.html` and hook up all webview events it is interested in.
7245+
* @param context Additional metadata about the view being resolved.
7246+
* @param token Cancellation token indicating that the view being provided is no longer needed.
7247+
*
7248+
* @return Optional thenable indicating that the view has been fully resolved.
7249+
*/
7250+
resolveWebviewView(webviewView: WebviewView, context: WebviewViewResolveContext, token: CancellationToken): Thenable<void> | void;
7251+
}
7252+
71307253
/**
71317254
* Provider for text based custom editors.
71327255
*
@@ -8280,6 +8403,40 @@ declare module 'vscode' {
82808403
*/
82818404
export function registerWebviewPanelSerializer(viewType: string, serializer: WebviewPanelSerializer): Disposable;
82828405

8406+
/**
8407+
* Register a new provider for webview views.
8408+
*
8409+
* @param viewId Unique id of the view. This should match the `id` from the
8410+
* `views` contribution in the package.json.
8411+
* @param provider Provider for the webview views.
8412+
*
8413+
* @return Disposable that unregisters the provider.
8414+
*/
8415+
export function registerWebviewViewProvider(viewId: string, provider: WebviewViewProvider, options?: {
8416+
/**
8417+
* Content settings for the webview created for this view.
8418+
*/
8419+
readonly webviewOptions?: {
8420+
/**
8421+
* Controls if the webview element itself (iframe) is kept around even when the view
8422+
* is no longer visible.
8423+
*
8424+
* Normally the webview's html context is created when the view becomes visible
8425+
* and destroyed when it is hidden. Extensions that have complex state
8426+
* or UI can set the `retainContextWhenHidden` to make VS Code keep the webview
8427+
* context around, even when the webview moves to a background tab. When a webview using
8428+
* `retainContextWhenHidden` becomes hidden, its scripts and other dynamic content are suspended.
8429+
* When the view becomes visible again, the context is automatically restored
8430+
* in the exact same state it was in originally. You cannot send messages to a
8431+
* hidden webview, even with `retainContextWhenHidden` enabled.
8432+
*
8433+
* `retainContextWhenHidden` has a high memory overhead and should only be used if
8434+
* your view's context cannot be quickly saved and restored.
8435+
*/
8436+
readonly retainContextWhenHidden?: boolean;
8437+
};
8438+
}): Disposable;
8439+
82838440
/**
82848441
* Register a provider for custom editors for the `viewType` contributed by the `customEditors` extension point.
82858442
*

‎src/vs/vscode.proposed.d.ts‎

Lines changed: 0 additions & 163 deletions
Original file line numberDiff line numberDiff line change
@@ -2090,169 +2090,6 @@ declare module 'vscode' {
20902090
}
20912091
//#endregion
20922092

2093-
2094-
//#region https://github.com/microsoft/vscode/issues/46585
2095-
2096-
/**
2097-
* A webview based view.
2098-
*/
2099-
export interface WebviewView {
2100-
/**
2101-
* Identifies the type of the webview view, such as `'hexEditor.dataView'`.
2102-
*/
2103-
readonly viewType: string;
2104-
2105-
/**
2106-
* The underlying webview for the view.
2107-
*/
2108-
readonly webview: Webview;
2109-
2110-
/**
2111-
* View title displayed in the UI.
2112-
*
2113-
* The view title is initially taken from the extension `package.json` contribution.
2114-
*/
2115-
title?: string;
2116-
2117-
/**
2118-
* Human-readable string which is rendered less prominently in the title.
2119-
*/
2120-
description?: string;
2121-
2122-
/**
2123-
* Event fired when the view is disposed.
2124-
*
2125-
* Views are disposed when they are explicitly hidden by a user (this happens when a user
2126-
* right clicks in a view and unchecks the webview view).
2127-
*
2128-
* Trying to use the view after it has been disposed throws an exception.
2129-
*/
2130-
readonly onDidDispose: Event<void>;
2131-
2132-
/**
2133-
* Tracks if the webview is currently visible.
2134-
*
2135-
* Views are visible when they are on the screen and expanded.
2136-
*/
2137-
readonly visible: boolean;
2138-
2139-
/**
2140-
* Event fired when the visibility of the view changes.
2141-
*
2142-
* Actions that trigger a visibility change:
2143-
*
2144-
* - The view is collapsed or expanded.
2145-
* - The user switches to a different view group in the sidebar or panel.
2146-
*
2147-
* Note that hiding a view using the context menu instead disposes of the view and fires `onDidDispose`.
2148-
*/
2149-
readonly onDidChangeVisibility: Event<void>;
2150-
2151-
/**
2152-
* Reveal the view in the UI.
2153-
*
2154-
* If the view is collapsed, this will expand it.
2155-
*
2156-
* @param preserveFocus When `true` the view will not take focus.
2157-
*/
2158-
show(preserveFocus?: boolean): void;
2159-
}
2160-
2161-
/**
2162-
* Additional information the webview view being resolved.
2163-
*
2164-
* @param T Type of the webview's state.
2165-
*/
2166-
interface WebviewViewResolveContext<T = unknown> {
2167-
/**
2168-
* Persisted state from the webview content.
2169-
*
2170-
* To save resources, VS Code normally deallocates webview documents (the iframe content) that are not visible.
2171-
* For example, when the user collapse a view or switches to another top level activity in the sidebar, the
2172-
* `WebviewView` itself is kept alive but the webview's underlying document is deallocated. It is recreated when
2173-
* the view becomes visible again.
2174-
*
2175-
* You can prevent this behavior by setting `retainContextWhenHidden` in the `WebviewOptions`. However this
2176-
* increases resource usage and should be avoided wherever possible. Instead, you can use persisted state to
2177-
* save off a webview's state so that it can be quickly recreated as needed.
2178-
*
2179-
* To save off a persisted state, inside the webview call `acquireVsCodeApi().setState()` with
2180-
* any json serializable object. To restore the state again, call `getState()`. For example:
2181-
*
2182-
* ```js
2183-
* // Within the webview
2184-
* const vscode = acquireVsCodeApi();
2185-
*
2186-
* // Get existing state
2187-
* const oldState = vscode.getState() || { value: 0 };
2188-
*
2189-
* // Update state
2190-
* setState({ value: oldState.value + 1 })
2191-
* ```
2192-
*
2193-
* VS Code ensures that the persisted state is saved correctly when a webview is hidden and across
2194-
* editor restarts.
2195-
*/
2196-
readonly state: T | undefined;
2197-
}
2198-
2199-
/**
2200-
* Provider for creating `WebviewView` elements.
2201-
*/
2202-
export interface WebviewViewProvider {
2203-
/**
2204-
* Revolves a webview view.
2205-
*
2206-
* `resolveWebviewView` is called when a view first becomes visible. This may happen when the view is
2207-
* first loaded or when the user hides and then shows a view again.
2208-
*
2209-
* @param webviewView Webview view to restore. The serializer should take ownership of this view. The
2210-
* provider must set the webview's `.html` and hook up all webview events it is interested in.
2211-
* @param context Additional metadata about the view being resolved.
2212-
* @param token Cancellation token indicating that the view being provided is no longer needed.
2213-
*
2214-
* @return Optional thenable indicating that the view has been fully resolved.
2215-
*/
2216-
resolveWebviewView(webviewView: WebviewView, context: WebviewViewResolveContext, token: CancellationToken): Thenable<void> | void;
2217-
}
2218-
2219-
namespace window {
2220-
/**
2221-
* Register a new provider for webview views.
2222-
*
2223-
* @param viewId Unique id of the view. This should match the `id` from the
2224-
* `views` contribution in the package.json.
2225-
* @param provider Provider for the webview views.
2226-
*
2227-
* @return Disposable that unregisters the provider.
2228-
*/
2229-
export function registerWebviewViewProvider(viewId: string, provider: WebviewViewProvider, options?: {
2230-
/**
2231-
* Content settings for the webview created for this view.
2232-
*/
2233-
readonly webviewOptions?: {
2234-
/**
2235-
* Controls if the webview element itself (iframe) is kept around even when the view
2236-
* is no longer visible.
2237-
*
2238-
* Normally the webview's html context is created when the view becomes visible
2239-
* and destroyed when it is hidden. Extensions that have complex state
2240-
* or UI can set the `retainContextWhenHidden` to make VS Code keep the webview
2241-
* context around, even when the webview moves to a background tab. When a webview using
2242-
* `retainContextWhenHidden` becomes hidden, its scripts and other dynamic content are suspended.
2243-
* When the view becomes visible again, the context is automatically restored
2244-
* in the exact same state it was in originally. You cannot send messages to a
2245-
* hidden webview, even with `retainContextWhenHidden` enabled.
2246-
*
2247-
* `retainContextWhenHidden` has a high memory overhead and should only be used if
2248-
* your view's context cannot be quickly saved and restored.
2249-
*/
2250-
readonly retainContextWhenHidden?: boolean;
2251-
};
2252-
}): Disposable;
2253-
}
2254-
//#endregion
2255-
22562093
//#region
22572094

22582095
export interface FileSystem {

‎src/vs/workbench/api/common/extHost.api.impl.ts‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -629,7 +629,6 @@ export function createApiFactoryAndRegisterActors(accessor: ServicesAccessor): I
629629
retainContextWhenHidden?: boolean
630630
}
631631
}) {
632-
checkProposedApiEnabled(extension);
633632
return extHostWebviewViews.registerWebviewViewProvider(extension, viewId, provider, options?.webviewOptions);
634633
}
635634
};

0 commit comments

Comments
 (0)