使い方 (応用編)

MapNJをカスタマイズする方法を紹介します。

Tips

ここで取り扱っているArea, Label, AreaIDなどに関しては「Design Source Setup」を参照してください ( Design Source Setup )
fill（塗り）およびstroke（線）を操作するオプションは、デザインソース自体にこれらが定義されている必要があります。

オプション

インスタンス生成時に第二引数に渡すオブジェクトに指定できるオプションの一覧です。

Sample: JavaScript

const mapnj = new('#your-mapnj', {
  activeAreaId: "foo",
  areaDefaultFillColors: {
    area1: "#123456",
    area2: "red"
  }
});

Global

Option Name	Type	Default	Description
attributeType	id \| data-name	id	SVGにマッピングされた情報を読み取る属性を指定します。 Note MapNJは操作対象のidもしくはdata-name属性の値を読み取ります。デザインソフト上ではこれはレイヤー名に対応させることが可能です。Adobe Illustratorではidもしくはdata-nameを、Figmaではidにマッピングし書き出しを行うことが可能です。
attributeValueSeparator	'-' \| '_'	'-'	mapnjに渡す情報（attributeTypeで指定されている属性の値）をハイフンで区切るかアンダースコアで区切るかを指定します。
activeAreaId	String	''	指定したAreaIDに対応したAreaがアクティブ化します。空文字を指定した場合、Area全てが非アクティブ状態になります。

Area

Option Name	Type	Default	Description
areaDefaultFillColor	String	#eee	全てのAreaのデフォルト時の塗り色を一括指定します。 Note pages.advanced_usage.options.area.areaDefaultFillColor.tips
areaDefaultFillColors	Object	{}	個々のAreaのデフォルト時の塗り色を指定します。 Note areaIDをキーに、cssカラーをバリューに指定します。ここで指定があったAreaはareaDefaultFillColorの指定を上書きします。
areaActiveFillColor	String \| undefined	undefined	全てのAreaのアクティブ時の塗り色を一括指定します。 Note 通常はデザイン時に指定した色がアクティブ色として割り当てられます。
areaActiveFillColors	Object	{}	個々のAreaのアクティブ時の塗り色を指定します。 Note areaIDをキーに、cssカラーをバリューに指定します。ここで指定があったAreaはareaActiveFillColorの指定を上書きします。
areaDefaultStrokeColor	String	#fff	全てのAreaのデフォルト時の線色を一括指定します。
areaDefaultStrokeColors	Object	{}	個々のAreaのデフォルト時の線色を個別指定します。 Note areaIDをキーに、cssカラーをバリューに指定します。ここで指定があったAreaはareaDefaultStrokeColorsの指定を上書きします。
areaActiveStrokeColor	String \| undefined	undefined	全てのAreaのアクティブ時の線色を一括指定します。 Note 通常はデザイン時に指定した色がアクティブ色として割り当てられます。
areaActiveStrokeColors	Object	{}	個々のAreaのアクティブ時の線色を個別指定します。 Note areaIDをキーに、cssカラーをバリューに指定します。ここで指定があったAreaはareaActiveStrokeColorでの指定を上書きします。
transparentDefaultAreas	Boolean	false	全てのAreaのデフォルト時の塗り色と線色を透明にします。(またこの時、その他のエリアのカラー定義はすべて無効化されます。)
areaChangeSpeed	Number	0.5	Areaの切り替わるスピードを指定します。（単位は秒）

Label

Option Name	Type	Default	Description
labelDefaultFillColor	String	#555	全てのLabelのデフォルト時の塗り色を一括指定します。
labelDefaultFillColors	Object	{}	個々のLabelのデフォルト時の塗り色を個別指定します。 Note areaIDをキーに、cssカラーをバリューに指定します。ここで指定があったLabelはlabelDefaultFillColorでの指定を上書きします。
labelActiveFillColor	String	#555	全てのLabelのアクティブ時の塗り色を一括指定します。
labelActiveFillColors	Object	{}	個々のLabelのアクティブ時の線色を個別指定します。 Note areaIDをキーに、cssカラーをバリューに指定します。ここで指定があったAreaはlabelActiveFillColorでの指定を上書きします。
labelDefaultStrokeColor	String	#fff	全てのLabelのデフォルト時の線色を一括指定します。
labelDefaultStrokeColors	Object	{}	個々のLabelのデフォルト時の線色を個別指定します。 Note areaIDをキーに、cssカラーをバリューに指定します。ここで指定があったAreaはlabelDefaultStrokeColorでの指定を上書きします。
labelActiveStrokeColor	String \| undefined	undefined	全てのLabelのアクティブ時の線色を一括指定します。 Note 通常はデザイン時に指定した色がアクティブ色として割り当てられます。
labelActiveStrokeColors	Object	{}	個々のLabelのアクティブ時の線色を個別指定します。 Note areaIDをキーに、cssカラーをバリューに指定します。ここで指定があったAreaはlabelActiveStrokeColorでの指定を上書きします。
transparentDefaultLabels	Boolean	false	全てのLabelのデフォルト時の塗り色と線色を透明にします。(またこの時、その他のエリアのカラー定義はすべて無効化されます。)
labelDispAnim	'static' \| 'fadeIn' \| 'fadeInUp' \| 'fadeInRight' \| 'fadeInDown' \| 'fadeInLeft'	fadeIn	初期化時のLabelの表示エフェクトを指定します。
noEventLabels	Array	[]	Labelをクリックした時のイベントを無効にします。無効にしたいAreaID名を列挙します。 Note 通常Labelはクリックすると、対応するAreaをアクティブ化するイベントが割り当てられています。

