vcard_dart #

English | 简体中文

A comprehensive vCard parsing and generation library for Dart/Flutter.

📖 API Documentation | 📦 pub.dev

Features #

• ✅ Full vCard 2.1, 3.0, and 4.0 support (RFC 2426, RFC 6350)
• ✅ jCard (JSON) representation (RFC 7095)
• ✅ xCard (XML) representation (RFC 6351)
• ✅ Platform-agnostic (Web, Mobile, Desktop)
• ✅ Type-safe API with comprehensive validation
• ✅ Zero dependencies - pure Dart implementation
• ✅ Extensive test coverage

Installation #

Add to your pubspec.yaml:

dependencies:
  vcard_dart: any

Then run:

dart pub get

Quick Start #

import 'package:vcard_dart/vcard_dart.dart';

// Create a vCard
final vcard = VCard()
  ..formattedName = 'John Doe'
  ..name = const StructuredName(
    family: 'Doe',
    given: 'John',
  )
  ..emails.add(Email.work('[email protected]'))
  ..telephones.add(Telephone.cell('+1-555-123-4567'))
  ..addresses.add(const Address(
    street: '123 Main St',
    city: 'Anytown',
    region: 'CA',
    postalCode: '12345',
    country: 'USA',
    types: ['work'],
  ));

// Generate vCard 4.0 string
final generator = VCardGenerator();
final vcardString = generator.generate(vcard, version: VCardVersion.v40);

// Parse vCard
final parser = VCardParser();
final parsed = parser.parseSingle(vcardString);
print(parsed.formattedName); // John Doe

Usage #

Creating vCards #

final vcard = VCard()
  // Required
  ..formattedName = 'Dr. Jane Smith, PhD'
  
  // Structured name
  ..name = const StructuredName(
    family: 'Smith',
    given: 'Jane',
    additional: ['Marie'],
    prefixes: ['Dr.'],
    suffixes: ['PhD'],
  )
  
  // Communication
  ..telephones.addAll([
    Telephone.cell('+1-555-000-0000'),
    Telephone.work('+1-555-111-1111'),
  ])
  ..emails.addAll([
    Email.work('[email protected]'),
    Email.home('[email protected]'),
  ])
  
  // Organization
  ..organization = const Organization(
    name: 'Acme Corporation',
    units: ['Engineering', 'R&D'],
  )
  ..title = 'Senior Engineer'
  ..role = 'Lead Developer'
  
  // Address
  ..addresses.add(const Address(
    street: '456 Tech Park',
    city: 'Silicon Valley',
    region: 'CA',
    postalCode: '94000',
    country: 'USA',
    types: ['work'],
  ))
  
  // Additional info
  ..birthday = DateOrDateTime(year: 1985, month: 4, day: 15)
  ..note = 'Key contact for technical projects'
  ..urls.add(WebUrl.work('https://company.com/jsmith'))
  ..categories = ['Colleague', 'Tech', 'VIP'];

Raw Value Support (Non-Compliant vCards) #

The library supports parsing and generating vCards with unstructured property values for better compatibility with non-compliant data:

// Create from raw (unstructured) values
final rawName = StructuredName.raw('John Doe');
print(rawName.isRaw); // true

final rawAddress = Address.raw('123 Main St, San Francisco, CA 94102');
print(rawAddress.isRaw); // true

final rawOrg = Organization.raw('Acme Inc. - Engineering');
print(rawOrg.isRaw); // true

// Auto-detect format from value string
final autoName = StructuredName.fromValue('Doe;John;;;'); // structured
final rawAutoName = StructuredName.fromValue('John Doe'); // raw

// Convert raw to structured
final parsedName = rawName.toStructured();
print(parsedName.family); // Doe
print(parsedName.given); // John

// Use with vCard
final vcard = VCard()
  ..formattedName = 'Jane Smith'
  ..name = StructuredName.raw('Jane Smith'); // For non-compliant sources

// Parser automatically handles both formats
const nonCompliantVcard = '''
BEGIN:VCARD
VERSION:4.0
FN:Bob Johnson
N:Bob Johnson
ADR:123 Main St, City, State 12345
ORG:Acme Corporation
END:VCARD
''';

final vcard = parser.parseSingle(nonCompliantVcard);
print(vcard.name.isRaw); // true
print(vcard.name.rawValue); // "Bob Johnson"

Parsing vCards #

final parser = VCardParser();

// Parse a single vCard
const vcardText = '''
BEGIN:VCARD
VERSION:4.0
FN:John Doe
N:Doe;John;;;
TEL;TYPE=CELL:+1-555-123-4567
EMAIL:[email protected]
END:VCARD
''';

final vcard = parser.parseSingle(vcardText);
print(vcard.formattedName); // John Doe
print(vcard.telephones.first.number); // +1-555-123-4567

// Parse multiple vCards
const multipleVcards = '''
BEGIN:VCARD
VERSION:4.0
FN:Person One
END:VCARD
BEGIN:VCARD
VERSION:4.0
FN:Person Two
END:VCARD
''';

final vcards = parser.parse(multipleVcards);
print(vcards.length); // 2

// Lenient parsing mode (tolerates some errors)
final lenientParser = VCardParser(lenient: true);
final recovered = lenientParser.parse(malformedVcardText);

Generating vCards #

final generator = VCardGenerator();

// Generate vCard 4.0 (default)
final v40 = generator.generate(vcard);

// Generate vCard 3.0
final v30 = generator.generate(vcard, version: VCardVersion.v30);

// Generate vCard 2.1
final v21 = generator.generate(vcard, version: VCardVersion.v21);

// Generate multiple vCards
final multipleVcards = generator.generateAll([vcard1, vcard2]);

jCard (JSON Format) #

final formatter = JCardFormatter();

// Convert to jCard
final json = formatter.toJson(vcard);
final jsonString = formatter.toJsonString(vcard);

// Parse from jCard
final fromJson = formatter.fromJson(json);
final fromString = formatter.fromJsonString(jsonString);

xCard (XML Format) #

final formatter = XCardFormatter();

// Convert to xCard
final xml = formatter.toXml(vcard);
final prettyXml = formatter.toXml(vcard, pretty: true);

// Parse from xCard
final fromXml = formatter.fromXml(xmlString);

Supported Properties #

Essential Properties #

Communication #

Address/Location #

Organization #

Other #

Error Handling #

The library provides detailed exception types:

try {
  final vcard = parser.parseSingle(invalidText);
} on VCardParseException catch (e) {
  print('Parse error: ${e.message}');
  print('Line: ${e.line}');
} on MissingPropertyException catch (e) {
  print('Missing required property: ${e.propertyName}');
} on UnsupportedVersionException catch (e) {
  print('Version error: ${e.message}');
}

RFC Compliance #

This library implements the following RFCs:

• RFC 2425 - MIME Content-Type for Directory Information
• RFC 2426 - vCard 3.0
• RFC 6350 - vCard 4.0
• RFC 6351 - xCard XML Representation
• RFC 7095 - jCard JSON Format
• vCard 2.1 - Legacy Format

License #

MIT License - see LICENSE for details.

Contributing #

Contributions are welcome! Please read our contributing guidelines first.

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Run tests: dart test
5. Run analysis: dart analyze
6. Format code: dart format .
7. Commit: git commit -m 'feat: add amazing feature'
8. Push: git push origin feature/amazing-feature
9. Open a Pull Request