Parser kontaktów VCF

Parser VCF – podgląd i konwersja plików vCard w przeglądarce

VCF (vCard File) to standardowy format przechowywania kontaktów – używany przez telefony, Gmail, Outlook i Apple Contacts. Narzędzie parsuje pliki .vcf bezpośrednio w przeglądarce (bez wysyłania na serwer), wyświetla listę kontaktów i umożliwia eksport do CSV.

Jak parser VCF czyta plik vCard

Parser traktuje plik vCard jako zwykły tekst i czyta go linia po linii, a strukturę kontaktu buduje dopiero z tych linii. Najpierw dzieli całą zawartość na karty: wszystko między BEGIN:VCARD a END:VCARD to jeden kontakt, a kolejne pary tych znaczników to kolejne osoby. Dopiero wewnątrz karty każda linia jest rozbijana na trzy części: nazwę właściwości (np. TEL), parametry po średnikach (np. TYPE=CELL) oraz wartość po dwukropku, czyli sam numer. Bez tego podziału nie da się odróżnić numeru komórkowego od służbowego, bo oba są zapisane tą samą właściwością TEL.

Drugi etap to normalizacja zapisu. Standard dopuszcza łamanie długich linii: kontynuacja zaczyna się od spacji albo tabulatora i formalnie należy do poprzedniej linii, więc parser musi je najpierw skleić — inaczej adres lub notatka urwą się w połowie. W wartościach występują też znaki zastępcze: \n oznacza przejście do nowej linii, \, przecinek, \; średnik, a \\ ukośnik. Jeśli ich nie rozwinąć, w podglądzie pojawią się surowe backslashe zamiast czytelnego tekstu, a adres z przecinkiem rozsypie się na kilka pól.

Trzeci etap to różnice między wersjami standardu. Starsze karty 2.1 kodują polskie znaki przez QUOTED-PRINTABLE i parametr CHARSET, karty 3.0 i 4.0 zakładają UTF-8, a zdjęcia bywają dołączone jako base64. Parser sprowadza to do jednego modelu: jedna karta to jeden rekord, a każde wystąpienie TEL, EMAIL czy ADR to osobna wartość z etykietą typu. Grupowanie po kropce, stosowane przy niektórych właściwościach, jest przy tym pomijane jako element porządkowy. Cała operacja odbywa się w przeglądarce przez File API — zawartość pliku nie jest nigdzie wysyłana.

Przykład: dwie karty w jednym pliku krok po kroku

1. Zapisujesz na dysku plik kontakty.vcf wyeksportowany z telefonu i wskazujesz go w narzędziu przez pole wyboru pliku. Przeglądarka odczytuje go lokalnie jako tekst, bez kontaktu z serwerem.
2. Parser skanuje tekst w poszukiwaniu par BEGIN:VCARD i END:VCARD i rozcina całość na osobne karty — w tym przykładzie na dwie. Wszystko, co znajduje się poza tymi znacznikami, jest pomijane.
3. W pierwszej karcie skleja złamaną linię notatki, której kontynuacja zaczynała się od spacji, a następnie zamienia sekwencję \, na zwykły przecinek w adresie. Dzięki temu adres wyświetla się jako jeden ciąg, a nie jako ucięty fragment.
4. Z właściwości N i FN parser buduje nazwę: z N rozdziela człony po średniku na nazwisko i imię, a FN pokazuje jako gotową nazwę do wyświetlenia. Gdy FN brakuje, nazwa jest składana z członów N.
5. Oba wystąpienia TEL rozpoznaje jako osobne wartości i przypisuje im typ odczytany z parametru — numer komórkowy oraz numer służbowy trafiają do podglądu razem z etykietami, zamiast zostać sklejone w jedno pole.
6. W drugiej karcie parser napotyka PHOTO zakodowane w base64. Nie odtwarza obrazu, ale nie przerywa parsowania — rekord trafia na listę z pozostałymi polami, a eksport do CSV obejmuje dane tekstowe.

Właściwości vCard i ich odwzorowanie w podglądzie

Jak korzystać z parsera, żeby wynik był wiarygodny

• Zacznij od jednej karty testowej — jeśli przygotowujesz własny plik, sprawdź na pojedynczym kontakcie, czy nazwa, numer i adres wyświetlają się poprawnie, dopiero potem wczytuj cały zbiór.
• Sprawdź kodowanie przed importem — pliki ze starych telefonów bywają zapisane w innym zestawie znaków; jeśli polskie litery wyglądają jak ciągi typu =C5=82, problem leży po stronie kodowania w pliku, a nie parsera.
• Nie usuwaj oryginalnego .vcf — eksport do CSV jest stratny: gubi typy telefonów, wiele wartości w jednym polu i zdjęcia. Plik źródłowy zachowaj jako kopię zapasową.
• Uważaj na duże pliki ze zdjęciami — zdjęcia zapisane w base64 znacznie zwiększają rozmiar pliku, więc wczytywanie i przewijanie listy trwa dłużej, a podgląd tekstowy i tak nie pokaże obrazu.
• Zweryfikuj notatki i adresy — to pola najczęściej łamane na kilka linii. Jeśli tekst wygląda na ucięty, najpewniej brakuje spacji lub tabulatora na początku linii kontynuacji.

Czego narzędzie nie zrobi

• Nie scala duplikatów — jeśli w pliku ten sam kontakt występuje kilka razy, każda karta trafi na listę osobno. Narzędzie nie porównuje rekordów ani nie usuwa powtórzeń.
• Nie zachowuje pełnej struktury w CSV — arkusz jest płaski, więc kilka numerów, kilka adresów e-mail czy etykiety typów zostaną uproszczone. Odtworzenie ich po imporcie do innego programu może być niemożliwe.
• Nie mapuje wszystkich właściwości — pola niestandardowe, rozszerzenia producentów, znaczniki kategorii i relacji mogą zostać pominięte albo pokazane w formie surowej wartości.
• Nie naprawia uszkodzonych plików — brak znacznika zamykającego kartę, niedomknięty cudzysłów albo źle zakodowane znaki powodują, że parser pominie fragment lub potraktuje go jako część sąsiedniego kontaktu.

Najczęstsze pytania

Powiązane narzedzia: konwersja CSV, generator kontaktow testowych i walidator JSON.