Address Selector | PostcodeJP Docs

Public Clientを準備する

PostcodeJP管理画面へログインし、「料金プラン」でAddress Selectorの利用プランを有効にします。
メニューの「Public Client」を開き、「作成」からPublic Clientを作成します。
機能にAddress Selectorを選び、「許可するWebサイト（Origin）」へWidgetを設置するWebサイトのOriginを登録します。
作成直後の画面に表示されるPublic Keyをコピーします。Public Keyは一覧画面で再表示できません。
Public Keyを<postcodejp-address-selector public-key="...">へ設定します。

先にAddress Selectorの利用プランを有効にする

利用プランが有効になっていない場合、Public ClientでAddress Selectorを選択できません。

Public KeyはBrowserへ公開する用途の認証情報です。Public Keyから短時間有効なsessionを取得して利用するため、server-side secretとしては扱いません。ただし、許可したOriginからだけ利用できるようOrigin制限と組み合わせてください。

API Keyでは利用できません

Address Selectorのpublic-key属性へAddress Search API Keyを設定しても利用できません。Public Clientで発行したPublic Keyを設定してください。

Originはscheme + host + portで一致します

https://example.comに対して、http://example.com、https://www.example.com、https://example.com:8443はそれぞれ別のOriginです。パスやqueryはOriginへ含めません。

Quick start

fixed-version scriptを読み込み、<postcodejp-address-selector>へpublic-keyを設定します。

HTML

<script src="https://js.postcode-jp.com/widgets/address-selector/v1.1.0/address-selector.js"></script>

<postcodejp-address-selector
  public-key="YOUR_PUBLIC_KEY"
  name-prefix="shipping"
  placeholder="住所を検索"
></postcodejp-address-selector>

料金と利用上限はAddress Search APIとは別です。Free / Standard / Businessの最新条件はAddress Selector料金を確認してください。

Attributes

Core

Attribute	Requirement	Purpose
`public-key`	必須	Origin制限付きPublic ClientのPublic Key
`name-prefix`	任意	生成されるhidden inputのname prefix
`placeholder`	任意	検索inputのplaceholder
`disabled`	任意	操作を無効化

Advanced

必要な表示・候補制御だけを指定してください。指定しない場合はcomponentのdefault動作を使用します。

Attribute	Value	Purpose
`display-mode`	inline / dialog	表示方法
`include-general`	boolean	一般郵便番号を候補へ含めるか
`include-office`	boolean	事業所郵便番号を候補へ含めるか
`result-priority`	auto / general / office	候補の優先順
`appearance`	contained / embedded	外観
`selected-display`	full / compact / actions	選択済み住所の表示
`allow-manual`	boolean	手入力を許可するか
`trigger-label`	string	dialogを開くbuttonのlabel
`dialog-title`	string	dialogのtitle
`close-on-select`	boolean	選択後にdialogを閉じるか

Methods

Method	Purpose
`open()`	selector UIを開く
`close()`	selector UIを閉じる
`focus()`	操作開始位置へfocus
`reset()`	選択状態をclear
`getValue()`	現在の選択値を取得

Events

すべてのpcjp:* eventはbubbleし、Shadow DOM境界を越えて伝播します。

detail.valueのfieldは選択結果によって異なり得るため、利用するfieldの存在を確認して扱ってください。

Event	Detail
`pcjp:open`	UIが開いた
`pcjp:close`	UIが閉じた
`pcjp:select`	住所を選択。選択値はdetail.value
`pcjp:change`	選択値が変更。変更後の値はdetail.value
`pcjp:clear`	選択をclear
`pcjp:error`	利用できない場合や設定に問題がある場合。診断情報はdetail.code

Event handling

const selector = document.querySelector("postcodejp-address-selector");

selector.addEventListener("pcjp:select", (event) => {
  const selectedAddress = event.detail.value;
  // 選択結果をアプリケーションへ反映
});

selector.addEventListener("pcjp:error", (event) => {
  // codeは診断情報として記録し、利用者には再試行などの案内を表示
  console.error(event.detail.code);
});

Error handling

pcjp:errorのdetail.codeは診断に利用できます。codeの一覧やdetail.statusの有無を固定せず、未知のcodeも扱えるようにしてください。

検索できない場合は入力を失わず、再試行や設定確認へ進める案内を表示してください。

Lifecycleとcleanup

componentはDOMへ追加すると利用できます。
不要になったcomponentはDOMからremoveできます。
integration側で追加したevent listenerは、画面の破棄時に解除してください。

Accessibility

combobox、dialog、listbox、optionのsemantic rolesと、keyboard/focus操作、live region、選択状態のARIA属性を実装しています。

特定browserやassistive technologyの完全なsupport matrix、WCAGへの完全適合は、この公開契約では保証しません。導入先の実際の画面構成でkeyboardと読み上げを確認してください。