Zurück zur Dokumentation

Dokumentkommentare

Einführung

Sutram bietet ein leistungsfähiges Dokumentenkommentarsystem, das Projektteams die direkte Zusammenarbeit an Dokumenten ermöglicht, indem Kommentare an bestimmten Positionen platziert werden. Kommentare werden an präzisen Stellen innerhalb von PDFs, Bildern, Office-Dokumenten, Markdown-Dateien und CAD/BIM-Modellen verankert, was kontextbezogene Diskussionen ermöglicht, ohne die Plattform zu verlassen.

Hauptfunktionen

  • Kontextbewusste Verankerung: Drei verschiedene Verankerungsmethoden je nach Dateityp
  • Diskussionsstränge: Auf Kommentare antworten, um Gesprächsstränge zu erstellen
  • Echtzeit-Zusammenarbeit: Kommentare anderer Benutzer sofort über PubSub sehen
  • Multi-Format-Unterstützung: Funktioniert mit PDFs, Bildern, Office-Dokumenten (Word, Excel, PowerPoint), Markdown und CAD/BIM-Dateien
  • Kommentarauflösung: Kommentare als gelöst markieren, wenn Probleme behoben sind
  • Visuelle Markierungen: Nummerierte Sprechblasen-Marker zeigen Kommentarpositionen direkt auf Dokumenten
  • Kommentarpanel: Unteres Panel mit Filtern (Alle/Offen/Gelöst) zum Durchsuchen und Navigieren von Kommentaren
  • Navigation: Auf Marker oder Panel-Einträge klicken, um zu bestimmten Kommentaren zu springen
  • 6-Sprachen-Unterstützung: Vollständige Internationalisierung (Englisch, Portugiesisch, Spanisch, Französisch, Deutsch, Italienisch)

Verankerungsmethoden nach Dateityp

Das System verwendet drei verschiedene Verankerungsmethoden je nach Dateityp, die jeweils für die Art und Weise optimiert sind, wie Benutzer mit diesem Inhaltstyp interagieren:

1. Positionsverankerung (PDF & Bilder)

Verwendet für: PDF-Dateien, Bilder, Office-Dokumente (in PDF konvertiert)

Funktionsweise: Der Benutzer klickt an eine beliebige Stelle im Dokument und der Kommentar wird an relativen Koordinaten (0,0-1,0) verankert.

Dateityp Positionstyp Speicherung Benutzerinteraktion
PDF pdf_page pdf_page_number + pdf_relative_x/y (0,0-1,0) Überall auf der Seite klicken
Bilder image pdf_relative_x/y (0,0-1,0) Überall auf dem Bild klicken
Office pdf_page Erst in PDF konvertiert, dann wie PDF Auf konvertiertes PDF klicken

Vorteile:

  • Funktioniert unabhängig von Zoomstufe oder Fenstergröße
  • Präzise Positionierung auf visuellen Inhalten
  • Einfach und intuitiv für Benutzer

Schaltflächentext: "Klicken zum Hinzufügen..." (in 6 Sprachen übersetzt)

2. Kameraansicht-Verankerung (CAD/BIM)

Verwendet für: CAD-2D-Zeichnungen (DWG, DXF), CAD-3D-Modelle (IFC, RVT usw.)

Funktionsweise: Der Benutzer klickt auf das Modell und der Kommentar erfasst sowohl die Weltkoordinaten ALS AUCH den Kamerazustand (Ansichtsposition, Zoom, Drehung).

Dateityp Positionstyp Speicherung Benutzerinteraktion
CAD 3D aps_3d aps_world_coordinates {x,y,z} + aps_db_id + aps_camera_state Auf die 3D-Modelloberfläche klicken
CAD 2D aps_2d aps_world_coordinates {x,y,z} + aps_sheet_guid + aps_camera_state Auf die 2D-Zeichnung klicken

Vorteile:

  • Marker folgen dem Modell beim Zoomen/Schwenken/Drehen
  • "Zur Position gehen" stellt die exakte Ansicht des Kommentators wieder her
  • Funktioniert mit Explosionsansichten und Schnittebenen
  • Element-ID wird für zukünftige Integrationen erfasst

Schaltflächentext: "Klicken zum Hinzufügen..." (in 6 Sprachen übersetzt)

3. Textverankerte Kommentare (Markdown)

Verwendet für: Markdown-Dateien (im Betrachter und Editor)

Funktionsweise: Der Benutzer markiert Text (anstatt zu klicken) und der Kommentar wird am ausgewählten Text mit umgebendem Kontext verankert, um widerstandsfähig gegen Bearbeitungen zu sein.

Dateityp Positionstyp Speicherung Benutzerinteraktion
Markdown markdown text_anchor {exact_text, prefix, suffix} + pdf_relative_y (Fallback) Text markieren zum Kommentieren

Textanker-Struktur:

{
  "exact_text": "the selected text",
  "prefix": "50 chars before selection",
  "suffix": "50 chars after selection",
  "selection_length": 18
}

Vorteile:

  • Kommentare überleben Dokumentbearbeitungen (textbasierte Suche, nicht Pixelposition)
  • Präfix-/Suffix-Kontext hilft, Text auch bei Verschiebung des exakten Treffers zu finden
  • Visuelle Hervorhebung des kommentierten Textes im Betrachter
  • Mobile Unterstützung mit schwebendem "Kommentar"-Button

Schaltflächentext: "Text markieren..." (in 6 Sprachen übersetzt)

Mobile Benutzeroberfläche:

  • Touch-Gerät wird automatisch erkannt
  • Benutzer führt langes Drücken aus, um Text zu markieren
  • Schwebender "Kommentar"-Button erscheint unterhalb der Auswahl (vermeidet Konflikt mit nativem Menü)
  • 600ms Verzögerung ermöglicht dem Benutzer, die Auswahlgriffe anzupassen, bevor der Button erscheint

Funktionsweise

Kommentarmodus aktivieren

  1. Öffnen Sie eine Dokumentvorschau (PDF, Bild, Markdown, Office oder CAD-Datei)
  2. Klicken Sie auf die Kommentar-Schaltfläche in der Vorschau-Werkzeugleiste
  3. Das Overlay wird aktiviert und Marker für bestehende Kommentare erscheinen
  4. Das Kommentarpanel erscheint unten mit Filteroptionen

Kommentar hinzufügen

Die Interaktion unterscheidet sich je nach Dateityp:

PDF, Bilder, Office, CAD

  1. Bei aktiviertem Kommentarmodus klicken Sie auf Hinzufügen im Kommentarpanel
  2. Klicken Sie auf das Dokument an der gewünschten Stelle
  3. Ein Dialog erscheint mit einem Texteingabefeld
  4. Geben Sie Ihren Kommentartext ein
  5. Klicken Sie auf Kommentar veröffentlichen, um den Kommentar zu erstellen
  6. Ein nummerierter Marker erscheint an der geklickten Position

Markdown

  1. Bei aktiviertem Kommentarmodus klicken Sie auf Hinzufügen im Kommentarpanel
  2. Markieren Sie Text durch Klicken und Ziehen (Desktop) oder langes Drücken und Ziehen der Griffe (Mobil)
  3. Auf dem Desktop: Dialog öffnet sich sofort nach der Auswahl
  4. Auf Mobilgeräten: Tippen Sie auf den schwebenden "Kommentar"-Button, der unterhalb der Auswahl erscheint
  5. Geben Sie Ihren Kommentartext ein
  6. Klicken Sie auf Kommentar veröffentlichen, um den Kommentar zu erstellen
  7. Ein nummerierter Marker erscheint am linken Rand, ausgerichtet am markierten Text

Bestehende Kommentare anzeigen

  • Marker: Nummerierte Sprechblasen-Marker zeigen Kommentarpositionen
    • Violette Marker: Offene Kommentare
    • Grüne Marker: Gelöste Kommentare
    • Oranges Badge: Anzahl der Antworten
  • Marker anklicken: Öffnet den Kommentarstrang-Dialog
  • Kommentarpanel: Unteres Panel mit allen Kommentaren
    • Auf-/Zuklappen durch Klicken auf die Kopfzeile
    • Nach Status filtern: Alle / Offen / Gelöst
    • Auf einen Kommentar klicken, um zu seiner Position zu navigieren
  • Navigation: "Zur Position gehen" oder das Panel verwenden, um zu Kommentaren zu springen

Auf Kommentare antworten

  1. Klicken Sie auf einen bestehenden Kommentar-Marker (oder wählen Sie aus dem Kommentarpanel)
  2. Der Strang-Dialog öffnet sich mit dem ursprünglichen Kommentar und allen Antworten
  3. Geben Sie Ihre Antwort in das Eingabefeld ein
  4. Klicken Sie auf Antwort veröffentlichen, um Ihre Antwort hinzuzufügen

Kommentare lösen

  1. Öffnen Sie einen Kommentarstrang
  2. Klicken Sie auf Als gelöst markieren (Schaltfläche über dem Antwort-Textfeld)
  3. Der Marker wird grün, um die Auflösung anzuzeigen
  4. Gelöste Kommentare können über die Dialog-Aktionen wieder geöffnet werden

Kommentare löschen

  1. Öffnen Sie einen Kommentarstrang
  2. Klicken Sie auf die Löschen-Schaltfläche (nur für den Kommentarautor oder Projektadministrator sichtbar)
  3. Bestätigen Sie die Löschung
  4. Der Marker wird vom Dokument entfernt

Office-Dokumente (Word, Excel, PowerPoint)

Office-Dateien erfordern eine besondere Behandlung, da Kommentare eine statische Leinwand für die Positionierung benötigen.

Funktionsweise

  1. Projekteinstellung: "Kommentare auf Office-Dateien erlauben" muss aktiviert sein
  2. Erstmalige Aktivierung: Beim Klicken auf die Kommentar-Schaltfläche bei einer Office-Datei:
    • Falls PDF zwischengespeichert: Wechselt sofort zum PDF-Betrachter
    • Falls nicht zwischengespeichert: Zeigt "Dokument wird konvertiert..." Ladezustand
  3. Konvertierung: LibreOffice konvertiert die Office-Datei in PDF (wird einmal ausgeführt, dauerhaft zwischengespeichert)
  4. Ergebnis: PDF-Betrachter mit Kommentar-Overlay erscheint
  5. Badge: "Kommentarmodus"-Badge erscheint in der Kopfzeile bei Anzeige des konvertierten PDFs

Konfiguration

Projektbesitzer können Office-Kommentare in den Projekteinstellungen aktivieren:

  1. Navigieren Sie zu Einstellungen > Dateieinstellungen
  2. Aktivieren Sie "Kommentare auf Office-Dateien erlauben"
  3. Speichern Sie die Einstellungen

Einschränkungen

  • Kommentare werden auf der PDF-Konvertierung platziert, nicht auf der Original-Office-Datei
  • Komplexe Formatierungen können im PDF anders dargestellt werden
  • Excel-Formeln zeigen nur berechnete Werte
  • PowerPoint-Animationen/Übergänge gehen verloren

CAD/BIM-Dateien (Autodesk APS)

Das Kommentarsystem ist vollständig in den Autodesk Viewer für CAD- und BIM-Dateien integriert.

3D-Modelle (IFC, RVT usw.)

Für 3D-Modelle werden Kommentare verankert mittels:

  • Weltkoordinaten: Der 3D-Punkt, auf den der Benutzer geklickt hat
  • Element-ID: Das spezifische Modellelement (wenn der Treffertest erfolgreich ist)
  • Kamerazustand: Die exakte Ansichtsposition bei der Kommentarerstellung

Verhalten:

  • Marker aktualisieren ihre Position in Echtzeit, wenn Sie das Modell drehen/zoomen
  • "Zur Position gehen" stellt die exakte Kameraansicht wieder her, die bei der Kommentarerstellung bestand
  • Funktioniert mit Explosionsansichten und Schnittebenen

2D-Zeichnungen (DWG, DXF)

Für 2D-Zeichnungen verwenden Kommentare:

  • Modellkoordinaten: Position in Zeichnungseinheiten (nicht Bildschirmpixel)
  • Blatt-GUID: Identifiziert, auf welchem Blatt sich der Kommentar befindet

Verhalten:

  • Marker bleiben beim Zoomen/Schwenken an Zeichnungspunkten befestigt
  • Kameraänderungsereignisse lösen Marker-Neudarstellung aus
  • Funktioniert über verschiedene Zoomstufen und Schwenkpositionen

Technische Details

Das System verwendet Autodesk Viewer SDK-Methoden:

Operation Methode
Klickposition ermitteln (3D) viewer.impl.hitTest()
Klickposition ermitteln (2D) viewer.clientToWorld()
Markerposition rendern viewer.impl.worldToClient()
Zum Kommentar navigieren viewer.restoreState()
Kameraänderungen verfolgen CAMERA_CHANGE_EVENT-Listener

Echtzeit-Zusammenarbeit

Kommentare werden in Echtzeit über alle verbundenen Benutzer synchronisiert.

PubSub-Topics

Topic-Format: document_comments:{content_item_id}

Ereignisse

Ereignis Beschreibung
comment_added Neuer Kommentar von einem anderen Benutzer erstellt
comment_updated Kommentar bearbeitet, Antwort hinzugefügt oder Status geändert
comment_deleted Kommentar von einem anderen Benutzer entfernt

Verhalten

  • Neue Marker erscheinen sofort, wenn andere Benutzer Kommentare hinzufügen
  • Antwortanzahlen werden in Echtzeit aktualisiert
  • Auflösungsstatus wird über alle Betrachter synchronisiert
  • Wenn ein gelöschter Kommentar angezeigt wird, schließt sich der Dialog automatisch

Benutzeroberfläche

Kommentar-Marker

Marker verwenden ein Sprechblasen-Design mit Zeiger:

   ┌───────┐
   │  1.2  │  ← Nummer (Seite.Index oder nur Index)
   └───┬───┘
       ▽     ← Zeiger zeigt die exakte Position an

