SPEvent class
Represents a framework event that components can subscribe to.
Remarks
Examples of events in a web application might include: the user clicking a button, the system navigating to another page, or an item being added/removed from an abstract collection. The SharePoint Framework represents events using instances of the SPEvent object, one for each kind of event. The SPEvent object is typically exposed as a property of an associated class (e.g. the button that can be clicked). When a component is interested in an event, it calls add() to register an event handler callback that will be invoked each time the event occurs. The handler receives an SPEventArgs parameter that may provide additional details about what happened. This is analogous to the browser's Document Object Model (DOM) events. The main difference is the ISPEventObserver feature, which tracks which component subscribed to each event, and automatically unsubscribes the handler when the component is disposed.
When an event is raised, all handlers are invoked synchronously. The order in which event handlers are called is unspecified. The event handler callback must catch any exceptions that occur during processing; an uncaught exception will not prevent other handlers from executing, but it will be reported as a problem with the associated component.
The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the SPEvent class.
Methods
| add(observer, event |
Registers a callback that will be invoked whenever the event occurs. |
| remove(observer, event |
Unregisters a callback that was registered using add(). |
Method Details
add(observer, eventHandler)
Registers a callback that will be invoked whenever the event occurs.
add(observer: ISPEventObserver, eventHandler: (eventArgs: TEventArgs) => void): void;Parameters
- observer
- ISPEventObserver
Indicates the object that is subscribing to the event: When the object is disposed, the event handler will be automatically removed. This object is also used for diagnostic purposes, e.g. detecting if the event handler failed to catch an exception.
- eventHandler
-
(eventArgs: TEventArgs) => void
A callback function that will be invoked whenever the event occurs
Returns
void
Remarks
The same object can add multiple event handlers to the same event. Since BaseComponent implements the ISPEventObserver interface, a web part or extension can pass itself as the observer. This will cause the event handler to be automatically unsubscribed when the web part or extension is disposed.
remove(observer, eventHandler)
Unregisters a callback that was registered using add().
remove(observer: ISPEventObserver, eventHandler: (eventArgs: TEventArgs) => void): void;Parameters
- observer
- ISPEventObserver
This must be the same observer that was passed to the add() function.
- eventHandler
-
(eventArgs: TEventArgs) => void
The event handler to remove; this must be the same object instance that was passed to the add() function.
Returns
void
Remarks
If the event handler has already been removed, or if it was never added, then this method has no effect.