@microsoft/sp-webpart-base
Version:
SharePoint Framework support for building web parts
2,026 lines • 83.8 kB
TypeScript
/**
* SharePoint Framework support for building web parts.
*
* @remarks
* This package defines the APIs used by developers to create a custom web part.
* A web part is a reusable visual object that a page author can add to their content,
* and customize using a property pane. Examples of web parts include an embedded
* video player, a map, a group calendar, a chart, etc.
*
* @packagedocumentation
*/
/// <reference types="office-js" />
import { BaseComponent } from '@microsoft/sp-component-base';
import { BaseComponentContext } from '@microsoft/sp-component-base';
import { DisplayMode } from '@microsoft/sp-core-library';
import type { HttpClient } from '@microsoft/sp-http';
import type { IA11yCheckResult } from '@msinternal/sp-a11y-checker-util';
import type { IAdaptiveCardExtensionManifest } from '@microsoft/sp-module-interfaces';
import type { IClientSideWebPartManifest } from '@microsoft/sp-module-interfaces';
import type { IClientSideWebPartManifestInstance } from '@microsoft/sp-module-interfaces';
import type { _IComponentContextParameters } from '@microsoft/sp-component-base';
import type { _IComponentPosition } from '@microsoft/sp-component-base';
import type { IComponentPropertyMetadata } from '@microsoft/sp-component-base';
import type { _IConfigurableOptionsController } from '@microsoft/sp-property-pane';
import type { ILoaderConfiguration } from '@msinternal/copilot-common';
import type { _IPropertyPaneConsumer } from '@microsoft/sp-property-pane';
import type { IPropertyPaneCustomFieldProps as IPropertyPaneCustomFieldProps_2 } from '@microsoft/sp-property-pane';
import type { _IPropertyPaneData } from '@microsoft/sp-property-pane';
import type { IPropertyPaneField as IPropertyPaneField_2 } from '@microsoft/sp-property-pane';
import { IReadonlyTheme } from '@microsoft/sp-component-base';
import type { IRenderProps } from '@msinternal/sp-renderable-components-base';
import { ISerializedServerProcessedData } from '@microsoft/sp-component-base';
import type { ISpPageContext } from '@msinternal/odsp-datasources/lib/interfaces/ISpPageContext';
import type { ITopActions } from '@microsoft/sp-top-actions';
import type { LaunchOrigin } from '@msinternal/copilot-common/lib/interfaces/ICopilotTelemetryExtraData';
import type * as microsoftTeams from '@microsoft/teams-js-v2';
import type { PageContext } from '@microsoft/sp-page-context';
import type { _PropertyPaneAction as _PropertyPaneAction_2 } from '@microsoft/sp-property-pane';
import type { _PropertyPaneLifeCycleEvent } from '@microsoft/sp-property-pane';
import { ServiceKey } from '@microsoft/sp-core-library';
import { ServiceScope } from '@microsoft/sp-core-library';
import { SPEvent } from '@microsoft/sp-core-library';
import { SPEventArgs } from '@microsoft/sp-core-library';
import type { SPHttpClient } from '@microsoft/sp-http';
import type * as SPPropertyPane from '@microsoft/sp-property-pane';
import { Version } from '@microsoft/sp-core-library';
/* Excluded from this release type: _AdaptiveCardExtensionWidthCalculator */
/* Excluded from this release type: _audienceFormServiceKey */
/**
* This abstract class implements the the base functionality for a client-side web part. Every client-side web part
* needs to inherit from this class.
*
* @remarks
* Along with the base functionality, this class provides some APIs that can be
* used by the web part. These APIs fall in two catagories.
*
* The first category of APIs provide data and functionality. Example, the web part context (i.e. this.context). This
* API should be used to access contextual data relevant to this web part instance.
*
* The second category of APIs provide a base implementation for the web part lifecycle and can be overridden for an
* updated implementation. The render() API is the only API that is mandatory to be implemented/overridden by a web
* part. All other life cycle APIs have a base implementation and can be overridden based on the needs of the web part.
* Please refer to the documentation of the individual APIs to make the right decision.
*
* @public
*/
export declare abstract class BaseClientSideWebPart<TProperties extends {}> extends BaseWebPart<TProperties> {
/**
* {@inheritDoc @microsoft/sp-component-base#BaseComponent.context}
*/
readonly context: WebPartContext;
private _firstTimeRenderPromises;
private _renderedOnce;
private _logSource;
/**
* Container width allocated for the web part
*/
private _width;
/**
* A timer guard, QOS monitor and resolver delegate for the Async render scenarios. An async render scenario
* is one in which the web part is rendering an IFRAME OR fetching async data outside of the onInit API
* OR rendering an image tag. In these cases much of the web part rendering lifecycle is controlled by external
* factors once the IFRAME is created or the data fetch request is sent OR the image tag is set. The web part
* needs to call the renderCompleted API once the final rendering is complete and data is displayed.
*/
private _asyncRenderGuardTimer;
private _asyncRenderQosMonitor;
private _renderPromiseResolver;
private _renderPromiseRejecter;
private _asyncRenderCompleteCalled;
private _asyncRenderCompleteDidUpdate;
/**
* Whether the web part is visible.
*/
private _isVisible;
/**
* Theme Provider to handle theme changes
*/
private _internalThemeProvider;
/**
* Current theme
*/
private _internalThemeVariant;
private _internalIsDisposing;
/**
* Time when syncRender is finished.
*/
private _syncRenderTime;
/**
* Constructor for the BaseClientSideWebPart class.
*
* @remarks
* It is highly recommended that the web part use the `onInit()` API to perform any web part specific
* initialization. Most of the web part features like this.context and `this.properties` are not
* available to be used before the the `onInit()` part of the web part loading lifecycle.
*/
constructor();
/**
* This property is a pointer to the root DOM element of the web part. This is a DIV element and contains the whole
* DOM subtree of the web part.
*
* @readonly
*/
protected get domElement(): HTMLElement;
/**
* This property returns the width of the container for the web part.
* @returns Width (in pixels) of the container for the web part.
*
* @remarks
* Web parts should utilize this property to perform operations such as any conditional styling of components
* based on the initial available width for the web part.
* @readonly
*/
protected get width(): number;
/**
* This property indicates whether the web part has been rendered once or not. After the first time rendering,
* the value of this property is always true until a full re-render of the web part happens.
*
* @readonly
*/
protected get renderedOnce(): boolean;
/**
* This property indicates whether the web part was rendered from the persisted data (serialized state from the
* last time that the web part was saved) or not.
*
* @remarks
* Example: When web part is added for the first time using toolbox then the value is false.
*
* @readonly
*/
protected get renderedFromPersistedData(): boolean;
/**
* This property indicates whether a web part can open a popup on initial render.
*
* @remarks
* In some environments the host
* re-renders the web parts frequently, and therefore opening popups during render will cause popups to open
* repeatedly, which is a poor user experience. As an example, the classic SharePoint pages perform postbacks
* causing the page to re-render on all button clicks.
*
* If a web part needs to open a popup on render, it should use this API before opening the popup. If this API
* returns false, the web part should not open popup on initial render. Some web parts that open popups during
* render are the document embed web part that pops up the file picker on initial render, embedded video web part
* that pops up the PropertyPane on initial render.
*
* @readonly
*/
protected get canOpenPopupOnRender(): boolean;
/**
* Indicates whether the web part is rendering in Async mode.
*
* @remarks
* If the web part overrides this field to return true, then it needs to call renderCompleted API
* after the web part rendering is complete.
*
* The default value is false.
*
* @virtual
*/
protected get isRenderAsync(): boolean;
/* Excluded from this release type: isVisible */
/* Excluded from this release type: isVisible */
/* Excluded from this release type: _isDisposing */
/* Excluded from this release type: _internalOnAfterResize */
/* Excluded from this release type: _internalFirstTimeRender */
/* Excluded from this release type: _internalSetDisplayMode */
/* Excluded from this release type: _internalTranspile */
/* Excluded from this release type: _internalInitialize */
/* Excluded from this release type: _internalDispose */
/* Excluded from this release type: onTranspile */
/**
* This API is called to render the web part. There is no base implementation of this API and the web part is
* required to override this API.
*/
protected abstract render(): void;
/**
* This API should be called by web parts that perform Async rendering. Those web part are required to override
* the isRenderAsync API and return true. One such example is web parts that render content in an IFrame. The
* web part initiates the IFrame rendering in the `render()` API but the actual rendering is complete only after
* the iframe loading completes.
*
* @param error - error object indicating async render has completed with an error
* @param didUpdate - used to override end performance time with sync render time
*/
protected renderCompleted(error?: Error, didUpdate?: boolean): void;
/**
* This event method is called when the display mode of a web part is changed.
*
* @remarks
* The default implementation of this API calls
* the web part render method to re-render the web part with the new display mode. If a web part developer does not
* want a full re-render to happen on display mode change, they can override this API and perform specific updates
* to the web part DOM to switch its display mode.
*
* If the web part is initialized or re-initialized when switching to a different display mode then this
* lifecycle method is not called. Example: SharePoint Site Page.
*
* @param oldDisplayMode - The old display mode.
*
* @virtual
*/
protected onDisplayModeChanged(oldDisplayMode: DisplayMode): void;
/**
* This API should be used to refresh the contents of the PropertyPane.
*
* @remarks
* This API is called at the end of the web part lifecycle on a page. It should be used to dispose any local
* resources (i.e. DOM elements) that the web part is holding onto. This API is expected to be called in scenarios
* like page navigation i.e. the host is transitioning from one page to another and disposes the page that is being
* transitioned out.
*
* @virtual
*/
protected onDispose(): void;
/**
* This API is invoked when the web part container dom element width is changed, e.g. when the browser
* browser window is resized and when the property pane is toggled open/closed.
*
* @param newWidth - Width (in pixels) of the container for the web part after the resize event.
* @remarks
* Web parts should utilize this method to perform operations such as potentially re-rendering components
* based on the new available width for the web part.
*
* @virtual
*/
protected onAfterResize(newWidth: number): void;
/**
* This API is called when a theme is initialized or changed on the page or for the current section.
* @param theme - New theme for the page or section
* @remarks
* Developers sould not call render in overridden method. It can lead to unpredicted re-flow of the web part.
* render will be called from the base class when needed.
*
* @virtual
*/
protected onThemeChanged(theme: IReadonlyTheme | undefined): void;
/**
* This API should be used to render an error message in the web part display area. Also logs the error message
* using the trace logger.
*
* @param error - An error object containing the error message to render.
*/
protected renderError(error: Error): void;
/**
* This API should be used to clear the error message from the web part display area.
*/
protected clearError(): void;
/* Excluded from this release type: _refresh */
/* Excluded from this release type: _dynamicPropertyRefresh */
/**
* Waits for all render promises to resolve before disposing.
*/
private _disposeAfterRenderPromises;
/* Excluded from this release type: _getExtendedWidthCacheKey */
/**
* The actual initialization and rendering of the Web part starts when it is close enough
* to the Viewport
*/
private _onInViewport;
/**
* Wraps render to ensure any type of rendering has access to the latest context
* to provide the most accurate accessible info to screen readers.
*/
private _renderWithAccessibleTitle;
/**
* Start async guard timer. This timer is to help avoid losing performance markers for a web part
* that renders asynchronously but does not call the `renderCompleted` API;
*/
private _startAsyncRenderGuardTimer;
/**
* Render completed.
*
* @param didUpdate - used to override end performance time with sync render time.
*/
private _renderCompleted;
private _handleAsyncRenderFailed;
/**
* Async render timed out. Log error information and
*/
private _asyncRenderTimeout;
private _logAsyncRenderError;
private _clearAsyncRenderGuardTimer;
/**
* This is called for every web part whether sync or async once rendering is completed.
*
* @param error - error object indicating asycn render has completed with an error
* @param didUpdate - used to override end performance time with sync render time.
*/
private _resolveOrRejectOnRenderPromise;
private _clearRenderPromises;
private _internalHandleThemeChangedEvent;
}
/**
* This abstract class implements the UI-agnostic base functionality for a client-side web part.
* The purpose is to allow a common core between 2D and MR WebParts.
*
* @privateRemarks
* The _refresh() and _dynamicPropertyRefresh() API are the only API that are
* mandatory to be implemented by our base WebPart classes.
*
* @public
*/
export declare abstract class BaseWebPart<TProperties extends {}> extends BaseComponent implements _IPropertyPaneConsumer {
/**
* {@inheritDoc @microsoft/sp-component-base#BaseComponent.context}
*/
readonly context: BaseWebPartContext;
/* Excluded from this release type: _renderedFromPersistedData */
private _displayMode;
private _properties;
private _initialized;
/**
* Keep a copy of the properties to be used for discard in non-reactive mode and this new set
* of `properties('_backUpProperties')` is what will be persisted until the apply button is clicked.
*/
private _backupProperties;
private _previousState;
private _baseLogSource;
private _title;
private _modifiedByGraph;
private _description;
private _iconImageUrl;
private _audiences;
private _hideOn;
/**
* It makes sure we only log edit events once during one editing session.
*/
private _hasEditLogged;
/**
* Cache init properties value, it would be used to check whether web part has been changed or not.
*/
private _initPropertiesSnapshot;
private _loadPropertyPaneResourcesPromise;
private _emptyResolvedPromise;
/**
* This property points to the preview image for the web part. The base implementation returns undefined. Web parts
* that want to provide a valid preview image url need to override this API. The preview image url can be used to
* create a preview of the web part or of the page on which the web part is present.
* virtual
*/
get previewImageUrl(): string | undefined;
/**
* This property is the current display mode of the web part.
*
* @readonly
*/
get displayMode(): DisplayMode;
/* Excluded from this release type: modifiedByGraph */
/**
* The value of this property is stored in the serialized data of the web part to allow developers to manage
* versioning of their web part. The default version is 1.0
*/
protected get dataVersion(): Version;
/**
* This property is the pointer to the custom property bag of the web part.
*
* @readonly
*/
protected get properties(): TProperties;
/**
* This property defines metadata for the web part property bag. The metadata can help SharePoint understand
* the content of the properties better and perform relevant services on the data.
* virtual
*
* @remarks
* See {@link IWebPartPropertiesMetadata} for more information about how to define metadata
*/
protected get propertiesMetadata(): IWebPartPropertiesMetadata | undefined;
/**
* This property is used to change the web part's property pane interaction from Reactive to NonReactive.
* virtual
*
* @remarks
* The default behavior is Reactive.
*
* Reactive implies that changes made in the PropertyPane are transmitted to the web part instantly and the user can
* see instant updates. This helps the page creator get instant feedback and decide if they should keep the new
* configuration changes or not.
*
* NonReactive implies that the configuration changes are transmitted to the web part only after "Apply" PropertyPane
* button is clicked.
*/
protected get disableReactivePropertyChanges(): boolean;
/**
* This property points to the accessible title of web part made available to screen readers. The base implementation
* returns that default title in the manifest. Web parts that want to provide more descriptive title containing
* contextual information need to override this API.
* virtual
*/
protected get accessibleTitle(): string;
/**
* Title of the WebPart
*
* @readonly
*/
protected get title(): string;
/* Excluded from this release type: iconImageUrl */
/**
* Description of the WebPart
*
* @readonly
*/
protected get description(): string;
/* Excluded from this release type: audiences */
/* Excluded from this release type: hideOn */
/**
* This property is a pointer to the current set of properties which are already or needs to be persisted.
*
* @readonly
*/
private get _persistedProperties();
/**
* Constructor for the `BaseWebPart` class.
*
* @remarks
* It is highly recommended that the web part use the OnInit API to perform any web part specific initialization.
* Most of the web part features like this.context and this.properties are not available to be used before the
* the onInit part of the web part loading lifecycle.
*/
constructor();
/* Excluded from this release type: _getPropertyPaneData */
/* Excluded from this release type: _loadPropertyPaneResources */
/* Excluded from this release type: _onPropertyPaneFieldChanged */
/* Excluded from this release type: _onPropertyPaneLifeCycleEvent */
/* Excluded from this release type: _isPropertyPaneReactive */
/* Excluded from this release type: _internalSerialize */
/* Excluded from this release type: _internalDispose */
/* Excluded from this release type: _internalOnAfterResize */
/* Excluded from this release type: _internalSetWebPartData */
/* Excluded from this release type: _internalSetDisplayMode */
/* Excluded from this release type: _internalSetDirtyBit */
/* Excluded from this release type: _internalInitialize */
/* Excluded from this release type: _internalDeserialize */
/**
* Returns the configuration for this webpart's top actions or undefined if the webpart
* doesn't support top actions.
*/
getTopActionsConfiguration(): ITopActions | undefined;
/* Excluded from this release type: _checkA11y */
/* Excluded from this release type: _preOnClickA11yResult */
/**
* This event method is called when the web part is initialized.
* virtual
*
* @remarks
* This API should be overridden to perform long running operations e.g. data fetching from a remote service before
* the initial rendering of the web part. The loading indicator is displayed during the lifetime of this method.
* This API is called only once during the lifecycle of a web part.
*/
protected onInit(): Promise<void>;
/**
* This event method is called when the display mode of a web part is changed.
* virtual
*
* @remarks
* The default implementation of this API calls
* the web part render method to re-render the web part with the new display mode. If a web part developer does not
* want a full re-render to happen on display mode change, they can override this API and perform specific updates
* to the web part DOM to switch its display mode.
*
* If the web part is initialized or re-initialized when switching to a different display mode then this
* lifecycle method is not called. Example: SharePoint Site Page.
*
* @param oldDisplayMode - The old display mode.
*/
protected onDisplayModeChanged(oldDisplayMode: DisplayMode): void;
/**
* This event method is called before the web part is serialized.
* virtual
*
* @remarks
* The default implementation is a no-op. The serialization
* process serializes the web part property bag i.e. this.properties. This API gives the web part a chance to
* update it's property bag before the serialization happens. Some web part's may keep their state other objects
* or even in the DOM. If a web part needs to persist some of that state, it needs to override this API and update
* the web part property bag to the latest state. If a web part updates the property bag with invalid property
* values, those will get persisted. So that should be avoided. The web part property bag should always contain
* valid property values.
*/
protected onBeforeSerialize(): void;
/**
* This API is called after the web part is deserialized to an object, right before the property bag is populated.
* virtual
*
* @remarks
* The default implementation is a no-op. A web part developer can override this API if the deserialized object
* does not fully reflect the initial state of the property bag. This gives the web part developer a chance to
* populate the property bag right after the data is deserialized to an object.
*
* An important scenario to use deserialize is upgrading. An upgraded web part may load the data
* that was serialized by an older version of the web part that supported a different schema of the property bag,
* resulting the deserialized object to be inconsistent with the current schema of the property bag. The developer
* can use `onAfterDeserialize` to check the dataVersion and fix the property bag.
*
* @param deserializedObject - The object deserialized from the stored data. Note that the schema of this object
* is not necessarily consistent with the current property bag, because the serialization could have been done by
* an older version of the web part
* @param dataVersion - The data version of the stored data being deserialized. You can use this value to determine
* if the data was serialized by an older web part. Web parts can define their data version by overriding the
* dataVersion property.
*
* @returns The property bag of the web part
*/
protected onAfterDeserialize(deserializedObject: any, dataVersion: Version): TProperties;
/**
* This API enables asynchronous loading of property pane related resources of the web part.
* @virtual
*
* @remarks
* If not overridden by the web part, base web part resolves the promise immediately.
*
* This method is called before any property pane APIs are called.
* Other property pane APIs cannot be called until this promise is resolved.
* No other property pane related events are raised except 'PropertyPaneConfigurationComplete'.
*
* 'PropertyPaneConfigurationComplete' event can be raised to clean up any pending resources
* including 'loadPropertyPaneResources' promise.
*/
protected loadPropertyPaneResources(): Promise<void>;
/**
* This API is used to ger the configuration to build the property pane for the web part. If the web part wants
* to use the PropertyPane for configuration, this API needs to be overridden and the web part needs to return
* the configuration for the PropertyPane.
*
* This API is not invoked until the 'loadPropertyPaneResources' promise is resolved.
*
* See IPropertyPane and other PropertyPane integration wiki documentation for more details.
* virtual
*/
protected getPropertyPaneConfiguration(): IPropertyPaneConfiguration;
/* Excluded from this release type: getDetailsPaneConfiguration */
/**
* This API should be used to refresh the contents of the PropertyPane.
* virtual
*
* @remarks
* This API is called at the end of the web part lifecycle on a page. It should be used to dispose any local
* resources (i.e. DOM elements) that the web part is holding onto. This API is expected to be called in scenarios
* like page navigation i.e. the host is transitioning from one page to another and disposes the page that is being
* transitioned out.
*/
protected onDispose(): void;
/**
* This API is invoked after updating the new value of the property in the property bag when the PropertyPane
* is being used in Reactive mode.
* virtual
*
* @param propertyPath - JSON path of the property in the property bag.
* In the case of custom field, if no target property is provided then a custom value is assigned,
* which will be in the form of `__CustomField_<key provided when the custom field is created>`.
* @param oldValue - Old value of the property.
* This value could be undefined/empty in the case of custom field.
* @param newValue - New value of the property.
* This value could be undefined/empty in the case of custom field.
*/
protected onPropertyPaneFieldChanged(propertyPath: string, oldValue: any, newValue: any): void;
/**
* This event method is invoked when the configuration starts on the PropertyPane.
* virtual
*
* @remarks
* This event method is invoked in the following cases:
*
* - When the PropertyPane is opened.
*
* - When the user switches web parts then the new web part gets this event.
*/
protected onPropertyPaneConfigurationStart(): void;
/**
* This API is invoked when the configuration is completed on the PropertyPane.
* virtual
*
* @remarks
* This event method is invoked in the following cases:
*
* - When the CONFIGURATION_COMPLETE_TIMEOUT((currently the value is 5 secs) elapses after the last change.
*
* - When user clicks the "X" (close) button before the CONFIGURATION_COMPLETE_TIMEOUT elapses.
*
* - When user clicks the 'Apply' button before the CONFIGURATION_COMPLETE_TIMEOUT elapses.
*
* - When the user switches web parts then the current web part gets this event.
*/
protected onPropertyPaneConfigurationComplete(): void;
/**
* This API is invoked after the changes made on the PropertyPane are applied when the PropertyPane is used in
* Non-Reactive mode. This API is not invoked when the PropertyPane is used in Reactive mode.
* virtual
*/
protected onAfterPropertyPaneChangesApplied(): void;
/**
* This API is invoked when the PropertyPane is rendered.
* virtual
* @privateRemarks
* From framework standpoint, we do not want to allow this event handler to be passed in, and trigger it.
* This api should be deprecated and then removed as part of refactoring.
*/
protected onPropertyPaneRendered(): void;
/* Excluded from this release type: onAfterPropertiesUpdatedExternally */
/* Excluded from this release type: _internalGetData */
/* Excluded from this release type: _refresh */
/* Excluded from this release type: _dynamicPropertyRefresh */
/* Excluded from this release type: _getDefaultAccessibleTitle */
/* Excluded from this release type: _onPropertyPaneChangesApplied */
/**
* This method consumes the properties object from the serialized data and re-applies
* the field values from the serverProcessedContent. This process will result in the
* properties bag as it was when the serialization happened.
*/
private _reInstateServerProcessedData;
/**
* Iterates and validates each metadata property before calling metadata processor.
*
* @param metadataProcessor - Callback handler to to process validated metadata.
* @param properties - Optional properties to process instead of default this.properties
*/
private _forEachPropertyWithMetaData;
/**
* Validates path and iterate over one or multiple wildcard paths
*
* @param propPath - Original property path provided in metadata
* @param properties - Properties to look for the given path.
* @param propertyPathHandler - Handler to process validated and fixed path
*/
private _validateAndIteratePath;
/**
* Operations to be done after the property bag is updated.
*
* @param shouldRefresh - Indicating whether web part needs to be shouldRefresh or not.
*/
private _afterPropertyUpdated;
/**
* Fixes up a property pane configuration to use dynamic data. This happens in-place.
* The fix-up consists on adding the necessary hooks to the web part that are required,
* like the dynamic data provider, the render function and the object it refers to.
*
* @param configuration - Property pane configuration to fix up.
*/
private _fixUpDynamicDataConfiguration;
/**
* Adds a new group with an audiences picker to the first page of the property pane configuration.
* This happens in-place.
*
* @param configuration - Property pane configuration to add the audience targeting picker group to
*/
private _addAudienceTargetingConfiguration;
/**
* Adds "Visibility" group (including "Show in mobile and email" toggle) to property pane.
*
* @param configuration - Property pane configuration to add the group / toggle to.
*/
private _addVisibilityConfiguration;
/**
* The serializer for the exposed part of the web part data
*
* @privateRemarks
* This serialize API is a public candidate for post-GA (after removing the input parameter)
*/
private _serialize;
/**
* This function serializes the Dynamic Data objects from the web part properties into the serialized web part data.
*
* If there is a property "myDynamicProperty" in the property bag that points to `"PageContext:user"`,
* the serialized data is updated as the following:
* ```
* serializedData = {
* dynamicDataPaths: {
* "myDynamicProperty": "PageContext:user"
* }
* }
* ```
*/
private _serializeDynamicData;
/**
* This function deserializes the Dynamic Data objects from serialized web part data into web part properties.
*
* If the serializedData has a "dynamicDataPaths" or "dynamicDataValues" property,
* it creates DynamicData objects for it.
*
* Example:
* ```
* serializedData = {
* dynamicDataPaths: {
* "myDynamicProperty": "PageContext:user"
* }
* }
* ```
*
* This will create a property "myDynamicProperty" in the web parts properties, with a new DynamicData object that
* points at "PageContext:user"
*/
private _deserializeDynamicData;
/**
* For each property in the serialized properties of the web part, we check if the property is declared
* as dynamicProperty in the properties metadata of the web part.
* - If yes, then we check
* - if the value of it is an instance of DynamicProperty
* - If No, then we create and assign a DynamicProperty with the type given specified in the
* 'dynamicPropertyType' property
* - else, it's a no-op.
* - If no, then it's a no-op
*
* While creating the DynamicProperty, we use the pre-configured value associated with that property from
* the web part's property bag as the default value.
* @param deSerializedProperties - deserialized properties of the web part.
*/
private _initializeDynamicPropertiesIfRequired;
/**
* Disposing the dynamic properties, for those which are declared as dynamic properties.
*
* @privateRemarks
* We are disposing only the declared dynamic properties because we created them on behalf of
* the web part and hence it is our responsiblity to clean them.
*/
private _disposeDynamicPropertiesIfRequired;
/**
* Update the web part property if it is in the property bag.
*
* @param propertyPath - property path as expected by lodash update (https://lodash.com/docs#update).
* (e.g. 'o.a.b', 'o[0].a.b[1].c'). These paths are similar to those in the JSONPath spec described by
* Stefan Goessner at (http://goessner.net/articles/JsonPath/). Currently we plan to use lodash.get, has
* and update APIs which support paths. Some day we may migrate to using actual JSONPath.js. But that
* should not be an issue because the path formatting conventions are same in lodash and JSONPath.
* @param newValue - new value entered by the user for the associated target property
*/
private _updateProperty;
/**
* Using 'cloneDeepWith' because the web part properties bag will now serialize the
* dynamic properties as well. One of the building blocks of these properties are dataProviders,
* which when serialized will result in 'Maximum call stack size exceeded' based on what kind of
* sources they hold references to.
* Hence using cloneDeepWith, which lets us handle the special cases and in this case if the property
* in question is a 'DynamicProperty' and we call '_cloneDeep' api on the dynamicProperty.
*/
private _cloneProperties;
}
/**
* Web part context object. This object contains the contextual services available to a web part. e.g.
* a contextual instance to the http client.
*
* This base is to be extended by UI-specific WebPart's base.
*
* @public
*/
export declare class BaseWebPartContext extends BaseComponentContext {
/**
* {@inheritDoc @microsoft/sp-component-base#BaseComponentContext.manifest}
*/
readonly manifest: IClientSideWebPartManifestInstance<any>;
private _webPartTag;
private _requestPropertyPaneAction;
private _isPropertyPaneRenderedByWebPart;
private _isPropertyPaneOpen;
private _isContentPanelOpen;
private _host;
private _propertyPaneAccessor;
private _privateDataUpdatedEvent;
private _formFactor;
/* Excluded from this release type: __constructor */
/**
* Web part tag to be used for logging and telemetry.
*/
get webPartTag(): string;
/**
* Accessor for common web part property pane operations.
*/
get propertyPane(): IPropertyPaneAccessor;
/* Excluded from this release type: formFactor */
/* Excluded from this release type: host */
/* Excluded from this release type: _dataUpdatedEvent */
}
/* Excluded from this release type: _BaseWebPartHost */
/**
* Callback to clear the dom node.
*
* @public
*/
export declare type _ClearDomElementCallback = (domElement: Element) => void;
/* Excluded from this release type: _ClientSideWebPartManager */
/* Excluded from this release type: _ClientSideWebPartManagerFactory */
/* Excluded from this release type: _ClientSideWebPartStatusRenderer */
/* Excluded from this release type: _CONTENT_PANEL_TOGGLED */
/**
* Enum for the possible values of shared depth of the dynamic data reference.
*
* @public
* @deprecated This is obsolete now. This enum has been moved to `@microsoft/sp-property-pane`.
* Please consume it from there.
* @remarks We have left the original implementation here to avoid breaking the public API contract.
*/
export declare enum DynamicDataSharedDepth {
/**
* Indicates that nothing is shared.
*/
None = 0,
/**
* Indicates that the dynamic data source is shared.
*/
Source = 1,
/**
* Indicates that both the dynamic data source and the property are shared.
*/
Property = 2
}
/* Excluded from this release type: _getErrorAceLoadConfiguration */
/* Excluded from this release type: IA11yCheckResult */
/* Excluded from this release type: IAdaptiveCardExtensionManifest */
/* Excluded from this release type: IAgentsSDK */
/* Excluded from this release type: _IAudienceFormOptions */
/* Excluded from this release type: _IAudienceFormService */
/* Excluded from this release type: _IBaseWebPartContextParameters */
/* Excluded from this release type: _ICanvasControlInfo */
/* Excluded from this release type: _ICardWidthMap */
/**
* Interface to be implemented by a component that should display the loading indicator and
* error messages for a web part.
*
* @public
*/
export declare interface IClientSideWebPartStatusRenderer {
/**
* Display a loading spinner.
* @param domElement - the web part container div.
* @param loadingMessage - the message to be displayed when the loading spinner id displayed.
* @param timeout - timeout to render the loading indicator. Default is 1500ms.
* @param clearDomElementCallback - Callback to clear the dom node before rendering the indicator. Standard DOM API will be used after the callback.
*/
displayLoadingIndicator(domElement: Element, loadingMessage: string, timeout?: number, clearDomElementCallback?: _ClearDomElementCallback): void;
/**
* Clear the loading indicator.
* @param domElement - the web part container div.
*/
clearLoadingIndicator(domElement: Element): void;
/**
* Render the provided error message in the webpart container div.
* @param domElement - the web part container div.
* @param error - the error message.
* @param clearDomElementCallback - Callback to clear the dom node before rendering the error element. Standard DOM API will be used after the callback.
*/
renderError(domElement: HTMLElement, error: Error | string, clearDomElementCallback?: _ClearDomElementCallback): void;
/**
* Clear the webpart error message.
* @param domElement - the web part container div.
*/
clearError(domElement: HTMLElement): void;
/* Excluded from this release type: _displayLoadingIndicator */
}
/* Excluded from this release type: _IComponentContextParameters */
/* Excluded from this release type: _IComponentPosition */
/* Excluded from this release type: _IConfigurableOptionsController */
/**
* Configuration related to a shared property.
*
* @public
* @deprecated This is obsolete now. This interface has been moved to `@microsoft/sp-property-pane`.
* Please consume it from there.
* @remarks We have left the original implementation here to avoid breaking the public API contract.
*/
export declare interface IDynamicDataSharedPropertyConfiguration extends SPPropertyPane.IDynamicDataSharedPropertyConfiguration {
}
/**
* Property pane dynamic data property filters.
*
* @public
* @deprecated This is obsolete now. This interface has been moved to `@microsoft/sp-property-pane`.
* Please consume it from there.
* @remarks We have left the original implementation here to avoid breaking the public API contract.
*/
export declare interface IDynamicDataSharedPropertyFilters extends SPPropertyPane.IDynamicDataSharedPropertyFilters {
}
/**
* Configuration related to a shared source.
*
* @public
* @deprecated This is obsolete now. This interface has been moved to `@microsoft/sp-property-pane`.
* Please consume it from there.
* @remarks We have left the original implementation here to avoid breaking the public API contract.
*/
export declare interface IDynamicDataSharedSourceConfiguration extends SPPropertyPane.IDynamicDataSharedSourceConfiguration {
}
/**
* Property pane dynamic data source filters.
*
* @public
* @deprecated This is obsolete now. This interface has been moved to `@microsoft/sp-property-pane`.
* Please consume it from there.
* @remarks We have left the original implementation here to avoid breaking the public API contract.
*/
export declare interface IDynamicDataSharedSourceFilters extends SPPropertyPane.IDynamicDataSharedSourceFilters {
}
/* Excluded from this release type: _IframedLifeCycleMethods */
/* Excluded from this release type: _IframedWebPartAction */
/* Excluded from this release type: _IHideOn */
/* Excluded from this release type: _IIframedWebPartMessage */
/* Excluded from this release type: _IInternalWebPartData */
/* Excluded from this release type: _IIsolatedItemContext */
/**
* Provides access to the Teams SDK and Teams context. Only provided when the web part is loaded in Teams.
*
* @public
*/
export declare interface IMicrosoftTeams {
/**
* Microsoft Teams SDK.
*/
teamsJs: typeof microsoftTeams;
/**
* Microsoft Teams' Context.
*
* @deprecated
* This property is deprecated. Use the `teamsJs.app.getContext()` method instead.
*
* @remarks
* For more information, please see:
* {@link https://docs.microsoft.com/en-us/javascript/api/@microsoft/teams-js/microsoftteams.context?view=msteams-client-js-latest}
*/
context: microsoftTeams.Context;
}
/* Excluded from this release type: _IMinimalWebPartContainerProps */
/* Excluded from this release type: _IModifiedMetadata */
/* Excluded from this release type: _InstanceId */
/* Excluded from this release type: _IOffice */
/* Excluded from this release type: _IParentHostLifeCycle */
/**
* Web part context property pane accessor interface. Provides some most commonly used operations
* to access the property pane and content panel.
*
* @public
*/
export declare interface IPropertyPaneAccessor {
/**
* This API should be used to open the PropertyPane or Content Panel to help configure the web part.
*/
open(): void;
/**
* This API should be used to close the PropertyPane or Content Panel to help configure the web part.
*/
close(): void;
/**
* This API should be used to open the Details PropertyPane/Content Panel to help configure the items in the web part.
* @remarks
* This API is mainly used for configuring Details, which is different from configuring the web part itself.
*
* @param context - Add additional context for property pane or content panel
*/
openDetails(context?: any): void;
/**
* This API should be used to invoke the PropertyPane or Content Panel to help configure the web part.
*
* @remarks
* This operation only works when the PropertyPane is already open for the currently active web part.
* If the PropertyPane is opened for another web part, calling the refresh API will have no impact.
*/
refresh(): void;
/**
* Indicates whether the PropertyPane/Content Panel was initially opened by the web part.
* @remarks
* For example, if the web part calls this.context.propertyPane.open() then the property would be true,
* whereas if the configuration was opened by the host, then the value will be false.
*/
isRenderedByWebPart(): boolean;
/**
* Returns true if the PropertyPane is open.
* @remarks
* This is true whenever the Property Pane is open whether it is hosted in the Content Panel
* or traditional Property Pane UI.
*
*/
isPropertyPaneOpen(): boolean;
/* Excluded from this release type: isPropertyPaneOpen */
/* Excluded from this release type: isContentPanelOpen */
}
/**
* PropertyPane button props.
*
* @public
* @deprecated This is obsolete now. This interface has been moved to `@microsoft/sp-property-pane`.
* Please consume it from there.
* @remarks We have left the original implementation here to avoid breaking the public API contract.
*/
export declare interface IPropertyPaneButtonProps extends SPPropertyPane.IPropertyPaneButtonProps {
}
/**
* PropertyPane CheckBox component props.
*
* @public
* @deprecated This is obsolete now. This interface has been moved to `@microsoft/sp-property-pane`.
* Please consume it from there.
* @remarks We have left the original implementation here to avoid breaking the public API contract.
*/
export declare interface IPropertyPaneCheckboxProps extends SPPropertyPane.IPropertyPaneCheckboxProps {
}
/**
* PropertyPane ChoiceGroup option props.
*
* @public
* @deprecated This is obsolete now. This interface has been moved to `@microsoft/sp-property-pane`.
* Please consume it from there.
* @remarks We have left the original implementation here to avoid breaking the public API contract.
*/
export declare interface IPropertyPaneChoiceGroupOption extends SPPropertyPane.IPropertyPaneChoiceGroupOption {
}
/**
* PropertyPane ChoiceGroup icon props.
*
* @public
* @deprecated This is obsolete now. This interface has been moved to `@microsoft/sp-property-pane`.
* Please consume it from there.
* @remarks We have left the original implementation here to avoid breaking the public API contract.
*/
export declare interface IPropertyPaneChoiceGroupOptionIconProps extends SPPropertyPane.IPropertyPaneChoiceGroupOptionIconProps {
}
/**
* PropertyPane ChoiceGroup props.
*
* @public
* @deprecated This is obsolete now. This interface has been moved to `@microsoft/sp-property-pane`.
* Please consume it from there.
* @remarks We have left the original implementation here to avoid breaking the public API contract.
*/
export declare interface IPropertyPaneChoiceGroupProps extends SPPropertyPane.IPropertyPaneChoiceGroupProps {
}
/**
* Property pane conditional group.
*
* @public
* @deprecated This is obsolete now. This interface has been moved to `@microsoft/sp-property-pane`.
* Please consume it from there.
* @remarks We have left the original implementation here to avoid breaking the public API contract.
*/
export declare interface IPropertyPaneConditionalGroup extends SPPropertyPane.IPropertyPaneConditionalGroup {
}
/**
* Web part configuration settings
*
* @public
* @deprecated This is obsolete now. This interface has been moved to `@microsoft/sp-property-pane`.
* Please consume it from there.
* @remarks We have left the original implementation here to avoid breaking the public API contract.
*/
export declare interface IPropertyPaneConfiguration extends SPPropertyPane.IPropertyPaneConfiguration {
}
/* Excluded from this release type: _IPropertyPaneConsumer */
/**
* PropertyPane CustomPropertyField props.
*
* @public
* @deprecated This is obsolete now. This interface has been moved to `@microsoft/sp-property-pane`.
* Please consume it from there.
* @remarks We have left the original implementation here to avoid breaking the public API contract.
*/
export declare interface IPropertyPaneCustomFieldProps extends SPPropertyPane.IPropertyPaneCustomFieldProps {
}
/* Excluded from this release type: _IPropertyPaneData */
/**
* PropertyPane dropdown callout properties.
*
* @public
* @deprecated This is obsolete now. This interface has been moved to `@microsoft/sp-property-pane`.
* Please consume it from there.
* @remarks We have left the original implementation here to avoid breaking the public API contract.
*/
export declare interface IPropertyPaneDropdownCalloutProps extends SPPropertyPane.IPropertyPaneDropdownCalloutProps {
}
/**
* PropertyPane drop down options.
*
* @public
* @deprecated This is obsolete now. This interface has been moved to `@microsoft/sp-property-pane`.
* Please consume it from there.
* @remarks We have left the original implementation here to avoid breaking the public API contract.
*/
export declare interface IPropertyPaneDropdownOption extends SPPropertyPane.IPropertyPaneDropdownOption {
}
/**
* PropertyPane drop down component props.
*
* @public
* @deprecated This is obsolete now. This interface has been moved to `@microsoft/sp-property-pane`.
* Please consume it from there.
* @remarks We have left the original implementation here to avoid breaking the public API contract.
*/
export declare interface IPropertyPaneDropdownProps extends SPPropertyPane.IPropertyPaneDropdownProps {
}
/**
* Property pane dynamic field filters which is an intersection of both
* source and property filters.
*
* @public
* @deprecated This is obsolete now. This interface has been moved to `@microsoft/sp-property-pane`.
* Please consume it from there.
* @remarks We have left the original implementation here to avoid breaking the public API contract.
*/
export declare interface IPropertyPaneDynamicFieldFilters extends SPPropertyPane.IPropertyPaneDynamicFieldFilters {
}
/**
* PropertyPaneDynamicField props.
*
* @public
* @deprecated This is obsolete now. This interface has been moved to `@microsoft/sp-property-pane`.
* Please consume it from there.
* @remarks We have left the original implementation here to avoid breaking the public API contract.
*/
export declare interface IPropertyPaneDynamicFieldProps extends SPPropertyPane.IPropertyPaneDynamicFieldProps {
}
/**
* PropertyPane DynamicFieldSet props.
*
* @public
* @deprecated This is obsolete now. This interface has been moved to `@microsoft/sp-property-pane`.
* Please consume it from there.
* @remarks We have left the original implementation here to avoid breaking the public API contract.
*/
export declare interface IPropertyPaneDynamicFieldSetProps extends SPPropertyPane.IPropertyPaneDynamicFieldSetProps {
}
/* Excluded from this release type: IPropertyPaneDynamicTextFieldProps */
/**
* PropertyPane field.
*
* @public
* @deprecated This is obsolete now. This interface has been moved to `@microsoft/sp-property-pane`.
* Please consume it from there.
* @remarks We have left the original implementation here to avoid breaking the public API contract.
*/
export declare interface IPropertyPaneField<TProperties> extends SPPropertyPane.IPropertyPaneField<TProperties> {
}
/**
* PropertyPane group. Group is part of the PropertyPanePage.
*
* @public
* @deprecated This is obsolete now. This interface has been moved to `@microsoft/sp-property-pane`.
* Please consume it from there.
* @remarks We have left the original implementation here to avoid breaking the public API contract.
*/
export declare interface IPropertyPaneGroup extends SPPropertyPane.IPropertyPaneGroup {
}
/**
* PropertyPaneLabel component props.
*
* @public
* @deprecated This is obsolete now. This interface has been moved to `@microsoft/sp-property-pane`.
* Please consume it from there.
* @remarks We have left the original implementation here to avoid breaking the public API contract.
*/
export declare interface IPropertyPaneLabelProps extends SPPropertyPane.IPropertyPaneLabelProps {
}
/* Excluded from this release type: IPropertyPaneLifeCycleEventCallback */
/* Excluded from this release type: IPropertyPaneLifeCycleEventData */
/**
* PropertyPaneLink component props.
*
* @public
* @deprecated This is obsolete now. This interface has been moved to `@microsoft/sp-property-pane`.
* Please consume it from there.
* @remarks We have left the original implementation here to avoid breaking the public API contract.
*/
export declare interface IPropertyPaneLinkProps extends SPPropertyPane.IPropertyPaneLinkProps {
}
/**
* PropertyPanePage interface.
*
* @public
* @deprecated This is obsolete now. This interface has been moved to `@microsoft/sp-property-pane`.
* Please consume it from there.
* @remarks We have left the original implementation here to avoid breaking the public API contract.
*/
export declare interface IPropertyPanePage extends SPPropertyPane.IPropertyPanePage {
}
/**
* PropertyPane header.
* This header remains same for all the pages.
*
* @public
* @deprecated This is obsolete now. This interface has been moved to `@microsoft/sp-property-pane`.
* Please consume it from there.
* @remarks We have left the original implementation here to avoid breaking the public API contract.
*/
export declare interface IPropertyPanePageHeader extends SPPropertyPane.IPropertyPanePageHeader {
}
/**
* PropertyPaneSliderProps component props.
*
* @public
* @deprecated This is obsolete now. This interface has been moved to `@microsoft/sp-property-pane`.
* Please consume it from there.
* @remarks We have left the original implementation here to avoid breaking the public API contract.
*/
export declare interface IPropertyPaneSliderProps extends SPPropertyPane.IPropertyPaneSliderProps {
}
/**
* PropertyPaneTextField component props.
*
* @public
* @deprecated This is obsolete now. This interface has been moved to `@microsoft/sp-property-pane`.
* Please consume it from there.
* @remarks We have left the original implementation here to avoid breaking the public API contract.
*/
export declare interface IPropertyPaneTextFieldProps extends SPPropertyPane.IPropertyPaneTextFieldProps {
}
/**
* PropertyPaneToggle component props.
*
* @public
* @deprecated This is obsolete now. This interface has been moved to `@microsoft/sp-property-pane`.
* Please consume it from there.
* @remarks We have left the original implementation here to avoid breaking the public API contract.
*/
export declare interface IPropertyPaneToggleProps extends SPPropertyPane.IPropertyPaneToggleProps {
}
/* Excluded from this release type: _IReInstateServerProcessedDataOptions */
/* Excluded from this release type: _IRenderErrorOptions */
/* Excluded from this release type: IRenderProps */
/**
* Conditional set of SDKs provided by SPFx dependent on the environment.
*
* @public
*/
export declare interface ISDKs {
/**
* Contextual information about the current Microsoft Teams tab. This object will only be defined if
* a component is being hosted in Microsoft Teams.
*
* @remarks
* For more information, please see:
* {@link https://docs.microsoft.com/en-us/javascript/api/@microsoft/teams-js/?view=msteams-client-js-latest}
*/
microsoftTeams?: IMicrosoftTeams;
/* Excluded from this release type: office */
/* Excluded from this release type: agents */
}
export { ISerializedServerProcessedData }
/**
* This structure represents the part of the serialized state of a web part which is controlled by the web part.
* It is extended by IWebPartData which contains additional data added by the framework to the serialized data.
*
* @public
*/
export declare interface ISerializedWebPartData {
/**
* Web part data version.
*
* @remarks
* Note that data version is different from the version field in the manifest.
* The manifest version is used to control the versioning of the web part code, while data version is used to
* control the versioning of the serialized data of the web part. Refer to dataVersion field of your web part
* for more information.
*
* Supported values: MAJOR.MINOR
*
* Example: `"1.0"`
*/
dataVersion: Version;
/**
* Web part specific properties. The individual web part owns the definition of these properties.
*
* @remarks
* Used by the web part to manage its internal metadata and config data. The framework code never
* touches these properties.
*
* Supported values: any JSON stringifiable object hierarchy.
*
* Example: `{ 'value': 'text value' }`
*/
properties?: any;
/**
* The collections of data that can be processed by server side services like search index and link fixup.
*/
serverProcessedContent?: ISerializedServerProcessedData;
/* Excluded from this release type: containsDynamicDataSource */
/* Excluded from this release type: dynamicDataPaths */
/* Excluded from this release type: dynamicDataValues */
}
/* Excluded from this release type: _ISupportedIdleLoadDisplayMode */
/* Excluded from this release type: _ITranspileContext */
/**
* The base context interface for client-side web parts.
*
* @remarks
* A "context" object is a collection of well-known services and other
* objects that are likely to be needed by any business logic working with
* a component. Each component type has its own specialized extension of
* this interface, e.g. IWebPartContext for web parts, IExtensionContext for
* client-side extensions, etc.
*
* @deprecated - This interface will be removed in an upcoming release. Use the
* {@link WebPartContext} class instead.
*
* @privateRemarks
*
* NOTE: The context object is a convenience that avoids the overhead of
* properly factoring the dependencies for each class in your project,
* in a situation where most classes have essentially the same dependencies.
* If lots of members are added to the context without displine, it can
* easily devolve into a poor engineering practice (where "everything depends
* on everything else"). Think carefully before adding more objects to this
* interface.
*
* Only add data properties or well-defined classes with ubiquitous applicability.
* Do not add loose functions, callbacks, or settable properties.
*
* @public
*/
export declare interface IWebPartContext {
/**
* Manifest for the client-side web part.
*/
readonly manifest: IClientSideWebPartManifestInstance<any>;
/**
* Web part instance id. This is a globally unique value.
*/
readonly instanceId: string;
/**
* Web part tag to be used for logging and telemetry.
*/
readonly webPartTag: string;
/**
* Reference to the DOM element that hosts this client-side component.
*/
readonly domElement: HTMLElement;
/**
* HttpClient instance scoped to this web part.
*/
readonly httpClient: HttpClient;
/**
* SPHttpClient instance scoped to this web part.
*/
readonly spHttpClient: SPHttpClient;
/**
* SharePoint page context.
*/
readonly pageContext: PageContext;
/**
* Web part status renderer.
*/
readonly statusRenderer: IClientSideWebPartStatusRenderer;
/**
* Accessor for common web part property pane operations.
*/
readonly propertyPane: IPropertyPaneAccessor;
/* Excluded from this release type: host */
/* Excluded from this release type: _dataUpdatedEvent */
}
/* Excluded from this release type: _IWebPartContextParameters */
/**
* This structure represents the serialized state of a web part.
*
* @remarks
* When the `serialize()` API is called on a web part, the output should be this structure.
* The structure of the 'properties' field is owned by the web part and is specific to the web part.
* Each web part can decide the set of properties it wants to serialize.
*
* @public
*/
export declare interface IWebPartData {
/**
* Universally unique web part Type id.
*
* @remarks
*
* Example: `"dbef608d-3ad5-4f8f-b139-d916f2f0a294"`
*/
id: string;
/**
* Universally unique instance id of the web part. A web part can have multiple instances on a page.
* This id is expected to be universally unique across time and page boundaries.
*
* @remarks
* supported values: a unique string. Could be GUID or other uniquely identifiable formats.
*
* example: `["dbef608d-3ad5-4f8f-b139-d916f2f0a294"]`
*/
instanceId: string;
/**
* Web part title
*
* @remarks
* Used to display the name of the web part in the toolbox, web part gallery and the page.
*
* Supported values: string less than 100 characters
*
* Example: `"Text"`
*/
title: string;
/**
* Web part description
*
* @remarks
* Used to display the description of the web part.
*
* Supported values: string with the description.
*
* Example: `"Text"`
*/
description?: string;
/**
* Web part data version
*
* @remarks
* Note that data version is different from the version field in the manifest.
* The manifest version is used to control the versioning of the web part code, while data version is used to
* control the versioning of the serialized data of the web part. Refer to dataVersion field of your web part
* for more information.
*
* Supported values: MAJOR.MINOR
*
* Example: `"1.0"`
*/
dataVersion: string;
/**
* Web part specific properties. The individual web part owns the definition of these properties.
*
* @remarks
* Used by the web part to manage its internal metadata and config data. The framework code never
* touches these properties.
*
* Supported values: any object hierarchy that can be serialized using `JSON.stringify()`.
*
* Example: `{ 'value': 'text value' }`
*/
properties?: any;
/**
* The collections of data that can be processed by server side services like search index and link fixup
*/
serverProcessedContent?: ISerializedServerProcessedData;
/* Excluded from this release type: dynamicDataPaths */
/* Excluded from this release type: dynamicDataValues */
/* Excluded from this release type: isolationLevel */
/* Excluded from this release type: iconImageUrl */
/* Excluded from this release type: modifiedByGraph */
/* Excluded from this release type: fullPageAppIconImageUrl */
/* Excluded from this release type: audiences */
/* Excluded from this release type: containsDynamicDataSource */
/* Excluded from this release type: connectedTeamsAppId */
/* Excluded from this release type: hideOn */
}
/* Excluded from this release type: _IWebPartHost */
/* Excluded from this release type: _IWebpartIdleLoad */
/* Excluded from this release type: _IWebPartLoadContext */
/* Excluded from this release type: _IWebPartManagerContext */
/**
* This structure is used to define metadata for web part properties as a map of string to `IWebPartPropertyMetadata`
*
* @remarks
* The key should be a JSON path to the property in web part properties. The JSON path supports the following operators:
*
* - Dot `.` for selecting object members, for example `person.name`
*
* - Brackets `[]` for selecting array items, for example `person.photoURLs[0]`
*
* - Bracketed asterisk `[*]` for array elements wildcard, for example `person.websites[*]`.
*
* You can make combinations of these operators, for example `person.websites[*].url`
*
* Important Note: Only one wildcard per path is supported.
*
* Example: Let's assume we have a web part with properties that have the following schema:
* ```
* {
* title: string;
* person: {
* name: string;
* bio: string;
* photoURLs: string[];
* websites: { title: string; url: string; }[]
* }
* }
* ```
*
* We can define the metadata for the desired properties as following:
* ```
* {
* 'person.bio': { isRichContent: true },
* 'person.photoURLs[*]': { isImageSource: true },
* 'person.websites[*].url': { isLink: true }
* }
* ```
*
* This will make SharePoint servers aware of the content of your properties and run services such as search indexing,
* link fix-up, etc on the data. In case any of the values needs to update by these services, e.g link fix-up, the
* web part property bag is automatically updated.
*
* @public
*/
export declare interface IWebPartPropertiesMetadata {
[key: string]: IWebPartPropertyMetadata;
}
/**
* This is the structure used for map values in `IWebPartPropertiesMetadata`
*
* @public
*/
export declare interface IWebPartPropertyMetadata extends IComponentPropertyMetadata {
/**
* If specified, indicates that the property is a dynamic property and the type of
* the dynamic property.
*
* @remarks
* If a web part has properties that are dynamically
* configurable, then use this flag to declare the property as a dynamic property by
* specifying its type. When a property specifies its dynamic property type, then
* the framework ensures that its value can be accessed using 'tryGetValue' anytime
* in the life cycle of the web part. If a property is marked as DynamicProperty in
* the IWebPartProperties interface, but does not appear in the IWebPartPropertiesMetadata
* with a dynamicPropertyType, then the web part developer will need to manually create
* the DynamicProperty themselves and assign it to the property.
*
* A web part can configure a default value for the property by specifying it in the
* properties section of the web part's manifest. This value will be used when a
* dynamic property is constructed for the property.
*
* Note: Web parts should be able to type cast the resultant value from the `tryGetValue`
* to suit their needs.
*
* @public
*/
dynamicPropertyType?: 'boolean' | 'number' | 'string' | 'array' | 'object';
}
/* Excluded from this release type: _MinimalWebPartContainer */
/* Excluded from this release type: _MinimalWebPartHost */
/* Excluded from this release type: _PageHostLayoutType */
/* Excluded from this release type: _PROPERTY_PANE_TOGGLED */
/* Excluded from this release type: _PROPERTY_PANE_WILL_OPEN */
/* Excluded from this release type: _PropertyPaneAction */
/* Excluded from this release type: _PropertyPaneAction_2 */
/**
* Helper method to create a Button on the PropertyPane.
* @param targetProperty - Target property the Button is associated to.
* @param properties - Strongly typed Button properties.
*
* @public
* @deprecated This is obsolete now. This function has been moved to `@microsoft/sp-property-pane`.
* Please consume it from there.
* @remarks We have left the original implementation here to avoid breaking the public API contract.
*/
export declare function PropertyPaneButton(targetProperty: string, properties: IPropertyPaneButtonProps): IPropertyPaneField<IPropertyPaneButtonProps>;
/**
* Enum for all the supported button types.
*
* @public
* @deprecated This is obsolete now. This enum has been moved to `@microsoft/sp-property-pane`.
* Please consume it from there.
* @remarks We have left the original implementation here to avoid breaking the public API contract.
*/
export declare enum PropertyPaneButtonType {
/**
* Optional completion action.
*
* @remarks
* Typically used at the end of a form or task when paired with the Primary button OR
* as a standalone button to undo an action.
* Examples: "Done" button which closes a container but doesn't make a server call or
* an "Undo" button when a user is uploading a file in OneDrive.
*/
Normal = 0,
/**
* Preferred completion action when paired with a Standard button.
*
* @remarks
* Typically used at the end of a task or form.
* Examples: "Create", "Save", "Send" which makes a server call.
*/
Primary = 1,
/**
* Hero button.
*/
Hero = 2,
/**
* Always used as a set with both Standard and Primary compound buttons.
*
* @remarks
* Typically used in a confirmation dialog.
* Examples: A confirmation dialog when a user discards a form or task with a possible
* significant time investment such as an email or a complex form
*/
Compound = 3,
/**
* Optional actions.
*
* @remarks
* Typically used in a command bar at the top of a view, panel and inside an inline command bar.
* Examples: Command bar at the top of OneDrive, Outlook, SharePoint. Inline command bar on the
* top of SharePoint web parts.
*/
Command = 4,
/**
* Same usage as Command button, when real estate does not allow for icons + labels or as secondary
* actions within the command bar.
*
* @remarks
* Typically used in Command bar in small and medium responsive web breakpoints. Also used on objects.
* Examples: OneDrive small and medium responsive web breakpoint Command Bars and view icons within the
* Command Bar. In SharePoint and OneDrive, Cards with social actions and images which allow users to
* access the image picker. In SharePoint, formatting experiences such as formatting a story within the
* Authoring experience. In Calendar, in the bottom of an event creation Callout when clicking inside
* an empty time range.
*/
Icon = 5
}
/**
* Helper method to create a Checkbox on the PropertyPane.
* @param targetProperty - Target property the checkbox is associated to.
* @param properties - Strongly typed Checkbox properties.
*
* @public
* @deprecated This is obsolete now. This function has been moved to `@microsoft/sp-property-pane`.
* Please consume it from there.
* @remarks We have left the original implementation here to avoid breaking the public API contract.
*/
export declare function PropertyPaneCheckbox(targetProperty: string, properties: IPropertyPaneCheckboxProps): IPropertyPaneField<IPropertyPaneCheckboxProps>;
/**
* Helper method to create a Choice Group on the PropertyPane.
* @param targetProperty - Target property the choice group is associated to.
* @param properties - Strongly typed Choice Group properties.
*
* @public
* @deprecated This is obsolete now. This function has been moved to `@microsoft/sp-property-pane`.
* Please consume it from there.
* @remarks We have left the original implementation here to avoid breaking the public API contract.
*/
export declare function PropertyPaneChoiceGroup(targetProperty: string, properties: IPropertyPaneChoiceGroupProps): IPropertyPaneField<IPropertyPaneChoiceGroupProps>;
/* Excluded from this release type: PropertyPaneCustomField */
/**
* Helper method to create a Dropdown on the PropertyPane.
* @param targetProperty - Target property the dropdown is associated to.
* @param properties - Strongly typed Dropdown properties.
*
* @public
* @deprecated This is obsolete now. This function has been moved to `@microsoft/sp-property-pane`.
* Please consume it from there.
* @remarks We have left the original implementation here to avoid breaking the public API contract.
*/
export declare function PropertyPaneDropdown(targetProperty: string, properties: IPropertyPaneDropdownProps): IPropertyPaneField<IPropertyPaneDropdownProps>;
/**
* Specifies the type of option in a dropdown menu rendered by {@link PropertyPaneDropdown}.
*
* @public
* @deprecated This is obsolete now. This enum has been moved to `@microsoft/sp-property-pane`.
* Please consume it from there.
* @remarks We have left the original implementation here to avoid breaking the public API contract.
*/
export declare enum PropertyPaneDropdownOptionType {
/**
* Render normal menu item.
*/
Normal = 0,
/**
* Render a divider.
*/
Divider = 1,
/**
* Render menu item as a header.
*/
Header = 2
}
/**
* Helper method to create a Dynamic Data widget on the PropertyPane for a dynamic field.
*
* @param targetProperty - Target property the Dynamic Data widget is associated to.
*
* @public
* @deprecated This is obsolete now. This function has been moved to `@microsoft/sp-property-pane`.
* Please consume it from there.
* @remarks We have left the original implementation here to avoid breaking the public API contract.
*/
export declare function PropertyPaneDynamicField(targetProperty: string, properties: IPropertyPaneDynamicFieldProps): IPropertyPaneField<IPropertyPaneDynamicFieldProps>;
/**
* Helper method to create a Dynamic Data widget on the Property Pane for a set
* of dynamic fields with a common data source.
*
* These fields can possibly share the same property based on the associated filters.
* @param properties - Contains entries and options, described as below:
* entries - A set of entries to be configured by the widget. Each entry includes the target
* property and, optionally, the label to show.
* options - Options enabling customized values for callback, filters etc.,
* for the given set of dynamic fields.
* @public
* @deprecated This is obsolete now. This function has been moved to `@microsoft/sp-property-pane`.
* Please consume it from there.
* @remarks We have left the original implementation here to avoid breaking the public API contract.
*/
export declare function PropertyPaneDynamicFieldSet(properties: IPropertyPaneDynamicFieldSetProps): IPropertyPaneField<IPropertyPaneDynamicFieldSetProps>;
/* Excluded from this release type: PropertyPaneDynamicTextField */
/**
* Enum for all the supported PropertyPane field types.
*
* Names should be consistent with those in office-ui-fabric-react, be careful to get letter casing correct.
*
* @public
* @deprecated This is obsolete now. This enum has been moved to `@microsoft/sp-property-pane`.
* Please consume it from there.
* @remarks We have left the original implementation here to avoid breaking the public API contract.
*/
export declare enum PropertyPaneFieldType {
/**
* Custom field.
*/
Custom = 1,
/**
* Checkbox field.
*/
CheckBox = 2,
/**
* TextField field.
*/
TextField = 3,
/**
* Toggle field.
*/
Toggle = 5,
/**
* Dropdown field.
*/
Dropdown = 6,
/**
* Label field.
*/
Label = 7,
/**
* Slider field.
*/
Slider = 8,
/**
* Heading field.
*/
Heading = 9,
/**
* Choice Group field.
*/
ChoiceGroup = 10,
/**
* Button field.
*/
Button = 11,
/**
* Horizontal Rule field.
*/
HorizontalRule = 12,
/**
* Link field.
*/
Link = 13,
/**
* Dynamic data field.
* @public
*/
DynamicField = 14,
/* Excluded from this release type: DynamicTextField */
/**
* A set of dynamic fields.
* @public
*/
DynamicFieldSet = 16,
/* Excluded from this release type: SpinButton */
/* Excluded from this release type: ThumbnailPicker */
/* Excluded from this release type: IconPicker */
/* Excluded from this release type: AlternativeText */
/* Excluded from this release type: WebPartTitleHeading */
/* Excluded from this release type: SortableAccordion */
}
/**
* Helper method to create a Horizontal Rule on the PropertyPane.
*
* @public
* @deprecated This is obsolete now. This function has been moved to `@microsoft/sp-property-pane`.
* Please consume it from there.
* @remarks We have left the original implementation here to avoid breaking the public API contract.
*/
export declare function PropertyPaneHorizontalRule(): IPropertyPaneField<void>;
/**
* Helper method to create a Label on the PropertyPane.
* @param targetProperty - Target property the label is associated to.
* @param properties - Strongly typed Label properties.
*
* @public
* @deprecated This is obsolete now. This function has been moved to `@microsoft/sp-property-pane`.
* Please consume it from there.
* @remarks We have left the original implementation here to avoid breaking the public API contract.
*/
export declare function PropertyPaneLabel(targetProperty: string, properties: IPropertyPaneLabelProps): IPropertyPaneField<IPropertyPaneLabelProps>;
/* Excluded from this release type: _PropertyPaneLifeCycleEvent */
/**
* Helper method to create a Link on the PropertyPane.
* @param targetProperty - Target property the Link is associated to.
* @param properties - Strongly typed Link properties.
*
* @public
* @deprecated This is obsolete now. This function has been moved to `@microsoft/sp-property-pane`.
* Please consume it from there.
* @remarks We have left the original implementation here to avoid breaking the public API contract.
*/
export declare function PropertyPaneLink(targetProperty: string, properties: IPropertyPaneLinkProps): IPropertyPaneField<IPropertyPaneLinkProps>;
/* Excluded from this release type: _PropertyPaneLoader */
/**
* Helper method to create a Slider on the PropertyPane.
* @param targetProperty - Target property the slider is associated to.
* @param properties - Strongly typed Slider properties.
*
* @public
* @deprecated This is obsolete now. This function has been moved to `@microsoft/sp-property-pane`.
* Please consume it from there.
* @remarks We have left the original implementation here to avoid breaking the public API contract.
*/
export declare function PropertyPaneSlider(targetProperty: string, properties: IPropertyPaneSliderProps): IPropertyPaneField<IPropertyPaneSliderProps>;
/**
* Helper method to create a TextField on the PropertyPane.
* @param targetProperty - Target property the textfield is associated to.
* @param properties - Strongly typed TextField properties.
*
* @public
* @deprecated This is obsolete now. This function has been moved to `@microsoft/sp-property-pane`.
* Please consume it from there.
* @remarks We have left the original implementation here to avoid breaking the public API contract.
*/
export declare function PropertyPaneTextField(targetProperty: string, properties: IPropertyPaneTextFieldProps): IPropertyPaneField<IPropertyPaneTextFieldProps>;
/**
* Helper method to create a Toggle on the PropertyPane.
* @param targetProperty - Target property the toggle is associated to.
* @param properties - Strongly typed Toggle properties.
*
* @public
* @deprecated This is obsolete now. This function has been moved to `@microsoft/sp-property-pane`.
* Please consume it from there.
* @remarks We have left the original implementation here to avoid breaking the public API contract.
*/
export declare function PropertyPaneToggle(targetProperty: string, properties: IPropertyPaneToggleProps): IPropertyPaneField<IPropertyPaneToggleProps>;
/* Excluded from this release type: _reInstateServerProcessedData */
/* Excluded from this release type: _TeamsAwareWebPartHost */
/* Excluded from this release type: _TeamsEnvironmentManager */
/**
* Web part context object. This object contains the contextual services available to a web part. e.g.
* a contextual instance to the http client.
*
* @public
*/
export declare class WebPartContext extends BaseWebPartContext {
/* Excluded from this release type: _getPositionOnPage */
private _domElement;
private _statusRenderer;
private _teams;
private readonly _sdks;
private _widthCacheKey;
private readonly _sdksAsync;
private readonly _pageLayoutType;
/* Excluded from this release type: __constructor */
/**
* Reference to the DOM element that hosts this client-side component.
*/
get domElement(): HTMLElement;
/**
* {@inheritdoc ISDKs}
*/
get sdks(): ISDKs;
/* Excluded from this release type: _getSdksAsync */
/**
* Web part status renderer.
*/
get statusRenderer(): IClientSideWebPartStatusRenderer;
/**
* Contextual information about the current Microsoft Teams tab. This object will only be defined if
* a component is being hosted in Microsoft Teams.
*
* @remarks
* For more information, please see:
* {@link https://docs.microsoft.com/en-us/javascript/api/@microsoft/teams-js/?view=msteams-client-js-latest}
* @public
* @deprecated - This function has been deprecated
*/
get microsoftTeams(): typeof microsoftTeams | undefined;
/**
* This functions returns a key generated by web parts display mode, layout index, and section factor.
* It will return undefined if sectionFactor or display mode is undefined, else return the cache key.
*/
get widthCacheKey(): string | undefined;
/* Excluded from this release type: _getPageLayoutType */
/* Excluded from this release type: _setTeams */
}
/* Excluded from this release type: _WebPartDataConverter */
/* Excluded from this release type: WebPartFormFactor */
/* Excluded from this release type: WebPartIsolationLevel */
/* Excluded from this release type: _WebPartWidthCacheManager */
export { }