Gestalte gut lesbare Formulare für finnische öffentliche Dienste mit Source Sans 3, ausdrücklich festgelegten Abstands-Design-Token und einem Muster für die wiederherstellbare Dokumentauswahl.
Teste eine PDF-Datei, lehne ein nicht unterstütztes Format ab und entferne das ausgewählte Dokument. Die Dateien bleiben in deinem Browser.
Offizielle Dokumentation, geprüftes Token-Repository und Metadaten von suomifi-ui-components 18.0.0. Die Vorschau ist eine eigenständige Interpretation, keine native Laufzeitumgebung von React.
| Name / Regel | Wert / Konfiguration | Verwendung |
|---|---|---|
Family | Source Sans 3 | Version 18; bis einschließlich Version 17 wurde Source Sans Pro verwendet. Schriftarten separat laden. |
Body text | 18px | Auf Mobilgeräten und Desktop dieselbe Standardeinstellung. |
Small body | 16px | Textdarstellung smallScreen, keine automatische Viewport-Regel. |
Lead | 22px / 20px smallScreen | Pro Ansicht eine Einleitung; lead nicht für jeden Absatz verwenden. |
Weights | 300 / 400 / 600 | Von dem Komponentenpaket benötigte Schriftdateien. |
| Name / Regel | Wert / Konfiguration | Verwendung |
|---|---|---|
Space scale | 5, 10, 15, 20, 25, 30, 40, 60, 80px | xxs bis xxxxl in der JSON-Datei des geprüften Repositorys. |
Inset scale | 2, 4, 6, 8, 10, 16, 20px | insetXxs bis insetXxl; nicht die äußere Abstands-Skala. |
Basic radius | 2px | Repository-Wert radius.basic; keinen großen Kartenradius daraus ableiten. |
Highlight base | hsl(212, 63%, 45%) | Standard-Blau für Interaktionen. |
Highlight dark 1 | hsl(212, 63%, 37%) | Dunklere Interaktionsrolle. |
Highlight light 2 | hsl(212, 63%, 90%) | Rolle für helle Oberflächen; Kontrast mit der gewählten Textfarbe prüfen. |
| Name / Regel | Wert / Konfiguration | Verwendung |
|---|---|---|
Default maximum width | 600px | Komponentenspezifische Breite, kein Raster für die gesamte Website. |
fullWidth | Boolean layout option | Auf die Breite des übergeordneten Elements ausdehnen, wenn das Formular es erfordert. |
smallScreen | Explicit compact presentation option | Aus dieser Prop keine globale automatische Breakpoint-Regel ableiten. |
Single selection | Chosen file replaces picker and drop area | Die Mehrfachauswahl ist ein eigenes Muster, bei dem die Dateien darunter aufgeführt werden. |
Required copy roles | labelText, hintText, dragAreaText, removeFileText, addedFileAriaText | Jede Rolle lokalisieren; der Dateiname allein ist keine vollständige barrierefreie Ansage. |
Ein praktischer Leitfaden zur Auswahl, Anwendung und Überprüfung dieses Systems für ein echtes Interface.
Umfassende Anleitung, Einstieg in die Implementierung und Links zu den Quellen.
Suomi.fi stellt React-Komponenten bereit, die mit styled-components gestaltet werden, sowie ein separates Token-Paket. Ab Version 18 wird Source Sans 3 als Schriftart erwartet. Seiten mit Version 17 können weiterhin Source Sans Pro verwenden. Werden solche Screenshots verglichen, ohne die Paketversion zu prüfen, kann das zu einer vermeintlichen Korrektur der Typografie führen.
Die eingebettete Vorschau bleibt ausdrücklich als Interpretation des dokumentierten Einzeldateimusters in HTML/CSS gekennzeichnet. Weiter unten ist nun zusätzlich ein eigenständiges Beispiel mit dem nativen React FileInput enthalten, einschließlich des überprüften Callbacks, des kontrollierten Werts, der Abhängigkeiten und der Schriftartimporte. Beide Implementierungen dienen derselben lokalen Auswahlaufgabe. Das native Beispiel macht die eingebettete HTML-Vorschau nicht nachträglich zur React-Komponente.
Verwende auf Mobilgeräten und Desktop die dokumentierte Fließtextgröße von 18px. Ein schmaler Viewport ist kein Grund, alle Formularerläuterungen zu verkleinern. Die kleine Textdarstellung ist 16px groß und für Zusatzinformationen vorgesehen. Der Lead-Text ist 22px groß und wird mit der kompakten Darstellung auf 20px reduziert. Verwende ihn nur für die Seiteneinleitung.
Lade die vorgesehenen Schriftstärken, bevor du den Zeilenumbruch vergleichst. Das Komponentenpaket erwartet Schriftdateien für Source Sans 3; diese eigenständige Vorschau verwendet bewusst Arial. Dieser Austausch ist im Vorschauhinweis kenntlich gemacht und darf nicht als exakte Darstellung der nativen Komponente ausgegeben werden.
Die Tokenquelle trennt gewöhnliche Abstände von Innenabständen. Das gewöhnliche l beträgt im untersuchten JSON 25px. Übernehmen Sie kein älteres README-Beispiel, in dem l mit 32px angegeben ist. Innenabstände beginnen bei 2px und folgen einer anderen Abstufung. Verwenden Sie zum Erzeugen von Stilen die tatsächlichen Exporte der installierten Version.
FileInput hat eine dokumentierte maximale Breite von 600px und eine fullWidth-Option. Das ist eine Einschränkung der Komponente und kein Beleg für einen universellen Seitencontainer mit 600px Breite. In einem Formular zur Dokumentenannahme kann das Feld in einem breiteren Layout stehen, während der erläuternde Text nahe an der Beschriftung bleibt.
Die sichtbare Beschriftung benennt das angeforderte Dokument. Der Hinweis erläutert unterstützte Formate, Dateigröße und Anzahl, bevor jemand den Dateiauswahldialog öffnet. Der Ablagebereich bietet eine zusätzliche Möglichkeit per Zeiger, darf das Dateieingabefeld aber nicht ersetzen. Laut offizieller Anleitung ist das Auswahlsteuerelement die Beschriftung eines verborgenen nativen Dateieingabefelds.
Im Einzeldateimodus ersetzen das ausgewählte Dokument den Dateiauswahldialog und den Ablagebereich. Bieten Sie neben dem Dokument eine klar erkennbare Entfernen-Aktion an. Im Mehrdateimodus wird eine andere Listenanordnung verwendet. Hängen Sie nicht stillschweigend weitere Dateien an eine Anfrage für eine einzelne Datei an.
Das Beispiel akzeptiert eine PDF-Datei mit höchstens 5.000.000 Byte. Diese Regeln wurden für das Szenario dieses Workshops festgelegt. Sie sind weder Paketstandardwerte noch eine offizielle Upload-Richtlinie von Suomi.fi. Die accept-Filterung des Browsers ist nur ein Hinweis für den Dateiauswahldialog; das Beispiel prüft Dateiname und Größe nach der Auswahl oder dem Ablegen zusätzlich selbst.
Bei ungültigen Metadaten bleibt das Auswahlfeld verfügbar und erklärt, wie der Vorgang wiederholt werden kann. Bei einer gültigen Auswahl wird der Dateiname mit textContent angezeigt, die Byteanzahl angegeben und der Fokus auf das Steuerelement zum Entfernen gesetzt. Beim Entfernen wird der Wert des zugrunde liegenden Eingabefelds gelöscht, die Auswahlmöglichkeit wiederhergestellt und der Fokus zurückgesetzt, sodass dieselbe Datei erneut ausgewählt werden kann.
Die veröffentlichte FileInput-Implementierung in Version 18.0.0 ruft onChange mit einer FileList auf, nicht mit einem React change-Ereignis. Der kontrollierte Wert ist ein Array aus Dateiobjekten; im Beispiel wird jede akzeptierte File auf { file } abgebildet. Derselbe Callback wird aufgerufen, wenn die integrierte Entfernen-Aktion die Liste ändert. Eine leere FileList leert daher das kontrollierte Array. Diese Verträge wurden im veröffentlichten Modul dist/esm/core/Form/FileInput/FileInput.js überprüft.
Halten Sie value vom ersten Rendern an kontrolliert, indem Sie mit einem leeren Array beginnen. Prüfen Sie die eingehende FileList, bevor Sie sie auf dieses Array abbilden. Dieses Beispiel weist Dateien zurück, deren Namen nicht auf .pdf enden oder deren Größe 5.000.000 Byte überschreitet, und hebt die Auswahl bei einer Zurückweisung auf. Das sind lokale Regeln des Beispiels, keine Sicherheitsprüfung und keine Richtlinie von Suomi.fi. Vor der Annahme eines tatsächlichen Uploads ist weiterhin eine serverseitige Inhaltsprüfung erforderlich.
Das native Beispiel unten lädt Source Sans 3 in den Schriftstärken 400 und 600, bindet React in ein explizites Root-Element ein und verwendet styled-components über die Bibliothek. Binden Sie tslib ausdrücklich ein: Die ESM-Module der Version 18.0.0 importieren dessen Hilfsfunktionen, und ein sauberer Build ohne diese Abhängigkeit schlug fehl. Die unten festgelegte Konfiguration enthält die fehlende Laufzeitabhängigkeit und die Schriftdateien. Für dieses Beispiel mit dem Standarddesign ist kein zusätzlicher Theme-Provider erforderlich.
Unterstützende Spezifikation lesen
Die offizielle Stilanleitung zeigt suomifiDesignTokens.spacing und suomifiDesignTokens.colors. Das folgende Beispiel verwendet diese exportierten Pfade für einen benutzerdefinierten Wrapper. Es ersetzt nicht die interne Implementierung von FileInput.
import { suomifiDesignTokens } from 'suomifi-design-tokens';
// Real exported token paths. Use values instead of copying README example numbers.
const attachmentStyle = {
maxWidth: 600,
padding: suomifiDesignTokens.spacing.m,
borderColor: suomifiDesignTokens.colors.highlightBase
};Sorgen Sie dafür, dass ein natives Dateieingabefeld auch dann per Tastatur bedienbar bleibt, wenn der Ablagebereich stark hervorgehoben ist. Verknüpfen Sie Hinweis und Fehlermeldung über aria-describedby mit dem Feld. Geben Sie Änderungen an der Auswahl und das Entfernen bekannt, ohne die gesamte Seite erneut vorlesen zu lassen. Wenn in einem Formular mehrere solcher Steuerelemente vorkommen können, sollte ein Entfernen-Button die ausgewählte Datei benennen.
Die offizielle smallScreen-Prop ermöglicht eine kompakte Darstellung. Sie legt keinen globalen Breakpoint fest. Diese unabhängige Vorschau passt den Innenabstand bei 480px gemäß einer anwendungsspezifischen Einstellung an und behält eine Textgröße von 18px bei. Testen Sie lange Dateinamen, Vergrößerung und übersetzte Beschriftungen. Lassen Sie Dateinamen umbrechen, ohne dadurch die gesamte Seite zu verbreitern.
Die Demo liest den Inhalt des Dokuments nicht aus und sendet keine Anfrage. Ein ausgewählter Dateiname und eine Byteanzahl beweisen nicht, dass ein Dokument gültig, gespeichert oder angenommen wurde. Echte Dienste benötigen eine serverseitige Validierung, Upload-Fortschritt, die Möglichkeit zur Wiederaufnahme nach Fehlern, Aufbewahrungsregeln und eine Bestätigung, die auf einer tatsächlichen Antwort beruht.
Der Komponentencode steht unter der MIT-Lizenz. Diese Lizenz berechtigt ein unabhängiges Projekt nicht dazu, sich als finnischer Behördendienst auszugeben oder eine geschützte institutionelle Identität zu verwenden. Nutzen Sie für Experimente einen neutralen Projektnamen und holen Sie für eine offizielle Implementierung die entsprechenden Markenrichtlinien ein.
Verifizierte Exportpfade für Abstände und Farben in einem benutzerdefinierten Wrapper.
import { suomifiDesignTokens } from 'suomifi-design-tokens';
// Real exported token paths. Use values instead of copying README example numbers.
const attachmentStyle = {
maxWidth: 600,
padding: suomifiDesignTokens.spacing.m,
borderColor: suomifiDesignTokens.colors.highlightBase
};Vollständige lokale Umsetzung. PDF- und Größenbeschränkungen sind Szenarioentscheidungen; es findet kein Upload statt.
<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Attachment example</title><style>*{box-sizing:border-box}body{margin:0;padding:30px 20px;font:18px/1.5 Arial,sans-serif;color:#202020;background:#fff}main{max-width:600px;margin:auto}h1{font-size:32px;line-height:1.2;font-weight:400;margin:0 0 20px}p{margin:0 0 20px}label{font-weight:600;display:block}small{display:block;font-size:16px}.drop{margin-top:15px;border:2px dashed hsl(212,63%,45%);padding:30px;text-align:center;background:hsl(212,63%,90%)}button,input::file-selector-button{font:600 18px Arial;padding:12px 20px;border:1px solid hsl(212,63%,37%);border-radius:2px;background:hsl(212,63%,45%);color:white;cursor:pointer}button:focus-visible,input:focus-visible{outline:3px solid #202020;outline-offset:3px}input{width:100%;font-size:16px;margin:15px 0}input::file-selector-button{margin-right:10px}.file{border:1px solid #777;padding:20px;margin:20px 0;overflow-wrap:anywhere}.file button{margin-top:15px;background:white;color:hsl(212,63%,37%)}#error{color:#a32020;font-weight:bold}footer{font-size:14px;margin-top:30px;border-top:1px solid #ccc;padding-top:15px}[hidden]{display:none!important}@media(max-width:480px){body{padding:20px 15px}.drop{padding:20px}h1{font-size:28px}}</style><main><small>COMMUNITY WORKSHOP · ATTACHMENT</small><h1>Add your project outline</h1><p>Choose one PDF up to 5 MB. This local example checks file metadata; it does not read or send the document.</p><div id="picker"><label for="file">Project outline</label><small id="hint">One PDF file. Maximum 5 MB (5,000,000 bytes).</small><input id="file" type="file" accept=".pdf,application/pdf" aria-describedby="hint error"><div class="drop" id="drop">Or drop one PDF here</div></div><p id="error" role="alert" hidden></p><section id="selected" class="file" hidden aria-label="Selected attachment"><strong id="name"></strong><small id="size"></small><button id="remove" type="button">Remove file</button></section><p id="status" role="status">No file selected.</p><footer>OpenDesign interpretation of the Suomi.fi attachment pattern. Arial fallback; no official identity or React component runtime. PDF and 5 MB are example rules.</footer></main><script>const input=document.querySelector('#file'),picker=document.querySelector('#picker'),selected=document.querySelector('#selected'),error=document.querySelector('#error'),status=document.querySelector('#status');function choose(files){error.hidden=true;if(files.length!==1){error.textContent='Choose exactly one file.';error.hidden=false;input.value='';return}const file=files[0];if(!/\.pdf$/i.test(file.name)||file.size>5000000){error.textContent='Choose a PDF no larger than 5 MB.';error.hidden=false;input.setAttribute('aria-invalid','true');input.value='';return}input.removeAttribute('aria-invalid');document.querySelector('#name').textContent=file.name;document.querySelector('#size').textContent=file.size.toLocaleString('en')+' bytes · selected locally';document.querySelector('#remove').setAttribute('aria-label','Remove '+file.name);picker.hidden=true;selected.hidden=false;status.textContent='Selected file: '+file.name;document.querySelector('#remove').focus()}input.addEventListener('change',()=>{if(input.files.length)choose(input.files)});document.querySelector('#drop').addEventListener('dragover',e=>e.preventDefault());document.querySelector('#drop').addEventListener('drop',e=>{e.preventDefault();choose(e.dataTransfer.files)});document.querySelector('#remove').onclick=()=>{input.value='';picker.hidden=false;selected.hidden=true;error.hidden=true;input.removeAttribute('aria-invalid');status.textContent='File removed. Choose another file.';input.focus()};</script></html>Als main.jsx speichern. Mit diesen drei Dateien lässt sich das native Beispiel für React mithilfe der Setup-Befehle reproduzieren.
import React, { useState } from 'react';
import { createRoot } from 'react-dom/client';
import { FileInput } from 'suomifi-ui-components';
import '@fontsource/source-sans-3/400.css';
import '@fontsource/source-sans-3/600.css';
import './app.css';
function App() {
const [value, setValue] = useState([]);
const [error, setError] = useState('');
function change(files) {
const next = Array.from(files);
const invalid = next.length > 1 || next.some(file => !/\.pdf$/i.test(file.name) || file.size > 5000000);
if (invalid) {
setValue([]);
setError('Choose one PDF no larger than 5 MB.');
return;
}
setValue(next.map(file => ({ file })));
setError('');
}
return <main><h1>Select a workshop document</h1><p>This local example does not upload or read the document.</p>
<FileInput id="document" labelText="Workshop document" hintText="One PDF, maximum 5 MB (5,000,000 bytes)."
inputButtonText="Choose PDF" dragAreaText="or drop a PDF here" removeFileText="Remove file"
addedFileAriaText="Selected file" accept=".pdf" value={value} onChange={change}
status={error ? 'error' : 'default'} statusText={error} />
<p role="status">{value.length ? `${value[0].file.name} selected locally.` : 'No file selected.'}</p>
</main>;
}
createRoot(document.getElementById('root')).render(<App />);
Als app.css speichern. Zusammen bilden diese drei Dateien das native React-Beispiel mit den Einrichtungsbefehlen nach.
body{margin:0;font:18px/1.5 'Source Sans 3',sans-serif;color:#292929;background:#fff}main{max-width:600px;margin:0 auto;padding:24px}h1{font-size:32px;line-height:1.2}*{box-sizing:border-box}
Als index.html speichern. Zusammen bilden diese drei Dateien das native React-Beispiel mit den Einrichtungsbefehlen nach.
<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Native Suomi.fi FileInput</title><link rel="stylesheet" href="./app.css"><div id="root"></div><script type="module" src="./app.js"></script></html>
Damit wird das native React-Beispiel unten erstellt, einschließlich lokaler Source-Sans-3-Schriftdateien. Getestet mit ungültigem Format, gültiger Auswahl, integrierter Entfernung und einer zu großen PDF-Datei bei 390px und 1440px. Die vorhandene herunterladbare Vorschau-ZIP ist eine separate Interpretation von HTML/CSS; die README-Datei ist weiterhin korrekt.
npm install --save-exact [email protected] [email protected] [email protected] [email protected] [email protected] @fontsource/[email protected] npm install --save-dev --save-exact [email protected] # Save main.jsx, app.css and index.html from the complete examples below. npx esbuild main.jsx --bundle --outdir=dist --entry-names=app --loader:.woff=copy --loader:.woff2=copy cp index.html dist/index.html python3 -m http.server 8080 --directory dist # Open http://localhost:8080
Verwende das bereitgestellte native Suomi.fi FileInput-18.0.0-React-Beispiel mit Source Sans 3 und den festgelegten Laufzeitabhängigkeiten, einschließlich tslib. Steuere den Wert als Array von { file }-Objekten und erhalte in onChange direkt eine FileList; lies in diesem Callback nicht event.target aus. Prüfe Format und Größe, bevor du eine lokale Auswahl akzeptierst, behandle die beim Entfernen ausgegebene leere Liste und lasse Hinweis- und Fehlermeldungen sichtbar. Betrachte die eingebettete HTML-Vorschau als separat gekennzeichnete Interpretation. Keine der beiden Implementierungen lädt eine Datei hoch; Servervalidierung, Fortschrittsanzeige und bestätigte Speicherung erfordern einen tatsächlichen Backend-Vertrag.Die eingebettete Vorschau und die herunterladbare ZIP-Datei sind eine OpenDesign-HTML/CSS-Interpretation. Das separate vollständige React-Beispiel verwendet suomifi-ui-components 18.0.0 und die verifizierten Verträge für FileInput-Wert und onChange. Beide Beispiele unterstützen die lokale Dateiauswahl; keines lädt ein Dokument auf einen Server hoch oder speichert es dort.