Gestaltung:

  • Hintergrund: Indigo (#6366f1) für offen, Grün (#22c55e) für gelöst
  • Antwort-Badge: Orange (#f97316) Kreis in der oberen rechten Ecke
  • Hover-Effekt: Leichte Vergrößerung (1,1x)
  • Schatten: Schlagschatten für Sichtbarkeit auf jedem Hintergrund

Kommentar-Dialog

Der Dialog zeigt:

Kopfzeile:

  • Name und Avatar des Kommentarautors
  • Zeitstempel (relativ, z.B. "vor 2 Stunden")
  • Positionsinformation (z.B. "Seite 3" oder "3D-Punkt")

Inhalt:

  • Kommentartext
  • Antworten (als Strang, chronologisch)
  • Antwort-Eingabefeld

Aktionen (Strangansicht):

  • Als gelöst markieren: Schaltfläche über dem Antwortformular (grün, hervorgehoben)
  • Antwort veröffentlichen: Antwort-Absende-Schaltfläche
  • Löschen: Papierkorb-Symbol (nur Autor/Admin)
  • Wieder öffnen: Verfügbar wenn Kommentar gelöst ist
  • Schließen: Dialog schließen

Architektur

Datenbankschema

Tabelle: document_comments

Spalte Typ Beschreibung
id UUID Primärschlüssel
content Text Kommentartext
content_item_id UUID FK zu content_items
user_id UUID FK zu users (Autor)
project_id UUID FK zu projects
parent_id UUID FK zu document_comments (für Antworten)
position_type String pdf_page, image, markdown, aps_3d, aps_2d
pdf_page_number Integer Seitennummer (nur PDF)
pdf_relative_x Float X-Position 0,0-1,0 (oder Pixel für Markdown)
pdf_relative_y Float Y-Position 0,0-1,0 (oder Pixel für Markdown)
aps_world_coordinates Map {x, y, z} für CAD
aps_db_id Integer Autodesk-Element-ID
aps_camera_state Map Viewer-Zustand für Navigation
aps_sheet_guid String 2D-Blatt-Bezeichner
resolved Boolean Auflösungsstatus
resolved_at DateTime Zeitpunkt der Auflösung
resolved_by_id UUID FK zu users
inserted_at DateTime Erstellungszeitstempel
updated_at DateTime Letzte Änderung

Backend-Module

Modul Zweck
Sutram.Content.DocumentComment Ecto-Schema mit Validierungen
Sutram.Content CRUD-Funktionen für Kommentare
SutramWeb.ProjectLive.Content.CommentHandler LiveView-Event-Handler
SutramWeb.ProjectLive.Components.CommentModal Dialog-LiveComponent
SutramWeb.ProjectLive.Components.CommentsPanel Unteres Panel mit Filtern
SutramWeb.ProjectLive.Components.PreviewModal Vorschau mit Overlay

Frontend (JavaScript)

Datei Zweck
assets/js/hooks/comment_overlay.js Haupt-Overlay-Hook
assets/js/viewers/pdf_viewer.js PDF-Betrachter mit Seitenverfolgung
assets/js/viewers/autodesk_viewer.js CAD-Betrachter mit getViewerInstance()

Schlüsselfunktionen

CommentOverlay Hook:

  • calculatePdfPosition(): Klick in PDF-Koordinaten umwandeln
  • calculateImagePosition(): Klick in Bildkoordinaten umwandeln
  • calculateMarkdownPosition(): Klick in Markdown-Pixelkoordinaten umwandeln
  • calculateApsPosition(): Klick in CAD-Weltkoordinaten umwandeln
  • calculateScreenPosition(): Gespeicherte Position in Bildschirmpixel umwandeln
  • renderMarkers(): Alle sichtbaren Marker zeichnen
  • navigateToComment(): Zum Kommentarort scrollen/zoomen

Konfiguration

Projekteinstellungen

Einstellung Standard Beschreibung
allow_office_comments false Kommentare auf Office-Dateien aktivieren

Anwendungseinstellungen

Kommentare sind standardmäßig aktiviert für:

  • PDF-Dateien
  • Bilddateien
  • CAD-Dateien (wenn APS konfiguriert ist)

Office-Dateien erfordern eine explizite Aktivierung auf Projektebene aufgrund der PDF-Konvertierungsanforderung.

Fehlerbehebung

Kommentare werden nicht angezeigt

Ursache: Kommentarmodus nicht aktiviert

Lösung:

  1. Klicken Sie auf die Kommentar-Schaltfläche in der Vorschau-Werkzeugleiste
  2. Warten Sie, bis die Marker gerendert sind
  3. Überprüfen Sie die Browserkonsole auf Fehler

Marker an falscher Position

Ursache: Größenänderung oder Zoom wurde nach dem Rendern der Marker geändert

Lösung:

  • Marker positionieren sich bei Größenänderung/Zoom automatisch neu
  • Falls weiterhin falsch, schließen und öffnen Sie die Vorschau erneut

CAD-Kommentare werden nicht gespeichert

Ursache: APS-Betrachter noch nicht vollständig geladen

Lösung:

  1. Warten Sie, bis das 3D-Modell vollständig geladen ist
  2. Versuchen Sie, auf eine sichtbare Oberfläche zu klicken
  3. Überprüfen Sie, ob der Betrachter auf Navigation reagiert

Office-Kommentar-Schaltfläche fehlt

Ursache: Projekteinstellung nicht aktiviert

Lösung:

  1. Gehen Sie zu Projekteinstellungen > Dateieinstellungen
  2. Aktivieren Sie "Kommentare auf Office-Dateien erlauben"
  3. Speichern und aktualisieren

API-Referenz

LiveView-Ereignisse (Client an Server)

Ereignis Payload Beschreibung
position_selected Positionsdaten Benutzer hat geklickt, um Kommentar hinzuzufügen
marker_clicked {comment_id, marker_number} Benutzer hat auf bestehenden Marker geklickt
create_comment {content} Neuen Kommentar speichern
create_reply {content, parent_id} Antwort zum Strang hinzufügen
resolve_comment {comment_id} Als gelöst markieren
reopen_comment {comment_id} Gelösten Kommentar wieder öffnen
delete_comment {comment_id} Kommentar entfernen
navigate_to_comment {comment_id} Zur Position springen
request_markers {content_item_id} Initiale Marker anfordern

Push-Ereignisse (Server an Client)

Ereignis Payload Beschreibung
render_markers {markers: [...]} Vollständige Liste der Marker
add_marker {marker: {...}} Einzelner neuer Marker
update_marker {marker: {...}} Aktualisierte Markerdaten
remove_marker {comment_id} Marker löschen
navigate_to_comment {comment: {...}} Navigation auslösen

Versionshistorie

Version Datum Änderungen
v0.58.0 2025-12-22 Initiale PDF-Kommentare mit Diskussionssträngen
v0.59.0 2025-12-23 Kommentare im Chat-Kontext
v0.60.0 2025-12-24 Unterstützung für Bildkommentare
v0.61.0 2025-12-24 Office-Datei-Kommentare (über PDF)
v0.61.1 2025-12-24 CAD/APS-Kommentare (2D und 3D)
v0.62.0 2025-12-24 Onboarding-Toast-Hinweis
v0.63.0 2025-12-25 Kommentarpanel (V3) - Unteres Panel mit Filtern und Navigation
v0.64.0 2025-12-26 Unterstützung für Markdown-Kommentare
v0.64.1 2025-12-26 UI-Verbesserungen: Neu organisierte Dialog-Aktionen, Toast-Hinweis entfernt
v0.65.0 2025-12-26 Kommentarmodus im Markdown-Editor mit manueller Positionsanpassung
v0.65.1 2025-12-29 Mobile Textauswahl-Unterstützung für Markdown-Kommentare
v0.65.2 2025-12-29 UX-Verbesserungen: Schwebender Button unterhalb der Auswahl positioniert, um natives Menü zu vermeiden
v0.65.3 2025-12-29 Internationalisierung: Schwebender "Kommentar"-Button in 6 Sprachen übersetzt

Kommentarpanel (V3)

Das Kommentarpanel ist ein unteres Panel, das alle Kommentare im Dokument auflistet und eine einheitliche Navigationserfahrung für Mobil- und Desktopgeräte bietet.

Layout

Das Panel verwendet ein Design als unteres Panel (einheitlich für Mobil und Desktop):

┌─────────────────────────────────────────────────┐
│                                                 │
│              Betrachter (PDF/Bild/CAD)          │
│                                                 │
│                       📍                        │
│                                                 │
├─────────────────────────────────────────────────┤
│ 💬 4 Kommentare                             ▼  │  ← Klicken klappt auf
├─────────────────────────────────────────────────┤
│ ◉ Alle   ○ Offen   ○ Gelöst                    │  ← Filter
├─────────────────────────────────────────────────┤
│ ┌─────────────────────────────────────────────┐ │
│ │ 🗨️1 👤 Hans · vor 2h                       │ │
│ │     Prüfen ob die Bemaßung korrekt ist...   │ │
│ └─────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────┐ │
│ │ 🗨️2 👤 Maria · vor 1T                  ✅  │ │
│ │     Konflikt mit der bestehenden Struktur   │ │
│ └─────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────┘

Zustände

Zustand Beschreibung
Minimiert Zeigt nur die Kopfzeile mit Kommentaranzahl (48px Höhe)
Aufgeklappt Zeigt Filter und scrollbare Liste (max. 50vh)

Funktionen

  • Umschalten: Kopfzeile klicken zum Auf-/Zuklappen
  • Filter: Alle / Offen / Gelöst (Optionsfelder)
  • Kommentarliste: Scrollbare Liste mit Sprechblasen-Markern im gleichen Stil wie auf der Leinwand
  • Navigation: Auf einen Kommentar klicken, um zu seiner Position zu springen (Seitenwechsel bei PDF, Kamerawiederherstellung bei CAD)
  • Echtzeit: Aktualisiert sich automatisch über bestehendes PubSub

Marker-Stil

Kommentare in der Liste verwenden den gleichen Sprechblasen-Marker-Stil wie auf der Leinwand:

   ┌───────┐
   │   1   │  ← Nummer (Einfügereihenfolge)
   └───┬───┘
       ▽     ← Zeiger (Sprechblasen-Schwanz)
  • Hintergrund: Indigo (#6366f1) für offen, Grün (#22c55e) für gelöst
  • Antwort-Badge: Orange (#f97316) in der oberen rechten Ecke
  • Schlagschatten: Für Sichtbarkeit

Technische Details

Neue Komponente: SutramWeb.ProjectLive.Components.CommentsPanel

Props:

  • comments - Liste von DocumentComment-Structs
  • expanded - Boolean (Panel-Zustand)
  • filter - Atom (:all, :open, :resolved)

Ereignisse (an das übergeordnete Element über send/2 gesendet):

  • {:comments_panel, :toggle} - Auf-/Zuklappen umschalten
  • {:comments_panel, :filter, filter} - Filter ändern
  • {:comments_panel, :go_to_comment, comment_id} - Zum Kommentar navigieren

Zustandsverwaltung (in Content LiveView):

  • comments_panel_expanded - Boolean
  • comments_panel_filter - Atom

Markdown-Editor-Kommentarmodus (v0.65.0)

Der Markdown-Editor enthält einen dedizierten Kommentarmodus, der es Benutzern ermöglicht, Kommentarmarker beim Bearbeiten anzuzeigen und neu zu positionieren. Dies löst das Problem, dass Marker nach der Bearbeitung von Markdown-Inhalten falsch ausgerichtet werden (da Markdown absolute Pixelkoordinaten verwendet).

Zwei Modi

Modus Beschreibung
Bearbeitung (Standard) Normaler Milkdown WYSIWYG-Editor, keine Marker sichtbar
Kommentare Gerenderter Vorschau mit Kommentar-Overlay und Seitenpanel

Layout (Kommentarmodus)

┌─────────────────────────────────────────────────────────────────┐
│  ← Zurück    [Bearbeitung] [Kommentare 📍3]      Hochladen │ Kopfzeile │
├─────────────────────────────────────┬───────────────────────────┤
│                                     │ 💬 3 Kommentare           │
│   Gerenderte Markdown-Vorschau      │ ─────────────────────────│
│   (schreibgeschützt)                │ ◉ Alle ○ Offen ○ Gelöst  │
│                                     │ ─────────────────────────│
│        📍 Marker 1                  │ [1] Hans · vor 2h         │
│                                     │     Diesen Abschnitt prüfen│
│        📍 Marker 2                  │     [Anpassen] [Gehe zu]  │
│                                     │ ─────────────────────────│
│                                     │ [2] Maria · vor 1T   ✅   │
│                                     │     Behoben               │
└─────────────────────────────────────┴───────────────────────────┘

Manuelle Positionsanpassung

Wenn Markdown-Inhalte bearbeitet werden, können Kommentarmarker falsch ausgerichtet werden, weil sie absolute Pixelkoordinaten verwenden. Benutzer können Marker manuell neu positionieren:

  1. Wechseln Sie im Markdown-Editor in den Kommentarmodus
  2. Finden Sie den falsch ausgerichteten Kommentar im Seitenpanel
  3. Klicken Sie auf die Schaltfläche "Position anpassen"
  4. Der Cursor wechselt zum Fadenkreuz, das Seitenpanel zeigt "Auf die neue Position klicken"
  5. Klicken Sie auf die korrekte Stelle in der Vorschau
  6. Der Marker wird an die neue Position verschoben und gespeichert

Mobile Einschränkung

Der Kommentarmodus ist auf Mobilgeräten nicht verfügbar (Viewport < 768px). Ein Tooltip auf der deaktivierten Schaltfläche erklärt: "Verwenden Sie einen Desktop-Computer, um Kommentare zu verwalten".

Technische Details

Neue Assigns (in markdown_editor.ex):

  • editor_mode - Atom (:editing | :comments)
  • comments - Liste von DocumentComment-Structs
  • comments_panel_expanded - Boolean
  • comments_panel_filter - Atom (:all | :open | :resolved)
  • repositioning_comment_id - UUID oder nil

Neue Ereignisse:

  • toggle_editor_mode - Zwischen Bearbeitungs- und Kommentarmodus wechseln
  • start_reposition - Neupositionierungsmodus für einen bestimmten Kommentar starten
  • cancel_reposition - Neupositionierungsmodus beenden
  • update_marker_position - Neue Position aus dem Neupositionierungs-Klick speichern
  • go_to_comment - Zum Kommentarort navigieren/scrollen

JavaScript-Änderungen (comment_overlay.js):

  • repositioningCommentId-Zustand hinzugefügt
  • enter_reposition_mode / exit_reposition_mode-Event-Handler hinzugefügt
  • Klick-Handler modifiziert, um Neupositionierungsmodus zu erkennen und update_marker_position zu senden
  • Markdown-Element-Selektoren aktualisiert, um sowohl im Betrachter- als auch im Editor-Kontext zu funktionieren

Dokumentversion: 1.3 Zuletzt aktualisiert: 29. Dezember 2025 Autor: Sutram-Entwicklungsteam

Zurück zur Dokumentation