Content

Tips

Contentは後述するOption Partsに含まれるパーツを指します。

Option Name	Type	Default	Description
contentChangeSpeed	Number	0.5	コンテンツ（data-mapnj="area-content"）の切り替わるスピードを指定します。（単位は秒）

Background

Option Name	Type	Default	Description
bgDefaultImage	String	''	全てのAreaが非アクティブの時にマップの背景に表示される画像のパス指定します。
bgImages	Object	{}	Areaアクティブ時にマップの背景に表示される画像をAreaIdをキー、画像パスをバリューとし個別指定します。
bgBrightness	Number	100	背景画像の明るさを指定します。（単位はパーセント）
bgChangeSpeed	Number	0.5	背景画像の切り替わるスピードを指定します。（単位は秒）

オプションパーツ

基礎パーツとは別に、オプションパーツを定義することが可能です。オプションパーツはHTMLタグ要素に特定のdata属性を与えます。

Sample: HTML


<!-- Click to make SVG active. -->
<button data-mapnj="selector" data-area-id="foo">Active Foo</button>

<!-- Click to make all SVGs default. -->
<button data-mapnj="reset-selector">Reset</button>

<!-- Appears when A is active. -->
<div data-mapnj="content" data-area-id="foo"></div>

<div>
  <svg id="mapnj-area-foo"></svg>
  <svg id="mapnj-area-bar"></svg>
</div>

Parts Name	Data Attributes	Description
Selector	data-mapnj="selector" & data-area-id="[AreaID]"	クリック時、data-area-idと一致するAreaIDを持つAreaをアクティブ化させます。 ※ data-area-idに空文字を指定すると、後述のarea-reset-selectorと同じ結果になります。
ResetSelector	data-mapnj="reset-selector"	クリック時、全てのAreaを非アクティブ化させます。
Content	data-mapnj="content" & data-area-id="[AreaID]"	ここで指定したdata-area-idと現在アクティブ化しているAreaのIDが一致していた場合、画面に表示されます。 ※ data-area-idに空文字を指定すると、全てのAreaが非アクティブの時に表示されるコンテンツになります。

イベント

インスタンスのonメソッドを利用することで特定のタイミングで実行される関数を定義することが可能です。

Sample: JavaScript

const mapnj = new('#your-mapnj');

mapnj.on('AREA_CHANGE', (mapnj) => {
  console.log('instance:', mapnj);
  console.log('actiev area is :', mapnj.state.activeAreaId);
})

Event Name	Arguments	Description
AREA_CHANGE	mapnj	選択中のエリアが変更された直後に実行されます。また選択中のエリアが無くなった場合にも実行されます。
AREA_CLICK	mapnj	いずれかのエリアがクリックされた直後に実行されます。
AREA_MOUSEOVER	mapnj	いずれかのAreaがマウスオーバーされた直後に実行されます。
AREA_MOUSEOUT	mapnj	いずれかのAreaがマウスアウトされた直後に実行されます。
AREA_LABEL_CLICK	mapnj	いずれかのLabelがクリックされた直後に実行されます。
AREA_LABEL_MOUSEOVER	mapnj	いずれかのLabelがマウスオーバーされた直後に実行されます。
AREA_LABEL_MOUSEOUT	mapnj	いずれかのLabelがマウスアウトされた直後に実行されます。
AREA_SELECTOR_CLICK	mapnj	いずれかのArea Selectorがクリックされた直後に実行されます。
AREA_SELECTOR_MOUSEOVER	mapnj	いずれかのArea Selectorがマウスオーバーされた直後に実行されます。
AREA_SELECTOR_MOUSEOUT	mapnj	いずれかのArea Selectorがマウスアウトされた直後に実行されます。
AREA_RESET_SELECTOR_CLICK	mapnj	いずれかのArea Reset Selectorがクリックされた直後に実行されます。

CSSクラスの利用

インスタンス生成時に第一引数に指定したHTMLタグ要素には、状態に応じたデザインクラスが付加されます。デザインクラスを利用することでMapNJに連動した独自のデザインパーツを作成することも可能です。

Name	Description
--mapnj-is-active-area_true	いずれかのAreaがアクティブ化している時に付加されます。
--mapnj-is-active-area_false	いずれのAreaもアクティブ化していない時に付加されます。
--mapnj-active-area_[AreaID]	アクティブ化されているAreaがある場合にそのAreaIDを最後尾文字列とし、付加されます。
--mapnj-hover-area_[AreaID]	マウスホバーされているAreaがある場合にそのAreaIDを最後尾文字列とし、付加されます。

プログラムからの操作API

MapNJ v1ではコアが選択状態を公開するようになりました。自分のコードから選択・解除・参照・購読ができます。

Sample: JavaScript

const mapnj = new MapNJ('#your-mapnj');

// select / deselect from your own code
mapnj.selectArea('shibuya');
mapnj.reset();

// read the current state
console.log(mapnj.activeAreaId); // also: hoverAreaId, prevActiveAreaId
console.log(mapnj.getState()); // { activeAreaId, prevActiveAreaId, hoverAreaId }

// subscribe to any state change (returns an unsubscribe function)
const off = mapnj.subscribe((state) => {
  console.log('active:', state.activeAreaId);
});
off();

Name	Returns	Description
selectArea(areaId)	void	idを指定してエリアを選択します。外部セレクタをクリックした場合と同じ流儀で、コンテンツ・背景・カラーへ通知されます。
reset()	void	選択を解除します。リセットセレクタのクリックと同じ扱いです。
getState()	MapNJState	現在の状態のスナップショット（activeAreaId / prevActiveAreaId / hoverAreaId）を返します。
subscribe(listener)	() => void	アクションの種類を問わず、状態変化を購読します。解除用の関数を返します。
on(action, callback)	() => void	従来のイベントAPI。v1ではアクション名がTypeScriptで型チェックされ、購読解除関数を返すようになりました。
activeAreaId / hoverAreaId / prevActiveAreaId	string	現在の選択・ホバー状態を読み取る読み取り専用のゲッターです。

React アダプタ

Reactアダプタをサブパス mapnj/react として同梱しました（React 18以上・オプションのpeer dependency）。useMapNJ() フックは、refがDOMへ接続された時点でインスタンスを生成し、状態をReactへ同期し、アンマウント時に破棄します（StrictModeでも安全）。

Sample: React

import { useMapNJ } from 'mapnj/react';

function TouristMap() {
  const { ref, state, selectArea, reset } = useMapNJ({
    areaActiveFillColor: '#e8b4a0',
  });

  return (
    <div>
      <div ref={ref}>{/* inline SVG with mapnj-area-* ids */}</div>
      <p>Active area: {state.activeAreaId || 'none'}</p>
      <button onClick={() => selectArea('shibuya')}>Select Shibuya</button>
      <button onClick={reset}>Reset</button>
    </div>
  );
}

Name	Returns	Description
ref	(node) => void	callback ref。インラインSVGを包むコンテナ要素へ渡します。
mapnj	MapNJ \| null	内部の MapNJ インスタンス（マウント前は null）。コアの全APIを使えます。
state	MapNJState	現在の選択・ホバー状態。変化するとReactが再レンダリングされます。
selectArea(areaId)	void	プログラムからエリアを選択します。
reset()	void	選択を解除します。

CSSフック（data属性）

従来の --mapnj-* クラスに加えて、MapNJ v1では状態をdata属性としても公開します。CSSの属性セレクタで扱いやすくなります。

Sample: CSS

/* container: which area is active / hovered */
#your-mapnj[data-mapnj-active-area='shibuya'] .legend-shibuya {
  font-weight: bold;
}

/* each area / label: current state */
#your-mapnj [data-mapnj-state='active'] {
  filter: drop-shadow(0 2px 6px rgb(0 0 0 / 0.3));
}

Name	Description
data-mapnj-active-area="[AreaID]"	エリア選択中、コンテナに付与されます。未選択のときは属性ごと外れます。
data-mapnj-hover-area="[AreaID]"	エリアのホバー中、コンテナに付与されます（マウス・ペンのみ）。
data-mapnj-state="active \| default"	各エリア・ラベルに付与されます。そのパーツが現在ハイライトされているかを表します。

アクセシビリティと操作性

MapNJ v1では操作品質をオプションではなく標準にしました:

エリアとクリック可能なラベルはフォーカス可能なボタン（role="button", tabindex="0"）になり、Enter / Space で選択できます。
選択中のエリアは aria-pressed="true" を持ち、支援技術が選択状態を追跡できます。
ホバーは Pointer Events を使います。タッチ端末でホバーが残留する問題は解消されました。
OSの「視差効果を減らす」設定が有効な場合、transitionとラベルの登場アニメーションは行われません。

0.x からの移行

0.x系からアップグレードする場合の変更点です:

パッケージはESMファーストになりました（ESM + CJS + IIFE）。mapnj/lib/... からimportしていた場合はパッケージルートからのimportへ切り替えてください。
CDNファイル dist/MapNJ.min.js のパスは変わりません。既存の埋め込みはそのまま動きます。
ホバー系イベントの名前（AREA_MOUSEOVER等）は同じですが、発火元はPointer Eventsになり、タッチでは発火しません。
on() は購読解除関数を返すようになり、不正なイベント名はTypeScriptのコンパイル時に弾かれます。