Native UI konfigurieren

Dies ist die Einstellungsreferenz. Beginnen Sie mit der Funktionsweise der Projektion, anschließend mit Ionic-Einrichtung oder HTML-Einrichtung für die Installation.

Rufen Sie enableNativeUI() einmal auf, nachdem das DOM Ihrer Anwendung eingebunden wurde. Ionic- und ausdrücklich markierte HTML-Bedienelemente verwenden dieselben Standard-Swift-Renderer. Das Theme ist optional; Web-Layout, Safe Areas und Abstände liegen bei Ihrer App oder Ihrem Theme.

import { enableNativeUI } from '@rdlabo/capacitor-native-ui';

const shell = await enableNativeUI();

Importieren Sie ohne Ionic dieselbe API aus @rdlabo/capacitor-native-ui/core. Dieser Einstiegspunkt lädt Ionics optionale Popover-Integration nicht. Siehe reines HTML.

Plattformverhalten

Web-Seitenleisten benötigen das Ionic-Seitenleistenlayout oder einen anwendungseigenen HTML-webHost. Einstellungen schaffen keine Gerätefähigkeit.

Das aus HTML abgeleitete Hell-/Dunkelverhalten beschreibt Helle und dunkle Darstellung. Die Darstellung wird im Web-CSS konfiguriert, nicht über eine Startoption.

Alle Einstellungen

controls wählt Standardwerte für Auswahl und Gruppierung. verticalBars konfiguriert die Seitenleiste. ionic konfiguriert Ionic-Erkennung und Darstellung. Ausgelassene Felder in controls sind standardmäßig true, auch bei Teilobjekten.

const shell = await enableNativeUI({
  root: document.body,
  controls: {
    buttonGroup: true,
    button: true,
    backButton: true,
    tabs: true,
    segment: true,
    fab: true,
  },
  verticalBars: {
    enabled: true,
    // Optional: placement: { edge: 'trailing', webHost: appOwnedHost },
  },
  extensions: [],
  ionic: {
    auto: true,
    verticalBars: {
      buttonProjection: 'system',
      buttonDefaultFill: 'glass',
      popover: false,
    },
  },
  debug: false,
});

Standardwerte für die Auswahl

Jedes Bedienelement akzeptiert ControlProjection. controls selbst akzeptiert dieselben Werte als Kurzform für alle sechs Felder.

Horizontal und vertikal beschreiben die Position des Bedienelements, nicht Bildschirmausrichtung oder Gerätemodell. Diese Standardwerte verschieben kein Bedienelement, ergänzen keine fehlende Gerätefähigkeit und machen nicht unterstütztes Markup nicht geeignet.

Lokale Attribute data-horizontal-bars="true|false" und data-vertical-bars="true|false" überschreiben den jeweiligen Auswahlstandard. Auf ion-buttons steuern sie nur die Gruppierung. Explizite data-native-ui-Quellen sind von diesen Standardwerten unabhängig. Strukturelle Ausschlüsse und Seitenleistenverfügbarkeit gelten weiterhin. Siehe Werkzeugleistenauswahl und Gruppierung.

Weitere Einstellungen

HTML-Host für die Fallback-Seitenleiste

webHost ist eine optionale, von der Anwendung gestaltete HTML-Fallback-Seitenleiste. Es gelten folgende Anforderungen:

• Mit demselben Dokument wie root verbunden.
• Außerhalb von root; keines der Elemente darf das andere enthalten.
• Von der Anwendung gestaltet und positioniert, einschließlich reservierter Inhaltsabstände.

Verwenden Sie einen begrenzten root, etwa Ihr <main>, mit einem benachbarten Host; der Standard document.body erlaubt keinen solchen Host. Ohne Host bleiben die Originalbedienelemente sichtbar, wenn HTML-Seitenleisten nicht verfügbar sind. Ionics bestehendes Seitenleistenlayout verwendet seinen eigenen Fallback-Adapter.

HTML unterstützt derzeit Schaltflächen und Zurückschaltflächen. Reader für Tabs, Segmente und FABs bleiben Ionic-Adapter; deren Aktivierung leitet keine entsprechenden Strukturen aus beliebigem HTML ab.

Häufige Konfigurationen

// Ionic oder HTML: alle unterstützten Bedienelemente, Seitenleistenunterstützung standardmäßig aktiv.
const shell = await enableNativeUI();

// Alternative: automatische Auswahl nur in der Seitenleiste.
const railOnly = await enableNativeUI({ controls: 'verticalOnly' });

// Alternative: automatisch nur Tabs auswählen.
const tabsOnly = await enableNativeUI({
  controls: { buttonGroup: false, button: false, backButton: false, tabs: true, segment: false, fab: false },
});

Dies sind Alternativen: Starten Sie nur eine Shell. Wiederholte gleichwertige Starteinstellungen liefern deren Handle zurück; andere Einstellungen erfordern zunächst das Zerstören der vorherigen Shell.

controls: false deaktiviert jede standardmäßige Auswahl und Gruppierung, während lokale Attribute weiterhin aktivieren können. ionic: { auto: false } deaktiviert dagegen die automatische Ionic-Erkennung vollständig. Keine der beiden Optionen deaktiviert explizite HTML-Quellen oder Erweiterungen.

verticalBars.enabled: false belässt Seitenleisten-Bedienelemente unabhängig von der Auswahl im Web. Gewöhnliche Bedienelemente bleiben unbeeinflusst. data-native-ui-placement="element" erhält die ursprüngliche Position eines expliziten Bedienelements, auch mit controls: 'verticalOnly'. Setzen Sie die Position bei Ionic-Gruppen auf die gesamte ion-buttons-Gruppe, damit ihre gemeinsame native Fläche genau eine Position hat.

