使い方
インストール
MapNJは、いくつかの利用方法があります。
NPM経由で利用する
以下のコマンドを利用します。
$ npm install mapnj
CDNからロードする
部分的にバージョンを指定した場合、自動的にそのメジャーバージョンとマイナーバージョン内での最新のパッチバージョンが提供されます。
※ @0.2 => 0.2.0
<script src="https://cdn.jsdelivr.net/npm/mapnj@0.2/dist/MapNJ.min.js"></script>
厳密にバージョンを指定することも可能です。
<script src="https://cdn.jsdelivr.net/npm/mapnj@0.2.0/dist/MapNJ.min.js"></script>
直接ソースをDLして利用する
GitHub Releaseより各バージョンが利用できます。 ( GitHub Release )
デザイン素材素材作成
MapNJを利用するには、事前にSVG(デザインソース)を準備する必要があります。
デザインソースの作成にはAdobe Illustrator (以下Illustrator)とFigmaを使った方法を紹介します。
これらのアプリケーションはSVGを書き出し時に、要素に固有のidやdata属性を設定することが可能です。
MapNJは、その設定を読み取りデザインやイベントを操作します。
ここではデザインソースの作成を3STEPで解説します。
全体像を掴むために是非デモをご参照ください。 ( デモ )
STEP1. SVGイラストの作成
地図全体のベクターデータを作成します。地図はエリアに分割します。
全てのエリアの配色は選択状態(アクティブ状態)のものにします。
必須ではありませんが、ラベル要素も作成します。
必要であればエリア(およびラベル)に線を定義してください。
また、最終的に全ての要素をアウトライン化し、ベクターデータにしておきましょう。
※ MapNJは地図図版のアクティブと非アクティブの状態を管理するスクリプトです。 デザイン時は全てのエリアがアクティブである状態を作成し、非アクティブ状態のデザインはJavaScriptで定義します。
※ Illustratorで線を利用する場合、線の位置は必ず「中央」を選択してください。 「内側」もしくは「外側」を選んだ場合、2色の異なる塗りを持つ要素として、意図とは異なった出力結果になります。
STEP2. デザインノードの名付け
デザインアプリのレイヤーパネル上で各パーツに名前を付けていきます。名前には以下のルールを適用します。
- ※ 命名には半角英数字を利用します。
- ※ 「種別名」は現在areaとlabelのみを認識します。
- ※ 「AreaId」には、エリアとそれと連動させたいラベルで同じものを割り当てるようにします。
- ※ 「自由テキスト」は通常利用する必要ありません。予備領域です。
エリア / Area
役割 : クリックするとアクティブ化します。また、その他のエリアを非アクティブ化します。
命名例 : mapnj-area-osaka
ラベル / Label
役割 : クリックするとidに指定したエリアがアクティブ化します。また、その他のエリアを非アクティブ化します。
命名例 : mapnj-label-osaka
※ 複数の要素をグループ化したものが対象である場合、そのグループノードに対し、命名してください。
STEP3-1. SVGの書き出し Illustrator編
- メニューから「ファイル > 書き出し > 書き出し形式」を選択
- SVG書き出しの設定画面でファイル形式を「SVG」に設定
- 「アートボードごとに作成」にチェックするとアートボードを基準として書き出しが行われます(任意)
- 「書き出し」を選択
- スタイルを「内部CSS」に設定
- フォントを「SVG」に設定
- [重要] 「オブジェクトID」を、ID属性に対し情報を出力したい場合は「レイヤー名」に、data-name属性に対し出力したい場合は「固有」(もしくは「最小」)に設定 ※1
- 書き出します
※1
id属性の値は、文書内で一意(ユニーク)でなければならないことから、data-name属性を利用することは常に良いアプローチになります。 ノード名が重複する可能性がある場合は積極的にdata-name属性(もしくは「自由テキスト」)を活用してください。
data-name属性を利用した場合、attributeTypeオプションを併用する必要があります。 ( attributeType )
STEP3-2. SVGの書き出し Figma編
- Export設定から「SVG」を選択
- 詳細設定画面を開きます
- 「Ignore Ovelapping layers」を選択(任意) ※1
- 「Include "id" attribute」を選択 ※2
- 書き出します
※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'));