Dokumentation

Installation

MudExRichTextEditor unterstützt .NET 8, 9 und 10 und läuft unter Blazor WebAssembly und Blazor Server. MudBlazor kommt transitiv mit, die Komponente rendert aber auch in Projekten, die MudBlazor selbst nicht verwenden.

dotnet add package MudExRichTextEditor

Danach einmalig das Using in _Imports.razor eintragen:

@using MudExRichTextEditor

Schnellstart

@page "/"

<MudExRichTextEdit @bind-Value="_html" Height="320" />

@code {
    private string _html = "<p>Hello <b>MudBlazor</b>!</p>";
}

Die Komponente erbt von der Formular-Basisklasse aus MudBlazor.Extensions. Deshalb verhalten sich @bind-Value, Required, Label, Validation und Disabled wie bei einem MudTextField. Ein leeres Dokument gilt als leer — die Required-Prüfung greift also auch, nachdem der Nutzer den gesamten Text gelöscht hat.

Presets

QuillPresets liefert drei fertige Kombinationen aus Werkzeugleiste und Modulen.

• Minimal — fett, kursiv, unterstrichen, durchgestrichen. Keine Module.
• Standard — Überschriften, Listen, Links und Bilder, dazu Tabellen-, Bildgrößen- und Komprimierungsmodul.
• Full — alles davon plus Farben, Einzüge, Ausrichtung, Zitat, Codeblock, Video und Tabellen-Button.

@using MudExRichTextEditor.Types

<MudExRichTextEdit @bind-Value="_html"
                   Tools="@QuillPresets.Standard.Tools"
                   Modules="@QuillPresets.Standard.Modules"
                   Height="360"
                   Immediate="true" />

Parameter

Die wichtigsten Parameter. Alles, was von der MudBlazor-Formularbasis geerbt wird (Label, Required, Disabled, Class, Style, Validation, Culture), steht ebenfalls zur Verfügung.

Methoden

Über @ref eine Referenz holen, dann aufrufen.

Werkzeugleiste & Tools

Ohne eigenen Tools-Wert rendert der Editor QuillTool.All() plus einen Datei- und einen Mikrofon-Button. Mit einem eigenen Array steuerst du Inhalt und Reihenfolge — die Tools werden nach ihrer group-Nummer gruppiert, jede Gruppe wird ein durch Trenner abgesetzter Block.

@using MudExRichTextEditor.Types

<MudExRichTextEdit @bind-Value="_html" Tools="@_tools" />

@code {
    private QuillTool[] _tools = [
        QuillTools.Header(group: 1),
        QuillTools.Font(group: 1),                 // font family dropdown
        QuillTools.Size(group: 1),                 // font size dropdown
        QuillTools.Bold(group: 2),
        QuillTools.Italic(group: 2),
        QuillTools.Link(group: 3),
        QuillTools.Image(group: 3),
    ];
}

QuillTools ist die Factory für jeden eingebauten Button: Bold, Italic, Underline, Strike, Header, Font, Size, Color, Background, OrderedList, BulletList, IndentDecrease, IndentIncrease, Align, Blockquote, CodeBlock, Link, Image, Video und TableButton.

Soll das Toolbar-Markup komplett ersetzt werden, nimm stattdessen das ToolbarContent-RenderFragment.

Eigene Toolbar-Buttons

CustomTool rendert einen MudBlazor-Icon-Button und übergibt beim Klick die Editor-Instanz. Icon, Tooltip und Farbe können statisch oder pro Render berechnet sein — genau so wechselt der Mikrofon-Button zwischen „Aufnehmen“ und „Stopp“.

@using MudExRichTextEditor.Types

<MudExRichTextEdit @ref="_editor" Tools="@_tools" />

@code {
    private MudExRichTextEdit _editor;

    private QuillTool[] _tools = QuillTool.All()
        .Append(new CustomTool(
            onClick: (_, editor) => editor.InsertHtmlAsync("<hr />"),
            icon: Icons.Material.Filled.HorizontalRule,
            tooltip: "Insert divider",
            group: 9))
        .ToArray();
}

