使い方

MapNJは、いくつかの利用方法があります。

インストール方法

NPM経由で利用する

以下のコマンドを利用します。

$ npm install mapnj

CDNからロードする

以下はjsdelivrから最新版を利用する方法です。特定のバージョンを利用したい場合は、バージョンを指定してください。

例: @latest => @0.3.0

<script src="https://cdn.jsdelivr.net/npm/mapnj@latest/dist/MapNJ.min.js"></script>

直接ソースをDLして利用する

GitHub Releaseより各バージョンが利用できます。 ( GitHub Release )

デザイン実装

MapNJを利用するには、事前にデザイン素材をSVGデータとして準備する必要があります。作成にはAdobe IllustratorもしくはFigmaを使うことを推奨します。これらのデザインアプリは出力するSVGのidやdata属性としてデザインレイヤー名を割り当てることが可能だからです。

MapNJは、SVGのdata属性もしくはID属性を読み取り、デザインを操作するモジュールです。

ここではデザインソースの作成を3STEPで解説します。

Tips

是非まずデモで全体像を掴んでください。 ( Demo )

STEP1. SVGイラストの作成

地図全体のベクターデータを作成します。地図はエリアに分割します。

全てのエリアの配色は選択状態（アクティブ状態）のものにします。
必須ではありませんが、ラベル要素も作成します。
必要であればエリア（およびラベル）に線を定義してください。

また、最終的に全ての要素をアウトライン化し、ベクターデータにしてください。

Tips

※MapNJは地図図版のアクティブと非アクティブの状態を管理するスクリプトです。デザイン時は全てのエリアがアクティブである状態を作成し、非アクティブ状態のデザインはJavaScriptで定義します。

※Illustratorで線を利用する場合、線の位置は必ず「中央」を選択してください。「内側」もしくは「外側」を選んだ場合、2色の異なる塗りを持つ要素として、意図とは異なった出力結果になります。

STEP2. デザインノードの命名

デザインアプリのレイヤーパネル上で各パーツに名前を付けていきます。名前には以下のルールを適用します。

mapnj-[種別名]-[AreaId]-[自由テキスト]

Tips

※命名には半角英数字を利用します。

※「種別名」は現在areaとlabelのみを認識します。

※「AreaId」には、エリアとそれと連動させたいラベルで同じものを割り当てるようにします。

※「自由テキスト」は通常利用する必要ありません。予備領域です。

Area

役割 : クリックするとアクティブ化します。また、その他のエリアを非アクティブ化します。

命名例 : mapnj-area-osaka

ラベル / Label

役割 : クリックするとidに指定したエリアがアクティブ化します。また、その他のエリアを非アクティブ化します。

命名例 : mapnj-label-osaka

Tips

複数の要素をグループ化したものが対象である場合、そのグループに対し、この命名を適用してください。

STEP3-1. SVGの書き出し Illustrator編

メニューから「ファイル > 書き出し > 書き出し形式」を選択
SVG書き出しの設定画面でファイル形式を「SVG」に設定
「アートボードごとに作成」にチェックするとアートボードを基準として書き出しが行われます（任意）
「書き出し」を選択
スタイルを「内部CSS」に設定
フォントを「SVG」に設定
[重要] 「オブジェクトID」を、ID属性に対し情報を出力したい場合は「レイヤー名」に、data-name属性に対し出力したい場合は「固有」（もしくは「最小」）に設定
書き出します

Tips

※1MapNJは通常ではSVGパーツのID属性を読み取ります。これをdata-nameに変更するにはオプションを利用します。 (attributeType)

STEP3-2. SVGの書き出し Figma編

Export設定から「SVG」を選択
詳細設定画面を開きます
「Ignore Ovelapping layers」を選択（任意） ※1
「Include "id" attribute」を選択 ※2
書き出します

Tips

※1 チェックを入れなかった場合、上位フレームの色を持つrect要素が追加で出力されます。

※2 チェック入れないとテキスト情報が出力されません。また出力の際はid属性として出力されます。

コード実装

作成したsvgデザインファイルをコードエディタなどで直接開き配置します。
（1行目に<?xml...?>のタグが出力されている場合は削除してください。）
また、ID（もしくはクラス）を与えた任意のタグでSVGタグをラップします。

<div id="your-mapnj">
  <svg>
    <defs>
      <style></style>
    </defs>

    <!-- 通常ノードへマッピングした場合の出力例 -->
    <!-- ※ 注意: Illustratorの設定次第ではidではなくdata-nameにマッピングされています -->
    <path id="mapnj-area-xxx" d="" />
    <path id="mapnj-label-xxx" d="" />

    <!-- グループ化した要素にマッピングした場合の出力例 -->
    <!-- ※ 注意: Illustratorの設定次第ではidではなくdata-nameにマッピングされています -->
    <g id="mapnj-area-xxx"><path d="" /><path d="" /></g>
    <g id="mapnj-label-xxx"><path d="" /><path d="" /></g>
  <svg>
</div>

Node Moduleを使う場合は、MapNJをインポートします。
SVGをラップする要素のセレクタを引数としてインスタンス化します。

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

直接ビルド済みのファイルを利用する場合も同様です。

<script src="path/to/MapNJ.js"></script>
<script>
  const mapnj = new MapNJ('#your-mapnj');
</script>

MapNJのコンストラクタは、第一引数としてCSSセレクタ文字列またはElement型のオブジェクトを受け付けます。コンストラクタ内で引数の型を判別し、適切に処理を行うため、以下のどちらの方法でもインスタンス化が可能です。

new MapNJ('.foo'); 
new MapNJ(document.querySelector('.foo'));