PluginSettingsComponentBase<PluginSettings>
Base class for plugin settings components.
Manages settings data, persistence, validation, and events. Plugin authors extend this class and implement createDefaultSettings.
Import:
import { PluginSettingsComponentBase } from 'obsidian-dev-utils/obsidian/components/plugin-settings-component';Signature:
export class PluginSettingsComponentBase<PluginSettings extends object> extends ComponentEx implements AsyncEventSource<PluginSettingsComponentBaseEventMap<PluginSettings>>Extends: ComponentEx
Implements: AsyncEventSource<PluginSettingsComponentBaseEventMap<PluginSettings>>
Constructor
new PluginSettingsComponentBase(params: PluginSettingsComponentBaseConstructorParams<PluginSettings>)Creates a new plugin settings component.
Properties
| Property | Type | Description |
|---|---|---|
| [ASYNC_EVENT_MAP]? | PluginSettingsComponentBaseEventMap<PluginSettings> | Phantom marker that makes EventMap inferable from an AsyncEventSource (e.g. via Source extends AsyncEventSource<infer EventMap>). Never present at runtime.(Inherited from AsyncEventSource) |
| dataHandler | DataHandler | The data handler used to load and save the plugin settings. |
| defaultSettings | ReadonlyDeep<PluginSettings> | Gets the readonly default settings. |
| pluginEventSource | PluginEventSource | The plugin event source the component listens to for external settings changes. |
| pluginSettingsClass | Constructor<PluginSettings, []> | The plugin settings class used to construct settings instances. |
Methods
| Method | Returns | Description |
|---|---|---|
| [Symbol.dispose]() | void | Disposes of the component. (Inherited from ComponentEx) |
| addChild(component) | TComponent | Adds a child component. Mirrors the native Component.addChild contract: if this component is already loaded, the child is loaded immediately, so child._loaded is set before this method returns even when this component has async load logic. The child's async tail (if any) is sequenced into the load promise so a later loadWithPromises call awaits it.(Inherited from ComponentEx) |
| editAndSave(settingsEditor, context?) | Promise<void> | Edits the plugin settings and saves them. |
| ensureLoaded() | void | Ensures the component is loaded, throwing if it is not. Use this to guard public methods that register teardown-bearing resources (via Component.register, Component.registerEvent, Component.registerDomEvent, etc.). Registering before load is unsafe: Component.unload is a no-op while the component is not loaded, so any teardown registered beforehand would never run if the component is unloaded without first being loaded.(Inherited from ComponentEx) |
| ensureSafe(settings) | Promise<void> | Ensures the settings are safe. It runs validation for each property and sets the default value if the validation fails. |
| getSafeCopy(settings) | Promise<PluginSettings> | Gets a safe copy of the settings. |
| getTransformer() | Transformer | Gets the transformer. |
| load() | void | Loads the component. (Inherited from ComponentEx) |
| loadFromFile(isInitialLoad) | Promise<void> | Loads the plugin settings from the file. |
| loadWithPromises() | null | Promise<void> | Loads the component with promises. Unlike load, this method never rejects with an individual error: every failure raised by onloadAsync or a child's load is collected, and once everything settles the returned Promise rejects with a single AggregateError holding all of them. Non-Error throwables are normalized via ErrorWrapper.create.(Inherited from ComponentEx) |
| off(name, callback) | void | Remove an event listener. |
| offref(eventRef) | void | Remove an event listener by reference. |
| on(name, callback, thisArg?) | AsyncEventRef | Add an event listener. |
| once(name, callback, thisArg?) | AsyncEventRef | Trigger an event, executing all the listeners in order even if some of them throw an error. Add an event listener that will be called only once. |
| onExternalSettingsChange() | Promise<void> | Called when the external settings change. |
| onloadAsync() | Promise<void> | Loads settings from file and registers event handlers. |
| onLoadRecord(record) | Promise<void> | Called when the plugin settings record is loaded from disk. |
| onLoadSettings(_loadedState, _isInitialLoad) | Promise<void> | Called when settings are loaded or reloaded. |
| onSaveSettings(params) | Promise<void> | Called when settings are saved. |
| onSavingRecord(_record) | Promise<void> | Called when the plugin settings record is about to be saved to disk. |
| registerDisposable(disposable) | TDisposable | Registers a Disposable so it is disposed when this component unloads, and returns it unchanged.The recurring "tie a disposable to the component's lifecycle, then keep using it" idiom: the disposable is disposed on Component.unload (or earlier, if the caller disposes it directly — dispose is expected to be idempotent). Guard with ensureLoaded at the call site when registering before load would be unsafe.(Inherited from ComponentEx) |
| registerLegacySettingsConverter(legacySettingsClass, converter) | void | Registers a legacy settings converter. |
| registerLegacySettingsConverters() | void | Registers the legacy settings converters. Override to register legacy settings converters. |
| registerValidator(propertyName, validator) | void | Registers a validator for a property. |
| registerValidators() | void | Registers the validators. Override to register validators for properties. |
| removeChild(component) | TComponent | Removes a child component. (Inherited from ComponentEx) |
| revalidate() | Promise<Record<PropertyNames<PluginSettings>, string>> | Revalidates the settings. |
| saveToFile(context?) | Promise<void> | Saves the new plugin settings. |
| setProperty(propertyName, value) | Promise<string> | Sets the value of a property. |
| validate(settings) | Promise<ValidationResult<PluginSettings>> | Validates the settings. |
Links to this page: