NgMultiselect

Eine Angular Multiselect-Komponente mit Gruppierungsfunktion. Die Komponente unterstützt:

• Mehrfachauswahl von Elementen
• Gruppierung von Optionen
• Suchfunktion
• Anpassbare Anzeige der Elemente
• Responsive Design
• Vorauswahl von Elementen
• Flexibles Styling durch CSS-Variablen
• Einfache Integration in bestehende Projekte

Installation

npm install @ferdifighter/ng-multiselect

Verwendung

import { NgMultiselectComponent, MultiSelectOption, MultiSelectOptgroup } from '@ferdifighter/ng-multiselect';

@Component({
  // ...
  imports: [NgMultiselectComponent]
})
export class AppComponent {
  // Beispiel für gruppierte Optionen
  gruppen: MultiSelectOptgroup[] = [
    {
      label: 'Gruppe 1',
      options: [
        { value: '1', label: 'Option 1' },
        { value: '2', label: 'Option 2' }
      ]
    },
    {
      label: 'Gruppe 2',
      options: [
        { value: '3', label: 'Option 3' },
        { value: '4', label: 'Option 4' }
      ]
    }
  ];

  // Vorauswahl von Elementen
  vorauswahl: MultiSelectOption[] = [
    { value: '1', label: 'Option 1' }
  ];

  // Optionale Anzeige-Funktion
  anzeigeFunktion = (option: MultiSelectOption) => option.label;

  // Event-Handler für Auswahländerungen
  onSelection(auswahl: MultiSelectOption[]) {
    console.log('Ausgewählte Elemente:', auswahl);
  }
}

<lib-ng-multiselect
  [optgroups]="gruppen"
  [useOptgroups]="true"
  [placeholder]="'Bitte wählen...'"
  [selectedTitle]="'Meine Auswahl'"
  [selected]="vorauswahl"
  [displayWith]="anzeigeFunktion"
  (selectionChange)="onSelection($event)">
</lib-ng-multiselect>

Responsive Design

Die Komponente unterstützt verschiedene responsive Modi:

Responsive Modus

<lib-ng-multiselect
  [optgroups]="gruppen"
  [useOptgroups]="true"
  [responsive]="true"
  [maxHeight]="'400px'"
  [minHeight]="'200px'"
  [containerHeight]="'100%'"
  (selectionChange)="onSelection($event)">
</lib-ng-multiselect>

Automatische Höhe

<lib-ng-multiselect
  [optgroups]="gruppen"
  [useOptgroups]="true"
  [autoHeight]="true"
  [maxHeight]="'none'"
  [containerHeight]="'auto'"
  (selectionChange)="onSelection($event)">
</lib-ng-multiselect>

Feste Höhe mit Scrollbalken

<lib-ng-multiselect
  [optgroups]="gruppen"
  [useOptgroups]="true"
  [maxHeight]="'300px'"
  [minHeight]="'150px'"
  [containerHeight]="'400px'"
  (selectionChange)="onSelection($event)">
</lib-ng-multiselect>

Styling

Die Komponente verwendet CSS-Variablen für einfache Anpassung an Ihr Design-System:

lib-ng-multiselect {
  /* Farben */
  --ms-border-color: #your-border-color;
  --ms-background-color: #your-background;
  --ms-header-background: #your-header-background;
  --ms-hover-background: #your-hover-color;
  --ms-selected-background: #your-selected-color;
  --ms-optgroup-background: #your-optgroup-background;
  --ms-optgroup-hover: #your-optgroup-hover;

  /* Typografie */
  --ms-font-family: your-font-family;
  --ms-font-size: your-font-size;

  /* Layout */
  --ms-border-radius: your-border-radius;
  --ms-padding: your-padding;
  --ms-gap: your-gap;
  --ms-list-max-height: your-max-height;
  --ms-disabled-opacity: your-disabled-opacity;
}

Standardwerte

:host {
  --ms-border-color: #ccc;
  --ms-border-radius: 4px;
  --ms-background-color: #fff;
  --ms-header-background: #f5f5f5;
  --ms-hover-background: #f0f0f0;
  --ms-selected-background: #e3f2fd;
  --ms-disabled-opacity: 0.5;
  --ms-font-family: inherit;
  --ms-font-size: inherit;
  --ms-padding: 0.5rem;
  --ms-gap: 1rem;
  --ms-list-max-height: 300px;
  --ms-optgroup-background: #f8f9fa;
  --ms-optgroup-hover: #e9ecef;
}

Optionen

Inputs

| Option | Typ | Standardwert | Beschreibung | |---------------------|--------------------------|------------------------|------------------------------------------------| | options | MultiSelectOption[] | [] | Flache Liste von Optionen | | optgroups | MultiSelectOptgroup[] | [] | Gruppierte Optionen | | useOptgroups | boolean | false | true = Gruppenmodus, false = flache Liste | | placeholder | string | 'Suchen...' | Platzhaltertext für die Suche | | selectedTitle | string | 'Ausgewählte Elemente' | Titel für den Bereich der ausgewählten Elemente | | selected | MultiSelectOption[] | [] | Vorauswahl von Elementen | | displayWith | Funktion | undefined | Optionale Anzeige-Funktion für Labels | | optgroupStyle | MultiSelectStyles | {...} | Styling für Optgroup-Labels | | optionStyle | MultiSelectStyles | {...} | Styling für Optionen | | selectedOptionStyle | MultiSelectStyles | {...} | Styling für ausgewählte Optionen | | maxHeight | string | '300px' | Maximale Höhe der Listen | | minHeight | string | '100px' | Minimale Höhe der Listen | | responsive | boolean | false | Aktiviert responsive Modus | | autoHeight | boolean | false | Automatische Höhenanpassung | | containerHeight | string | 'auto' | Höhe des Hauptcontainers |

Outputs

| Event | Typ | Beschreibung | |-----------------|--------------------------|------------------------------------------------| | selectionChange | MultiSelectOption[] | Wird bei jeder Auswahländerung ausgelöst |

Interfaces

interface MultiSelectOption {
  value: string | number;
  label: string;
  disabled?: boolean;
  groupLabel?: string;
}

interface MultiSelectOptgroup {
  label: string;
  options: MultiSelectOption[];
  disabled?: boolean;
}

interface MultiSelectStyles {
  [key: string]: string;
}

Beispiel: Styling anpassen

@Component({
  // ...
})
export class AppComponent {
  optgroupStyle = {
    'padding': '0.4rem 0.7rem',
    'fontWeight': 'bold',
    'background': '#f8f9fa',
    'borderBottom': '1px solid #eee',
    'fontSize': '1rem',
    'margin': '0'
  };

  optionStyle = {
    'paddingLeft': '1.5rem',
    'paddingTop': '0.2rem',
    'paddingBottom': '0.2rem',
    'margin': '0',
    'background': '#fff',
    'fontWeight': 'normal',
    'borderBottom': 'none'
  };

  selectedOptionStyle = {
    'paddingLeft': '1.5rem',
    'paddingTop': '0.2rem',
    'paddingBottom': '0.2rem',
    'margin': '0',
    'background': '#fff',
    'fontWeight': 'normal',
    'borderBottom': 'none'
  };
}

<lib-ng-multiselect
  [optgroups]="gruppen"
  [useOptgroups]="true"
  [optgroupStyle]="optgroupStyle"
  [optionStyle]="optionStyle"
  [selectedOptionStyle]="selectedOptionStyle"
  (selectionChange)="onSelection($event)">
</lib-ng-multiselect>

Beispiel: Statische Daten

// Komponente
import { MultiSelectOptgroup, MultiSelectOption } from 'ng-multiselect';

export class ExampleComponent {
  gruppen: MultiSelectOptgroup[] = [
    {
      label: 'Gruppe A',
      options: [
        { value: 1, label: 'Option 1' },
        { value: 2, label: 'Option 2' }
      ]
    },
    {
      label: 'Gruppe B',
      options: [
        { value: 3, label: 'Option 3' }
      ]
    }
  ];
  anzeigeFunktion = (option: MultiSelectOption) => option.label;
  onSelection(auswahl: MultiSelectOption[]) {
    console.log(auswahl);
  }
}

Beispiel: Asynchrone Daten (z.B. REST, TypeORM)

import { NgMultiselectService, MultiSelectOption } from 'ng-multiselect';

export class ExampleComponent {
  optionen: MultiSelectOption[] = [];
  constructor(private msService: NgMultiselectService) {}

  ngOnInit() {
    this.msService.loadFromDatabase({
      type: 'mysql',
      host: 'localhost',
      database: 'test',
      table: 'users',
      valueField: 'id',
      labelField: 'name'
    }).subscribe(data => this.optionen = data);
  }
}

Integration in bestehende Projekte

Die Komponente ist so konzipiert, dass sie sich nahtlos in bestehende Projekte integrieren lässt:

1. Styling-Integration:

   • Verwendet CSS-Variablen für einfache Anpassung
   • Erbt Schriftart und -größe vom übergeordneten Element
   • BEM-Methodologie für Styling-Isolation

2. Responsive Design:

   • Flexibles Layout
   • Anpassbare Höhen und Breiten
   • Mobile-freundlich