Um einen eingebauten Quill-Handler zu ersetzen statt einen Button zu ergänzen, nutze DefaultToolHandlers mit dem Quill-Formatnamen, z. B. new DefaultToolHandler("image", (editor, args) => ...).

Module

@using MudExRichTextEditor.Extensibility

<MudExRichTextEdit @bind-Value="_html" Modules="@_modules" />

@code {
    private IQuillModule[] _modules = [
        new QuillBlotFormatterModule(),   // resize images by clicking them
        new QuillImageCompressorModule(), // shrink pasted/dropped images
        new QuillTableBetterModule(),     // tables (needs QuillTools.TableButton())
    ];
}

• QuillBlotFormatterModule — Anfasser zum Skalieren von Bildern und Embeds. Teil der Presets Standard und Full.
• QuillImageCompressorModule — verkleinert Bilder beim Einfügen und Ablegen, bevor sie gespeichert werden.
• QuillTableBetterModule — Tabellen mit Kontextmenü. Für den Einfügen-Button QuillTools.TableButton() in die Werkzeugleiste aufnehmen.
• QuillBetterTableModule — die ältere Tabellenimplementierung, mit MudBlazor-Palettenfarben für Zellhintergründe.
• QuillMentionModule<T> — siehe unten.

Eigene Module leiten von QuillModule ab: JsFiles und CssFiles deklarieren und die Quill-Konfiguration aus OnModuleLoadedAsync zurückgeben.

Mentions

QuillMentionModule<T> ist generisch über deinen eigenen Typ und erwartet eine asynchrone Suche, die das Auslösezeichen und den aktuellen Suchbegriff bekommt.

@using MudExRichTextEditor.Extensibility

<MudExRichTextEdit @bind-Value="_html" Modules="@_modules" />

@code {
    private IQuillModule[] _modules;

    protected override void OnInitialized() => _modules = [
        new QuillMentionModule<string>(
            (denotationChar, search) => Task.FromResult(
                new[] { "Alice", "Bob", "Carol" }.Where(n => n.Contains(search, StringComparison.OrdinalIgnoreCase))),
            '@', '#')
    ];
}

Das Modul bietet außerdem die Callbacks MentionClicked, MentionHovered, BeforeMentionSelect und AfterMentionSelect.

Die Vorschlagsliste wird mit der fixed-Strategie von quill-mention positioniert und landet damit auch in einem MudDialog oder einem gescrollten bzw. transformierten Elternelement am Cursor.

Dateien & Uploads

Der Anhang-Button öffnet einen MudBlazor-Upload-Dialog; Einfügen und Drag & Drop werden ebenfalls behandelt. Ohne CustomUploadFunc landet jede Datei als Data-URL im Dokument — praktisch für Demos, teuer für echte Inhalte. Besser auf den eigenen Speicher zeigen:

<MudExRichTextEdit @bind-Value="_html" CustomUploadFunc="@UploadAsync" />

@code {
    // Return the URL the editor should embed. Without this func the file is
    // inlined as a data URL, which bloats the stored HTML.
    private async Task<string> UploadAsync(UploadableFile file)
    {
        await file.EnsureDataLoadedAsync();
        var url = await _myStorage.SaveAsync(file.FileName, file.Data, file.ContentType);
        return url;
    }
}

Mit Files oder OnGetFilesFunc lässt sich der Dialog vorbefüllen, OnBeforeDialogOpen und OnDialogClosed erlauben Reaktionen darum herum.

Wert & HTML-Verhalten

ValueHtmlBehavior bestimmt, was die Bindung zurückschreibt.

@using MudExRichTextEditor.Types

<MudExRichTextEdit @bind-Value="_html"
                   ValueHtmlBehavior="GetHtmlBehavior.SemanticHtml" />

@code {
    // Read a different representation on demand, independent of the binding:
    private async Task ReadAll()
    {
        var semantic = await _editor.GetSemanticHTML();
        var inner    = await _editor.GetHtml();
        var text     = await _editor.GetText();
        var delta    = await _editor.GetContent(); // Quill Delta as JSON
    }
}

