obsidian-dev-utils/dist/lib/esm/obsidian/Dataview.d.mts

This is the collection of useful functions that you can use for your Obsidian plugin development

/**
 * @packageDocumentation
 *
 * This module provides utility functions for working with Dataview in Obsidian.
 */
import type { Promisable } from 'type-fest';
import type { DataviewInlineApi as DataviewInlineApiOriginal } from './@types/Dataview/api/inline-api.d.mjs';
import type { DataArray, DataviewApi, SMarkdownPage } from './@types/Dataview/index.d.mjs';
import type { PathOrFile } from './FileSystem.mjs';
import type { CombinedFrontmatter } from './Frontmatter.mjs';
/**
 * Export DateTime and Link types from the Dataview API.
 */
export type { DateTime, Link } from './@types/Dataview/index.d.mjs';
declare global {
    /**
     * A {@link DataviewApi} object represents the API for interacting with Dataview in Obsidian.
     */
    var DataviewAPI: DataviewApi | undefined;
}
/**
 * A combined page type, which includes the front matter and the SMarkdownPage.
 */
export type CombinedPage<CustomFrontmatter = unknown> = CombinedFrontmatter<CustomFrontmatter> & SMarkdownPage;
/**
 * Extended interface for the Dataview Inline API, providing additional methods for custom page types and array handling.
 *
 * @typeParam CustomPage - The type of the custom page. Defaults to `SMarkdownPage`.
 */
export interface DataviewInlineApi extends DataviewInlineApiOriginal {
    /**
     * Wraps an array of items into a {@link DataArray} object.
     *
     * @typeParam T - The type of the items in the array.
     * @param arr - The array of items to wrap.
     * @returns A {@link DataArray} containing the items.
     */
    array<T>(arr: T[]): DataArray<T>;
    /**
     * Retrieves the current page, with an optional custom page type.
     *
     * @typeParam CustomPage - The type of the custom page. Defaults to `SMarkdownPage`.
     * @returns The current page.
     */
    current<CustomFrontmatter = unknown>(): CombinedPage<CustomFrontmatter>;
    /**
     * Retrieves pages based on an optional query, with an optional custom page type.
     *
     * @typeParam CustomPage - The type of the custom page. Defaults to `SMarkdownPage`.
     * @param query - An optional string query to filter the pages.
     * @returns A {@link DataArray} of pages matching the query.
     */
    pages<CustomFrontmatter = unknown>(query?: string): DataArray<CombinedPage<CustomFrontmatter>>;
    /**
     * Creates a paragraph HTML element with the provided text and optional DOM element options.
     *
     * @param text - The content of the paragraph.
     * @param options - Optional DOM element options, including an optional container.
     * @returns The created HTML paragraph element.
     */
    paragraph(text: unknown, options?: DomElementInfoWithContainer): HTMLParagraphElement;
}
/**
 * DomElementInfo with an optional container.
 */
export type DomElementInfoWithContainer = {
    container?: HTMLElement;
} & DomElementInfo;
/**
 * A combined file type, which includes the front matter and the SMarkdownFile.
 */
export type PageFile = SMarkdownPage['file'];
/**
 * List of page files.
 */
export type PageFiles = ArrayOrDataArray<PageFile>;
/**
 * Reloads the current file cache using the Dataview API.
 *
 * @param dv - The DataviewInlineApi instance.
 * @returns A {@link Promise} that resolves when the cache is reloaded.
 */
export declare function reloadCurrentFileCache(dv: DataviewInlineApi): Promise<void>;
/**
 * Array or DataArray type.
 */
export type ArrayOrDataArray<T> = DataArray<T> | T[];
/**
 * Options for {@link renderIframe}.
 */
export interface RenderIframeOptions {
    /**
     * A {@link DataviewInlineApi} instance.
     */
    dv: DataviewInlineApi;
    /**
     * A height of the iframe.
     */
    height: string;
    /**
     * A relative path to the resource to be displayed in the iframe.
     */
    relativePathOrFile: PathOrFile;
    /**
     * A width of the iframe.
     */
    width: string;
}
/**
 * Options for {@link renderPaginatedList}.
 */
export interface RenderPaginatedListOptions<T> {
    /**
     * A {@link DataviewInlineApi} instance.
     */
    dv: DataviewInlineApi;
    /**
     * Options for items per page. Defaults to `[10, 20, 50, 100]`.
     */
    itemsPerPageOptions?: number[];
    /**
     * A list of items to paginate.
     */
    rows: ArrayOrDataArray<T>;
}
/**
 * Options for {@link renderPaginated}.
 */
export interface RenderPaginatedOptions<T> {
    /**
     * A {@link DataviewInlineApi} instance.
     */
    dv: DataviewInlineApi;
    /**
     * Options for items per page.
     */
    itemsPerPageOptions: number[];
    /**
     * Display the paginated content.
     *
     * @param rowsForOnePage - The rows to render.
     * @returns A {@link Promise} that resolves when the content is rendered.
     */
    renderer(rowsForOnePage: ArrayOrDataArray<T>): Promisable<void>;
    /**
     * Rows to paginate.
     */
    rows: ArrayOrDataArray<T>;
}
/**
 * Options for {@link renderPaginatedTable}.
 */
export interface RenderPaginatedTableOptions<T> {
    /**
     * A {@link DataviewInlineApi} instance.
     */
    dv: DataviewInlineApi;
    /**
     * A headers of the table.
     */
    headers: string[];
    /**
     * Options for items per page. Defaults to `[10, 20, 50, 100]`.
     */
    itemsPerPageOptions?: number[];
    /**
     * Rows of the table to paginate.
     */
    rows: ArrayOrDataArray<T>;
}
/**
 * Renders the content using the provided renderer function in a temporary container,
 * and then returns the container.
 *
 * @param dv - The DataviewInlineApi instance.
 * @param renderer - The function responsible for rendering the content.
 * @returns A {@link Promise} that resolves to the HTML paragraph element
 * that was used as the temporary container.
 */
export declare function getRenderedContainer(dv: DataviewInlineApi, renderer: () => Promisable<void>): Promise<HTMLParagraphElement>;
/**
 * Inserts a code block into the specified Dataview instance using the provided language and code.
 *
 * @param dv - The DataviewInlineApi instance to insert the code block into.
 * @param language - The language identifier for the code block.
 * @param code - The code content to be inserted into the code block.
 */
export declare function insertCodeBlock(dv: DataviewInlineApi, language: string, code: string): void;
/**
 * Renders an iframe in the Dataview container with the specified relative path, width, and height.
 *
 * @param options - The options for rendering the iframe.
 */
export declare function renderIframe(options: RenderIframeOptions): void;
/**
 * Renders a paginated list using the provided DataviewInlineApi instance.
 *
 * @typeParam T - The type of items in the list.
 *
 * @param options - The options for rendering the paginated list.
 *
 * @returns A {@link Promise} that resolves when the list is rendered.
 */
export declare function renderPaginatedList<T>(options: RenderPaginatedListOptions<T>): Promise<void>;
/**
 * Renders a paginated table using the provided DataviewInlineApi instance.
 *
 * @typeParam T - The type of items in the table rows.
 *
 * @param options - The options for rendering the paginated table.
 *
 * @returns A {@link Promise} that resolves when the table is rendered.
 */
export declare function renderPaginatedTable<T extends unknown[]>(options: RenderPaginatedTableOptions<T>): Promise<void>;