> For the complete documentation index, see [llms.txt](https://docs.eximee.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.eximee.com/budowanie-aplikacji/interfejs-uzytkownika/formularze/biblioteka-komponentow-bazowych/5-dokumenty-i-zaloczniki/zalaczniki-uploadfile.md).

# Załączniki - UploadFile

Komponent załączania plików do wniosku

![](https://content.gitbook.com/content/2CssJT0zIo4SJQLbSZ6l/blobs/lGDkyNrwKf6pOElPJKmk/3k_files/image2025-5-16_8-55-39.png)

## Właściwości komponentu

<table><thead><tr><th>Właściwość Eximee Designer</th><th width="200.9832763671875">Nazwa atrybutu w Źródle</th><th>Opis</th></tr></thead><tbody><tr><td><strong>Maksymalna liczba załączonych plików</strong> (sekcja <strong>Podstawowe właściwości</strong>)</td><td>numberOfUploadingFiles</td><td>Liczba plików, jaką można załadować w komponencie, domyślnie 1.</td></tr><tr><td><strong>Liczba wymaganych załączników</strong> (sekcja <strong>Jakość danych</strong>)</td><td>requiredCount</td><td>Wymagana liczba plików do załączenia - domyślnie 0. Jeśli 0, to można nie załączyć żadnego pliku, jeśli więcej to zależnie od danej liczby.</td></tr><tr><td><strong>Tekst wyświetlany na brak wymaganych załączników</strong> (sekcja <strong>Jakość danych</strong>)</td><td>requiredCountError</td><td>Komunikat wymagalności, wymagany jeśli zdefiniowana jest właściwość <strong>Liczba wymaganych załączników</strong> (requiredCount).</td></tr><tr><td><strong>Maksymalny rozmiar pliku</strong> (sekcja <strong>Jakość danych</strong>)</td><td>maxFileSize</td><td>Maksymalny rozmiar pliku w KB. Domyślnie 1024 KB.</td></tr><tr><td><strong>Maksymalny sumaryczny rozmiar wszystkich plików</strong> (sekcja <strong>Jakość danych</strong>)</td><td>maxTotalFilesSize</td><td>Maksymalny rozmiar wszystkich załączonych plików w KB. Domyślnie 10240 KB.</td></tr><tr><td><strong>Pokaż listę dostępnych rozszerzeń</strong> (sekcja <strong>Interakcje</strong>)</td><td>showExtensionList</td><td>Włączenie opcji wyświetlania informacji o dopuszczalnych formatach oraz maksymalnym rozmiarze załączanego pliku (domyślnie opcja jest wyłączona). Przykładowa informacja: "Dopuszczalne formaty załączników: pdf (max. 1 MB)"</td></tr><tr><td><strong>Włączenie kompresji obrazów</strong> (sekcja <strong>Interakcje</strong>)</td><td>imageCompressionEnabled</td><td>Możliwość kompresji obrazów (domyślna wartość "false").</td></tr><tr><td><strong>Maksymalna szerokość zdjęcia z kamery</strong> (sekcja <strong>Interakcje</strong>)</td><td>maxWebcamWidth</td><td>Dostępność funkcjonalności zależy od licencji i może nie być dostępna we wszystkich wdrożeniach. Maksymalna szerokość zdjęcia z kamery w pikselach.</td></tr><tr><td><strong>Maksymalna wysokość zdjęcia z kamery</strong> (sekcja <strong>Interakcje</strong>)</td><td>maxWebcamHeight</td><td>Dostępność funkcjonalności zależy od licencji i może nie być dostępna we wszystkich wdrożeniach. Maksymalna wysokość zdjęcia z kamery w pikselach.</td></tr><tr><td><strong>Możliwość dołączenia zdjęcia wykonanego kamerą</strong> (sekcja <strong>Interakcje</strong>)</td><td>webcamEnabledCondition</td><td>Dostępność funkcjonalności zależy od licencji i może nie być dostępna we wszystkich wdrożeniach. Warunek włączający/wyłączający możliwość uploadu zdjęcia wykonanego kamerą wbudowaną w urządzenie.</td></tr><tr><td><strong>Lista dozwolonych rozszerzeń plików</strong> (sekcja <strong>Bezpieczeństwo</strong>)</td><td>validExtensionList</td><td>Formaty dopuszczalnych rozszerzeń plików, wymieniane po przecinku, np.: jpg, jpeg, png, pdf.</td></tr><tr><td><strong>Dodatkowa walidacja plików PDF</strong> (sekcja <strong>Bezpieczeństwo</strong>)</td><td>validateContent</td><td>Dodatkowa walidacja pliku pod kątem FORMATU pdf, a nie samego rozszerzenia.</td></tr><tr><td><strong>Odrzucanie zaszyfrowanych plików PDF, DOC, DOCX, XLS, XLSX</strong> (sekcja <strong>Bezpieczeństwo</strong>)</td><td>rejectEncrypted</td><td>Odrzucanie plików (PDF, DOC, DOCX, XLS, XLSX), jeśli są zaszyfrowane hasłem.</td></tr><tr><td><strong>Wyrażenie regularne do walidacji nazwy pliku</strong> (sekcja <strong>Bezpieczeństwo</strong>)</td><td>allowedFilenameRegexp</td><td>Wyrażenie regularne sprawdzające dopuszczalne nazwy pliku. Możliwe jest nadpisanie domyślnego komunikatu błędu walidacyjnego poprzez dopisanie do tłumaczeń wnioskowych klucza <strong>iew.gwtupload.invalid_filename</strong> i ustalenie nowej wartości tłumaczenia.</td></tr><tr><td><strong>Biała lista znaków</strong> (sekcja <strong>Bezpieczeństwo</strong>)</td><td>extraWhitelistCharacters</td><td>Aby umożliwić przesyłanie plików zawierających niestandardowe znaki, dodaj je do białej listy dozwolonych znaków. np.: (). Ta konfiguracja rozszerza konfigurację webforms.xml ...</td></tr><tr><td><strong>Możliwość dołączania opisów do załączonych plików</strong> (sekcja <strong>Pozostałe</strong>)</td><td>attachmentWithDescription</td><td>Dostępność funkcjonalności zależy od licencji i może nie być dostępna we wszystkich wdrożeniach. Wyświetlanie pola opisu dla każdego dodanego załącznika. Domyślnie właściwość wyłączona (ustawione na "false").</td></tr><tr><td><strong>Maksymalna liczba znaków opisów do załączonych plików</strong> (sekcja <strong>Pozostałe</strong>)</td><td>attachmentDescriptionMaxLength</td><td>Dostępność funkcjonalności zależy od licencji i może nie być dostępna we wszystkich wdrożeniach. Maksymalna długość opisu, jaki można wprowadzić dla dodawanego załącznika. Domyślnie 120 znaków.</td></tr><tr><td><strong>Etykieta przycisku</strong> (sekcja <strong>Pozostałe</strong>)</td><td>buttonLabel</td><td>Dostępność funkcjonalności zależy od licencji i może nie być dostępna we wszystkich wdrożeniach. Tekst wyświetlany na przycisku dodawania pliku.</td></tr><tr><td><strong>Opis pola</strong> (sekcja <strong>Pozostałe</strong>)</td><td>description</td><td>Dostępność funkcjonalności zależy od licencji i może nie być dostępna we wszystkich wdrożeniach. Tekst opisu.</td></tr><tr><td><strong>Włączenie kompresji obrazów</strong> (sekcja <strong>Pozostałe</strong>)</td><td></td><td>Dostępność funkcjonalności zależy od licencji i może nie być dostępna we wszystkich wdrożeniach. Właściwość pozwalająca na zmniejszanie załączanych obrazów.</td></tr><tr><td><strong>Typ dokumentu - zaawansowana integracja</strong> (sekcja <strong>Pozostałe</strong>)</td><td>documentType</td><td>Pole techniczne używane przy zaawansowanej integracji (wymaga dodatkowej implementacji). Dostępność funkcjonalności zależy od licencji i może nie być dostępna we wszystkich wdrożeniach.</td></tr><tr><td><strong>Numer kontaktowy - zaawansowana integracja</strong> (sekcja <strong>Pozostałe</strong>)</td><td>contractNumber</td><td>Pole techniczne używane przy zaawansowanej integracji (wymaga dodatkowej implementacji). Dostępność funkcjonalności zależy od licencji i może nie być dostępna we wszystkich wdrożeniach.</td></tr><tr><td><strong>Typ procesu</strong> (sekcja <strong>Pozostałe</strong>)</td><td>processType</td><td>Nazwa procesu przekazywana do usługi zapisującej załączany plik w zasobie zewnętrznym. Dostępność funkcjonalności zależy od licencji i może nie być dostępna we wszystkich wdrożeniach.</td></tr><tr><td><strong>Wywołanie walidatora zewnętrznego dla dodanego pliku</strong></td><td>singleFileValidator</td><td>Wywołanie walidatora zewnętrznego dla dodanego pliku. Walidator wołany jest przy próbie dodania każdego pliku (jeśli załącznik nie przejdzie walidacji, to jest odrzucany). Właściwość należy dodać z poziomu Źródła xml.</td></tr></tbody></table>

> Więcej informacji o właściwościach komponentu: [Wspólne właściwości komponentów](https://docs.eximee.com/budowanie-aplikacji/interfejs-uzytkownika/formularze/praca-z-komponentami-bazowymi/wspolne-wlasciwosci-komponentow.md)

## Użycie komponentu

{% stepper %}
{% step %}
**Dodanie pliku**

Aby zaimportować plik za pomocą komponentu **Załączniki**, należy kliknąć przycisk **Dodaj plik**. Otworzy się wtedy systemowe okno wyboru pliku. Po wybraniu pliku zostanie on zaimportowany. Po zakończeniu importu nazwa pliku pojawi się na liście.
{% endstep %}

{% step %}
**Usuwanie pliku**

Zaimportowane pliki można usunąć, klikając przycisk **Usuń** widoczny przy nazwie pliku.
{% endstep %}
{% endstepper %}

![Ilustracja 1. Przykładowy wygląd komponentu na wniosku](https://content.gitbook.com/content/2CssJT0zIo4SJQLbSZ6l/blobs/TKEkbYuWJS7tpFxU1XIU/3k_files/image2025-5-16_8-56-37.png)

![Ilustracja 2. Przykładowy wygląd komponentu z przesłanym załącznikiem](https://content.gitbook.com/content/2CssJT0zIo4SJQLbSZ6l/blobs/3jM4l4r1skVXTpi54W7V/3k_files/image2025-5-16_8-59-42.png)

{% hint style="info" %}
Do komponentu **Załączniki** można dołączyć plik o dowolnym rozszerzeniu.
{% endhint %}

## Opis do załączonych plików

{% hint style="info" %}
Dostępność funkcjonalności zależy od licencji i może nie być dostępna we wszystkich wdrożeniach.
{% endhint %}

Do załączonego pliku można dodać jego opis. W tym celu należy zaznaczyć pole **Możliwość dołączania opisów do załączonych plików** (attachmentWithDescription) (domyślnie pole jest wyłączone). Długość dodanego opisu można ustawić w polu **Maksymalna liczba znaków opisów do załączonych plików** (attachmentDescriptionMaxLength).

## Parametry wejściowe komponentu

| Właściwość             | Opis                                                            |
| ---------------------- | --------------------------------------------------------------- |
| **maxFileSize**        | Maksymalny rozmiar pliku w bajtach                              |
| **validExtensionList** | Lista dopuszczalnych rozszerzeń (jedno rozszerzenie per wiersz) |
| **maxWebcamWidth**     | Maksymalna szerokość zdjęcia z kamery w pikselach               |
| **maxWebcamHeight**    | Maksymalna wysokość zdjęcia z kamery w pikselach                |

## Parametry wyjściowe komponentu

| Właściwość         | Opis                                                                                                                |
| ------------------ | ------------------------------------------------------------------------------------------------------------------- |
| **totalFilesSize** | Suma rozmiarów wszystkich plików dodanych za pomocą komponentu uploader'a                                           |
| **fileNames**      | Pobranie nazwy plików dodanych do kontrolki. Dane zwracane są w formacie JSON: \["nazwaPliku1", "nazwaPliku2", ...] |
| **externalIds**    | Identyfikatory plików z zewnętrznej usługi, podobnie jak powyżej są zwracane w formacie JSON.                       |

Jeśli chcemy w komponencie np. Polu tekstowym wyświetlić sumę rozmiarów wszystkich plików, możemy to zrobić z użyciem właściwości **ŹRÓDŁO DANYCH Z INNEGO POLA** (valueSourceId) komponentu, który ma wyświetlać wartość. W tym celu właściwość **ŹRÓDŁO DANYCH Z INNEGO POLA** przypisujemy następującą wartość: `GesUploadFile1$totalFilesSize` gdzie `GesUploadFile1` jest identyfikatorem komponentu załącznika, natomiast `totalFilesSize` jest właściwością tego komponentu, której wartość zostanie wpisana. Przepisywanie wartości wymaga dodatkowo nasłuchiwania na komponent załącznika.

## Model danych

Dla każdego pliku załączonego w komponencie Załączniki w modelu danych zapisywane są dane o pliku, np. jego nazwa i rozmiar, ale nie sam plik. W polu **Klucz modelu danych** należy wskazać [węzeł wielokrotny](https://docs.eximee.com/budowanie-aplikacji/model-danych/struktura-modelu-danych.md#strukturamodeludanychbudowanieiuzywanie-definiowanietablicowychpolmodeludanych) o liczebności bez górnego limitu, np. `0..null`. Dane pierwszego pliku trafiają do elementu `[0]` tego węzła, drugiego do elementu `[1]` itd. Pod węzłem należy utworzyć pola, które mają być przechowywane:

| Pole                      | Co zawiera                                                                                                                                  |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **formstoreId**           | Identyfikator pliku. Na jego podstawie platforma pokazuje plik na Liście dokumentów i pozwala go pobrać.                                    |
| **externalId**            | Identyfikator pliku w usłudze zewnętrznej, jeśli plik jest do niej przesyłany.                                                              |
| **fileName**              | Nazwa pliku nadana przez platformę.                                                                                                         |
| **originalName**          | Nazwa pliku wybranego przez użytkownika.                                                                                                    |
| **fileSize**              | Rozmiar pliku w bajtach.                                                                                                                    |
| **attachmentDescription** | Opis pliku wpisany przez użytkownika. Pole ma wartość tylko wtedy, gdy włączona jest **Możliwość dołączania opisów do załączonych plików**. |

Pola są opcjonalne – więcej informacji w [Model danych na interfejsie](https://docs.eximee.com/budowanie-aplikacji/interfejs-uzytkownika/formularze/praca-z-komponentami-bazowymi/model-danych-na-interfejsie.md#komponenty-o-wartosci-zlozonej).

{% hint style="warning" %}
Wartości pól z danymi pliku nie należy wpisywać w inny sposób niż przez komponent na formularzu, np. skryptem, integracją albo wartością domyślną. Takie działanie nie jest wspierane i może powodować błędy.
{% endhint %}

Przykład: w komponencie ustawiono **Klucz modelu danych** `wniosek.zalaczniki`, a pod tym węzłem utworzono pola `formstoreId` i `originalName`:

```
wniosek
└── zalaczniki (0..null)
    ├── formstoreId
    └── originalName
```

Użytkownik załącza pliki `dowod.pdf` i `zaswiadczenie.pdf`. Po zapisaniu wniosku model zawiera:

```
wniosek.zalaczniki[0].formstoreId = 7f3c2a91
wniosek.zalaczniki[0].originalName = dowod.pdf
wniosek.zalaczniki[1].formstoreId = 0b84d6e2
wniosek.zalaczniki[1].originalName = zaswiadczenie.pdf
```

Jeśli komponent znajduje się w sekcji powtarzalnej, dane plików z każdego wiersza trafiają do elementu tego wiersza, np. `osoby[1].zalaczniki[0].originalName`.

{% hint style="info" %}
W modelu danych zapisywane są tylko dane o plikach. Przy otwarciu formularza nie są z niego odczytywane, więc lista załączonych plików jest pusta. Aby pokazać pliki na kolejnym formularzu, należy użyć komponentu [Lista dokumentów](https://docs.eximee.com/budowanie-aplikacji/interfejs-uzytkownika/formularze/biblioteka-komponentow-bazowych/5-dokumenty-i-zaloczniki/lista-dokumentow-documentlist.md#pliki-z-modelu-danych).
{% endhint %}

## Definiowanie akcji czyszczenia komponentu

Dla komponentu możliwe jest zdefiniowanie na głównym szablonie wniosku akcji czyszczącej komponent z załączonego pliku. Więcej informacji w [Akcje](https://docs.eximee.com/budowanie-aplikacji/logika-biznesowa/przeplywy/akcje.md).

{% hint style="info" %}
Wniosek demo: demoUploadFile
{% endhint %}

{% hint style="info" %}
♿WCAG: [Dobre praktyki WCAG dla low-code dev](https://docs.eximee.com/budowanie-aplikacji/proces-biznesowy/tworzenie-procesu-biznesowego-w-bpmn-2.0/dobre-praktyki.md)
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.eximee.com/budowanie-aplikacji/interfejs-uzytkownika/formularze/biblioteka-komponentow-bazowych/5-dokumenty-i-zaloczniki/zalaczniki-uploadfile.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
