obsidian-dev-utils
Version:
This is the collection of useful functions that you can use for your Obsidian plugin development
149 lines (148 loc) • 6.38 kB
text/typescript
/**
* @packageDocumentation
*
* This module defines a base class for creating plugin setting tabs in Obsidian.
* It provides a utility method to bind value components to plugin settings and handle changes.
*/
import type { ConditionalKeys, Promisable, ReadonlyDeep } from 'type-fest';
import { PluginSettingTab } from 'obsidian';
import type { StringKeys } from '../../Type.mjs';
import type { ValueComponentWithChangeTracking } from '../Components/SettingComponents/ValueComponentWithChangeTracking.mjs';
import type { ValidationMessageHolder } from '../Validation.mjs';
import type { ExtractPlugin, ExtractPluginSettings, ExtractReadonlyPluginSettingsWrapper, PluginTypesBase } from './PluginTypesBase.mjs';
/**
* A context passed to the {@link PluginSettingsManagerBase.saveToFile} method.
*/
export declare const SAVE_TO_FILE_CONTEXT = "PluginSettingsTab";
/**
* Options for `PluginSettingsTabBase.bind`.
*/
export interface BindOptions<T> {
/**
* A callback function that is called when the value of the component changes.
*/
onChanged?(newValue: ReadonlyDeep<T>, oldValue: ReadonlyDeep<T>): Promisable<void>;
/**
* Whether to reset the setting when the component value is empty. Default is `true`.
* Applicable only to text-based components.
*/
shouldResetSettingWhenComponentIsEmpty?: boolean;
/**
* Whether to show the placeholder for default values. Default is `true`.
* Applicable only to text-based components.
*/
shouldShowPlaceholderForDefaultValues?: boolean;
/**
* Whether to show the validation message when the component value is invalid. Default is `true`.
*/
shouldShowValidationMessage?: boolean;
}
/**
* Extended options for `PluginSettingsTabBase.bind`.
*/
export interface BindOptionsExtended<PluginSettings extends object, UIValue, PropertyName extends StringKeys<PluginSettings>> extends BindOptions<PluginSettings[PropertyName]> {
/**
* Converts the UI component's value back to the plugin settings value.
*
* @param uiValue - The value of the UI component.
* @returns The value to set on the plugin settings.
*/
componentToPluginSettingsValueConverter(uiValue: UIValue): PluginSettings[PropertyName] | ValidationMessageHolder;
/**
* Converts the plugin settings value to the value used by the UI component.
*
* @param pluginSettingsValue - The value of the property in the plugin settings.
* @returns The value to set on the UI component.
*/
pluginSettingsToComponentValueConverter(pluginSettingsValue: ReadonlyDeep<PluginSettings[PropertyName]>): UIValue;
}
/**
* Base class for creating plugin settings tabs in Obsidian.
* Provides a method for binding value components to plugin settings and handling changes.
*
* @typeParam PluginTypes - Plugin-specific types.
*/
export declare abstract class PluginSettingsTabBase<PluginTypes extends PluginTypesBase> extends PluginSettingTab {
plugin: ExtractPlugin<PluginTypes>;
/**
* Whether the plugin settings tab is open.
*
* @returns Whether the plugin settings tab is open.
*/
get isOpen(): boolean;
/**
* A debounce timeout for saving settings.
*
* @returns The debounce timeout for saving settings.
*/
protected get saveSettingsDebounceTimeoutInMilliseconds(): number;
private _isOpen;
private readonly asyncEvents;
private readonly asyncEventsComponent;
private readonly saveSettingsDebounced;
private get pluginSettings();
/**
* Creates a new plugin settings tab.
*
* @param plugin - The plugin.
*/
constructor(plugin: ExtractPlugin<PluginTypes>);
/**
* Binds a value component to a plugin setting.
*
* @typeParam UIValue - The type of the value of the UI component.
* @typeParam TValueComponent - The type of the value component.
* @param valueComponent - The value component to bind.
* @param propertyName - The property of the plugin settings to bind to.
* @param options - The options for binding the value component.
* @returns The value component.
*/
bind<UIValue, TValueComponent>(valueComponent: TValueComponent & ValueComponentWithChangeTracking<UIValue>, propertyName: ConditionalKeys<ExtractPluginSettings<PluginTypes>, UIValue>, options?: BindOptions<UIValue>): TValueComponent;
/**
* Binds a value component to a plugin setting.
*
* @typeParam UIValue - The type of the value of the UI component.
* @typeParam TValueComponent - The type of the value component.
* @typeParam PropertyName - The property name of the plugin settings to bind to.
* @param valueComponent - The value component to bind.
* @param propertyName - The property name of the plugin settings to bind to.
* @param options - The options for binding the value component.
* @returns The value component.
*/
bind<UIValue, TValueComponent, PropertyName extends StringKeys<ExtractPluginSettings<PluginTypes>>>(valueComponent: TValueComponent & ValueComponentWithChangeTracking<UIValue>, propertyName: PropertyName, options: BindOptionsExtended<ExtractPluginSettings<PluginTypes>, UIValue, PropertyName>): TValueComponent;
/**
* Renders the plugin settings tab.
*/
display(): void;
/**
* Hides the plugin settings tab.
*/
hide(): void;
/**
* Async actions to perform when the settings tab is being hidden.
*
* @returns A {@link Promise} that resolves when the settings tab is hidden.
*/
hideAsync(): Promise<void>;
/**
* Shows the plugin settings tab.
*/
show(): void;
/**
* Called when the plugin settings are loaded.
*
* @param _loadedSettings - The loaded settings.
* @param _isInitialLoad - Whether the settings are being loaded for the first time.
* @returns A {@link Promise} that resolves when the settings are loaded.
*/
protected onLoadSettings(_loadedSettings: ExtractReadonlyPluginSettingsWrapper<PluginTypes>, _isInitialLoad: boolean): Promise<void>;
/**
* Revalidates the settings.
*
* @returns A {@link Promise} that resolves when the settings are revalidated.
*/
protected revalidate(): Promise<void>;
private on;
private onSaveSettings;
private updateValidations;
}