• SemanticHtml (Standard) — die bereinigte Quill-Ausgabe, am besten zum Speichern und späteren Rendern.
• InnerHtml — das Editor-DOM wortwörtlich, inklusive Quill-eigener Klassen.
• Text — reiner Text.
• Content — das Delta-Dokument als JSON; mit LoadContent wieder einlesen.

Themes & Aussehen

@using MudExRichTextEditor.Types

<MudExRichTextEdit @bind-Value="_html"
                   Theme="QuillTheme.Bubble"
                   BackgroundColor="MudExColor.Surface"
                   ToolBarBackgroundColor="MudExColor.Primary"
                   BorderColor="MudExColor.Secondary"
                   EnableResize="true"
                   Height="300" />

Die Farben akzeptieren den vollen MudExColor-Umfang: Paletteneinträge, CSS-Variablen und feste Werte. Im Nur-Lese-Modus verschwindet die Werkzeugleiste standardmäßig:

<MudExRichTextEdit Value="@_html" ReadOnly="true" HideToolbarWhenReadOnly="true" />

Blazor Server

Der Editor braucht einen interaktiven Render-Modus; bei statischem oder rein vorgerendertem Modus erscheint zwar der Container, Quill initialisiert aber nie. Die MudBlazor-Provider und blazor.web.js müssen vorhanden sein:

<!-- App.razor / _Host.cshtml -->
<head>
    ...
    <link href="_content/MudBlazor/MudBlazor.min.css" rel="stylesheet" />
</head>
<body>
    <MudDialogProvider @rendermode="InteractiveServer" />
    <MudSnackbarProvider @rendermode="InteractiveServer" />
    <MudPopoverProvider @rendermode="InteractiveServer" />
    <Routes @rendermode="InteractiveServer" />
    <script src="_framework/blazor.web.js"></script>
    <script src="_content/MudBlazor/MudBlazor.min.js"></script>
</body>

Self-Hosting & Offline

Alle Assets stecken im Paket und werden aus _content/MudExRichTextEditor ausgeliefert: Quill selbst, die Themes, das Mention-Modul, der Bildkomprimierer, der Blot-Formatter und — seit 9.5.1 — das Tabellen-Modul. Nichts wird von einem CDN geholt; die Komponente läuft hinter einem Proxy, in abgeschotteten Netzen und unter strenger Content-Security-Policy.

FAQ

Chrome warnt über vorgeladenes CSS von AuralizeBlazor oder Nextended.Blazor

Diese Warnung stammt vom .NET SDK, nicht von dieser Komponente. Sobald deine App irgendeine Razor Class Library mit Scoped CSS referenziert, hängt das SDK an deine eigene {App}.styles.css einen Header Link: <…bundle.scp.css>; rel="preload". Chrome meldet jedes Preload, das nicht schnell genug verwendet wird. Rein kosmetisch — nichts ist kaputt und nichts wird doppelt geladen.

Geht das auch ohne MudBlazor?

Ja. Das Paket bringt seine MudBlazor-Abhängigkeit mit; der Rest der App muss nicht damit gebaut sein.

Wie bekomme ich echtes HTML statt Quill-Markup?

Das voreingestellte GetHtmlBehavior.SemanticHtml verwenden oder GetSemanticHTML() aufrufen.

Warum kommt mein Markup verändert zurück?

Markup, das du an Value übergibst, wird von Quill geparst und damit auf das normalisiert, was Quill darstellen kann: <b> wird zu <strong>, <pre> zu einem Codeblock, Listeneinträge bekommen Quill-eigene Attribute. Das zurückgelesene semantische HTML ist gleichwertig, nicht bytegleich.

Drag & Drop und Einfügen

Die Komponente behandelt beides selbst und fügt die Datei genau einmal ein, an der Stelle des Drops. Keinen eigenen drop- oder paste-Handler für Dateien auf der Editor-Wurzel ergänzen — genau das führt zu doppelten Bildern.