3. Barrierefreiheit:

   • Semantische HTML-Struktur
   • Tastatur-Navigation
   • ARIA-Attribute

Weitere Hinweise

• Die Komponente ist für die Nutzung in eigenen Projekten und als npm-Paket vorbereitet
• Für Backend-Anbindung (z.B. TypeORM/NestJS) siehe Beispiel im example-Ordner
• Die Komponente verwendet BEM-Methodologie für bessere Styling-Isolation
• Alle Styling-Eigenschaften können über CSS-Variablen angepasst werden

CHANGELOG

[1.2.4] - 2025-09-18

Behoben

• Daten korrigiert: Alle Changelog-Daten auf korrekte Daten aktualisiert (2025-09-18)
• Konsistenz: Einheitliche Datumsformatierung im gesamten Changelog

[1.2.3] - 2025-09-18

Behoben

• README.md: Changelog in README.md aktualisiert für npmjs-Anzeige
• Dokumentation: Neue responsive Input-Properties zur Dokumentation hinzugefügt
• Beispiele: Responsive Design-Beispiele zur README.md hinzugefügt

[1.2.2] - 2025-09-18

Behoben

• Changelog: Korrektur des Datums für Version 1.2.1

[1.2.1] - 2025-09-18

Hinzugefügt

• Responsive Design: Neue Input-Properties für responsive Verhalten
  • responsive: Aktiviert responsive Modus (boolean)
  • autoHeight: Automatische Höhenanpassung (boolean)
  • maxHeight: Maximale Höhe der Listen (string, Standard: '300px')
  • minHeight: Minimale Höhe der Listen (string, Standard: '100px')
  • containerHeight: Höhe des Hauptcontainers (string, Standard: 'auto')
• Verbesserte Scrollbalken: Dünne, ansprechende Scrollbalken mit Hover-Effekten
• Sticky Optgroup-Labels: Gruppen-Überschriften bleiben beim Scrollen sichtbar
• Responsive Breakpoints: Automatische Anpassung für mobile Geräte
  • Tablet: ≤ 768px (vertikales Layout)
  • Mobile: ≤ 480px (optimierte Höhen)
• Dynamische CSS-Variablen: Automatische Anpassung der Styling-Parameter
• Flexible Container: Container passen sich automatisch an umliegende Elemente an

Verbessert

• CSS-Architektur: Erweiterte CSS-Variablen für bessere Anpassbarkeit
• Mobile Experience: Optimiertes Layout für kleinere Bildschirme
• Scroll-Verhalten: Verbesserte Benutzerfreundlichkeit bei vielen Einträgen
• Performance: Effizientere CSS-Klassen-Verwaltung

Technische Details

• Neue CSS-Klassen: ng-multiselect--responsive, ng-multiselect--auto-height, ng-multiselect--fixed-height
• Erweiterte CSS-Variablen: --ms-list-min-height, --ms-container-height
• Responsive Media Queries für verschiedene Bildschirmgrößen
• Verbesserte Scrollbar-Styling für Webkit und Firefox

[1.2.0] - 2025-09-18

Hinzugefügt

• Neue Styling-Inputs für feinere Anpassung:
  • optgroupStyle für Optgroup-Labels
  • optionStyle für Optionen
  • selectedOptionStyle für ausgewählte Optionen
• Verbesserte Styling-Dokumentation
• Beispiel für die Verwendung der neuen Styling-Optionen

[1.1.1] - 2025-09-18

Geändert

• README.md um CHANGELOG erweitert
• Verbesserte Dokumentation der Versionshistorie

[1.1.0] - 2025-09-18

Hinzugefügt

• Flexibles Styling-System mit CSS-Variablen
• BEM-Methodologie für bessere Styling-Isolation
• Verbesserte Integration in bestehende Projekte
• Anpassbare Typografie und Layout-Eigenschaften
• Detaillierte Styling-Dokumentation

[1.0.4] - 2025-09-17

Geändert

• Verbesserte Fehlerbehandlung
• Optimierte Performance bei großen Datenmengen

[1.0.3] - 2025-09-16

Hinzugefügt

• Unterstützung für TypeORM/NestJS
• Verbesserte Dokumentation

[1.0.2] - 2025-09-15

Geändert

• Bugfixes für Gruppierungsfunktion
• Verbesserte Suchfunktion

[1.0.1] - 2025-09-14

Hinzugefügt

• Gruppierungsfunktion
• Suchfunktion
• Vorauswahl von Elementen

[1.0.0] - 2025-09-13

Hinzugefügt

• Erste Version der Multiselect-Komponente
• Basis-Funktionalität für Mehrfachauswahl
• Responsive Design