# Download Komponente des SBB Design Systems Lyne. - Paket: `@sbb-esta/lyne-elements` (Angular: `@sbb-esta/lyne-angular`) - Aufbau: Hauptelement mit Bestandteilen; Bestandteile nur innerhalb des jeweiligen Elements verwenden - Kategorien: Action - Status: Gestaltungsrichtlinien vollständig ## Links - Seite auf digital.sbb.ch: https://digital.sbb.ch/de/design-system/lyne/components/download/ - Storybook: https://lyne-elements.app.sbb.ch/?path=/docs/elements-download--docs - Angular (`@sbb-esta/lyne-angular`): https://lyne-angular.app.sbb.ch/angular/components/download/overview (API: https://lyne-angular.app.sbb.ch/angular/components/download/api) - GitHub: https://github.com/sbb-design-systems/lyne-components ## Elemente - `sbb-download`: It displays a downloadable document, styled as a card. - `sbb-download-info`, nur innerhalb von `sbb-download`: It displays metadata of a document; used within a `sbb-download`. ## Übersicht ### Was macht die Komponente? Ein Download zeigt ein Dokument zum Herunterladen an, z.B. ein PDF. Die ganze Fläche ist ein Link. Titel, Dateityp, Grösse und Änderungsdatum helfen Nutzenden einzuschätzen, was sie erhalten. ### Wann soll die Komponente eingesetzt werden? * Um Dokumente wie Berichte, Formulare oder Merkblätter zum Herunterladen anzubieten. * Um mehrere Dokumente einheitlich aufzulisten. ### Regeln. * Der Titel beschreibt den Inhalt des Dokuments, nicht den Dateinamen. * Dateityp und Grösse sollen immer angegeben werden, das Änderungsdatum, wenn es für Nutzende relevant ist. * Dokumente, die nicht barrierefrei sind, müssen als solche gekennzeichnet werden. * Für Links auf Webseiten soll ein Link oder eine Card verwendet werden, nicht ein Download. ## Implementation (Web Components, Englisch) The `` is a component that displays a downloadable document, styled as a [sbb-card](https://lyne-elements.app.sbb.ch/?path=/docs/elements-card--docs). The whole area is rendered as a link. ```html ``` The `label` shown as the title defaults to the file name extracted from the `href`, but can be set explicitly. ```html ``` ### Download vs. inline Whether the referenced document is downloaded or shown inline in the browser is up to the consumer: - With the `download` attribute, activating the component triggers the browser download. - Without it, the document is opened inline. In this case the link opens in a new browser tab (`target="_blank"`) by default and an "opens in new window" hint is provided to assistive technology. An explicitly set `target` takes precedence; an empty `target` attribute opts out of the new tab behavior without specifying a target. ```html ``` It's possible to set the other link related properties `rel` and `target` as well. ### Icon An icon is automatically derived from the `href` file extension. The following extensions are mapped to a dedicated document icon; any other (or missing) extension falls back to the generic `document-standard-small` icon. | File extension | Icon | | ------------------------------------------------ | ------------------------- | | `.pdf` | `document-pdf-small` | | `.xls`, `.xlsx` | `document-xls-small` | | `.ppt`, `.pptx` | `document-ppt-small` | | `.doc`, `.docx` | `document-doc-small` | | `.zip` | `document-zip-small` | | `.jpg`, `.jpeg`, `.png`, `.gif`, `.svg`, `.webp` | `document-image-small` | | _anything else / no extension_ | `document-standard-small` | A custom icon can be set with the `iconName` property or via the `icon` slot, which overrides the automatic derivation. ```html ``` ### Content The content of the unnamed slot and the `` block are both optional and independent. You can render custom content, a ``, both, or none of them. A `` placed in the unnamed slot is automatically moved to the dedicated `info` slot, so it always renders in the correct position. The `` assigns itself to the `info` slot in its `connectedCallback`, which only runs on the client; during server-side rendering the element stays in the unnamed slot until it is hydrated. ```html Custom description for the downloadable document. ``` ### Document metadata Use the optional `` component to display the document's metadata. The information is rendered in the order `type`, `size`, non-accessible, `changed`, skipping any value that has not been provided. - `type` falls back to the file extension of the parent `sbb-download`. - `size`, if it contains only digits, is interpreted as a number of bytes and shortened to the closest unit (e.g. `1234567` becomes `1 MB`); otherwise it is displayed as is. - `changed` accepts an ISO 8601 date string and is rendered as a formatted date. - `nonAccessible` renders a localized "not accessible" hint. ```html ``` ## API (Web Components, Englisch) #### class: `SbbDownloadElement`, `sbb-download` ##### Properties | Name | Attribute | Privacy | Type | Default | Description | | ---------------------- | ----------------------- | ------- | ------------------------------------------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------- | | `accessibilityCurrent` | `accessibility-current` | public | `string` | `''` | This will be forwarded as aria-current to the inner anchor element. | | `accessibilityLabel` | `accessibility-label` | public | `string` | `''` | This will be forwarded as aria-label to the inner anchor element. | | `color` | `color` | public | `'white' \| 'milk'` | `'white'` | Option to set the component's background color. | | `download` | `download` | public | `boolean` | `false` | Whether the browser will show the download dialog on click. | | `fileExtension` | - | public | `string` | | The lower-cased file extension extracted from the `href` (e.g. `pdf`), if any. | | `fileName` | - | public | `string` | | The file name extracted from the `href` (e.g. `report.pdf`). | | `href` | `href` | public | `string` | `''` | The href value you want to link to. | | `iconName` | `icon-name` | public | `string` | `''` | The icon name we want to use, choose from the small icon variants from the ui-icons category from here https://icons.app.sbb.ch. | | `label` | `label` | public | `string` | `''` | The label of the download. Defaults to the file name of the `href`. | | `rel` | `rel` | public | `string` | `''` | The relationship of the linked URL as space-separated link types. | | `target` | `target` | public | `'_blank' \| '_self' \| '_parent' \| '_top' \| string` | `''` | Where to display the linked URL. | ##### Slots | Name | Description | | ------ | ------------------------------------------------------------------------------------------------------------------------------------------ | | | Use the unnamed slot to add custom content. Optional. | | `icon` | Use this slot to display a custom icon, by providing a `sbb-icon` component. Optional. | | `info` | Slot used to render a `sbb-download-info`. A `sbb-download-info` placed in the unnamed slot is automatically moved to this slot. Optional. | #### class: `SbbDownloadInfoElement`, `sbb-download-info` ##### Properties | Name | Attribute | Privacy | Type | Default | Description | | --------------- | ---------------- | ------- | --------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `changed` | `changed` | public | `string` | `''` | The date of the latest change of the document, as an ISO 8601 string. | | `nonAccessible` | `non-accessible` | public | `boolean` | `false` | Whether the document is not accessible. | | `size` | `size` | public | `string` | `''` | The size of the document. If the value contains non-numeric characters it is rendered as is, otherwise it is interpreted as a number of bytes and shortened to the closest unit. | | `type` | `type` | public | `string` | `''` | The type of the document (e.g. `PDF`). Falls back to the extension of the parent `sbb-download`. |