PaymentAddress.dependentLocality — Eigenschaft · JavaScript-Referenz

Signatur

PaymentAddress.dependentLocality

Beschreibung

Die schreibgeschützte Eigenschaft dependentLocality eines PaymentAddress-Objekts enthält eine Unterlokalität innerhalb der Stadt (city), also etwa einen Stadtteil, Bezirk, Ortsteil oder Distrikt. Das Adressobjekt erhält man über die Payment Request API, meist über PaymentResponse.shippingAddress oder PaymentRequest.shippingAddress.

In vielen Ländern, darunter Deutschland, Österreich und die USA, ist dieses Feld für die Postzustellung nicht nötig und daher meist ein leerer String. Wichtig wird es in Ländern, in denen der Stadtteil zur offiziellen Postanschrift gehört, z. B. in Südkorea, China, Großbritannien (dependent locality), Mexiko (colonia) oder Brasilien (bairro).

Man nutzt die Eigenschaft, um aus der vom Browser gelieferten Adresse eine vollständige Versandadresse zusammenzusetzen oder um Versandkosten nach Bezirk zu berechnen, etwa im shippingaddresschange-Ereignis.

Rückgabewert

Typ

string

Beschreibung

Die Unterlokalität (Stadtteil, Bezirk, Distrikt) oder ein leerer String, wenn keine angegeben wurde oder sie im jeweiligen Land nicht üblich ist.

Beispiele

Stadtteil aus der Lieferadresse auslesen

const methods = [{ supportedMethods: 'https://example.com/pay' }];
const details = {
  total: { label: 'Summe', amount: { currency: 'EUR', value: '49.90' } },
  shippingOptions: [{
    id: 'standard', label: 'Standardversand', selected: true,
    amount: { currency: 'EUR', value: '0.00' }
  }]
};

const checkout = async () => {
  const request = new PaymentRequest(methods, details, { requestShipping: true });
  const response = await request.show();
  const address = response.shippingAddress;

  console.log('Stadt:', address.city);
  console.log('Stadtteil:', address.dependentLocality || '(keiner)');

  await response.complete('success');
};

document.querySelector('#kaufen').addEventListener('click', checkout);

Stadt: Seoul Stadtteil: Gangnam-gu

Versandkosten nach Bezirk berechnen

const surcharges = { 'Centro': '2.00', 'Polanco': '3.50' };

const request = new PaymentRequest(
  [{ supportedMethods: 'https://example.com/pay' }],
  { total: { label: 'Summe', amount: { currency: 'MXN', value: '500.00' } } },
  { requestShipping: true }
);

request.addEventListener('shippingaddresschange', (event) => {
  const district = request.shippingAddress?.dependentLocality ?? '';
  const fee = surcharges[district] ?? '5.00';

  event.updateWith({
    total: { label: 'Summe', amount: { currency: 'MXN', value: (500 + Number(fee)).toFixed(2) } },
    shippingOptions: [{
      id: 'lokal', label: `Versand nach ${district || 'Stadt'}`, selected: true,
      amount: { currency: 'MXN', value: fee }
    }]
  });
});

Adresse formatieren, leere Felder weglassen

const formatAddress = (a) => [
  a.recipient,
  ...(a.addressLine ?? []),
  a.dependentLocality,
  [a.postalCode, a.city].filter(Boolean).join(' '),
  a.country
].filter(Boolean).join('\n');

// Mit einem nachgebauten Objekt testen
const demo = {
  recipient: 'Kim Min-jun', addressLine: ['Teheran-ro 123'],
  dependentLocality: 'Gangnam-gu', postalCode: '06133', city: 'Seoul', country: 'KR'
};
console.log(formatAddress(demo));

Kim Min-jun Teheran-ro 123 Gangnam-gu 06133 Seoul KR

// Wichtig · Fallstricke

Veraltet: Die Schnittstelle PaymentAddress wurde aus der Spezifikation entfernt bzw. in ContactAddress umbenannt. Die Browser-Unterstützung ist uneinheitlich, Firefox bietet sie nur hinter einem Flag an. Vor der Nutzung mit 'PaymentRequest' in window prüfen und immer einen Rückfall auf ein normales Formular vorsehen.
Der Wert ist oft ein leerer String, nicht null. Daher mit || oder filter(Boolean) prüfen.
Vor request.show() ist request.shippingAddress gleich null. Deshalb optionale Verkettung (?.) verwenden.
Aus Datenschutzgründen kann der Browser die Adresse im shippingaddresschange-Ereignis gekürzt übermitteln (z. B. ohne addressLine oder recipient). Die vollständige Adresse gibt es erst in der PaymentResponse.
Die Payment Request API funktioniert nur in einem sicheren Kontext (HTTPS), und show() braucht eine Nutzeraktion.
Die Eigenschaft ist schreibgeschützt. Eine Zuweisung hat keine Wirkung und löst im Strict Mode einen TypeError aus.

Siehe auch

ContactAddress.dependentLocality PaymentAddress.city PaymentAddress.recipient PaymentAddress.addressLine PaymentAddress.country