Bedienelemente in einer angepassten Ionic-App explizit auswählen

Deaktivieren Sie automatische Ionic-Projektion und behalten Sie die native Seitenleiste sowie Ihre eigenen Erweiterungen:

const shell = await enableNativeUI({
  root: document.querySelector<HTMLElement>('#content')!,
  ionic: { auto: false },
  verticalBars: {
    enabled: true,
    placement: {
      edge: 'trailing',
      webHost: document.querySelector<HTMLElement>('#rail')!,
    },
  },
  extensions: [myExtension],
});

<main id="content">
  <ion-button>Keep this on the Web</ion-button>
  <ion-button data-native-ui="button" data-native-ui-placement="rail">Project this action</ion-button>
  <button data-native-ui="button">Project at its original position</button>
</main>
<aside id="rail" aria-label="Actions"></aside>

Behalten Sie die ursprünglichen Handler an jeder Quelle. Explizites ion-button verwendet den Standard-Schaltflächenreader; unterstützte Inhalte und Stilregeln gelten daher weiterhin. Das Attribut macht beliebiges eigenes Markup nicht unterstützt. data-native-ui-placement="rail" fordert die Systemleiste an, sofern verfügbar. Gestalten Sie den optionalen webHost und reservieren Sie Platz in Ihrer App; ohne ihn bleiben die Quellelemente nicht verfügbarer expliziter Seitenleisten sichtbar. Unmarkierte Ionic-Bedienelemente werden weiterhin im Web dargestellt. Eine automatisch projizierte Gruppe mit einer explizit markierten Quelle bleibt im Web, um diese Quelle nicht doppelt zu überdecken.

Explizite integrierte Quellen unterstützen einzelne button-, ion-button- und [role="button"]-Elemente mit data-native-ui="button" oder "back-button". Dies aktiviert nicht die Ionic-spezifischen Reader für bestehende ion-back-button, ion-menu-button, Schaltflächengruppen, Tabs, Segmente oder FABs. Lassen Sie automatische Projektion für den jeweiligen Typ aktiviert, verwenden Sie eine explizite Standardschaltfläche mit eigenem Klickhandler oder registrieren Sie eine Erweiterung für eigene Oberflächen.

verticalBars.enabled steuert weiterhin die Seitenleistenverfügbarkeit. Entfernen Sie die explizite Markierung einer Quelle oder verwenden Sie data-native-ui="disabled", um sie im Web zu belassen.

Seitenleistennutzung nach dem Start ändern

await shell.disableVerticalControlArea();
await shell.enableVerticalControlArea();

Diese Methoden ändern verticalBars.enabled dieser Shell und erhalten Darstellung, Bedienelemente und Position. Vor dem Zuständigkeitswechsel lösen sie bestehende Projektionen auf, ohne eine weitere Shell zu erzeugen. Aufrufe werden serialisiert. Nach destroy() werden beide Methoden abgewiesen.

const lease = await shell.suspend(); // vorübergehend alle Web-Bedienelemente wiederherstellen
await lease.resume();
await shell.destroy(); // Shell stoppen und Quellen wiederherstellen

Das Deaktivieren der Seitenleistenprojektion entfernt kein Anwendungs-CSS und ändert keine anwendungseigenen Abstände. Aktualisieren Sie bei Bedarf zugleich Ihr eigenes Layout.

Nach einer unbeobachteten Änderung eine Prüfung anfordern

shell.markForCheck();

Verwenden Sie dies nach der Änderung einer Eigenschaft oder eines Reader-Zustands ohne DOM-Mutation. Es plant eine Prüfung, bündelt wiederholte Anforderungen und sendet nur geänderte native Snapshots. Der Rückgabewert ist void; es wartet weder auf nativen Abschluss noch rendert es das Framework-DOM. Aufrufe nach der Zerstörung werden ignoriert. Siehe Quellprüfungen und Beobachtung.

Verstehen, warum eine Quelle im Web bleibt

Ergänzen Sie Ihre bestehenden Startoptionen vorübergehend um debug: true und erstellen Sie die Web-App erneut. Starten Sie für Diagnosen keine zweite Shell:

const shell = await enableNativeUI({ debug: true, extensions: [myExtension] });
console.info(shell.getStatus());

Öffnen Sie die WebView-Entwicklerkonsole und filtern Sie nach [Native UI]. Diagnosen enthalten nach Möglichkeit die DOM-Quelle. Jeder Grund wird während dieser Aktivierung einmal je Quelle protokolliert, damit Scrollen oder wiederholtes markForCheck() die Konsole nicht überfüllen. Props, Aktions-Payloads und Ausnahmemeldungen der Anwendung werden nicht protokolliert.

getStatus() fasst die Shell zusammen; es ist kein Diagnosebericht pro Element. Normale Navigation, Aussetzung und nicht unterstützte Inhalte können bewusst die Web-Darstellung beibehalten. Deaktivieren Sie Debug nach der Untersuchung; es ändert die Projektionseignung nicht.

Bestehende Anwendungen

Das eigenständige enableVerticalControlArea() wählt standardmäßig 'verticalOnly'. Sein Helfer setPlacement() ist ein veralteter Web-CSS-Adapter; verwenden Sie für das Web-Layout setVerticalBarsLayout({ edge, inset }) aus dem Theme. Native Verfügbarkeit stammt aus den Gerätemetriken des Plugins.

Die Migration von 1.2.1 beschreibt Paketaufteilung, entfernte Optionen und geänderte Standardwerte bei partieller Bedienelementkonfiguration.