「CanDume.js」の使い方

（2024/11/17, Version 2.5対応）
  1. はじめに
    1. このツールはWebサーバにアップロードして使用する。
      PC等のローカル環境では動作しない。
    2. 任意のファイルがアップロード可能なWebサービスであれば、ブログツール等でも利用できる（はず）。
    3. 必要に応じて、ダウンロードしたサンプルファイルや、サンプルのアップロード例もご参照。
      • ダウンロードしたファイルの中にある「SampleFiles」フォルダのファイル一式で、動作サンプルとなっている。
      • 「SampleFiles」フォルダごと、Webサーバにアップロードし、index.htmlを閲覧して動作を確認できる。
      • ツールの本体は「SampleFiles」フォルダにある「candume.js」である。
  2. 設置方法
    1. HTMLの例
      このツールではHTML5の<canvas>タグを使用するため、HTML5（正確にはHTML5が廃止された2021年時点のHTML Living Standard）で作成する。
      HTML5とHTML4.1以前が混在している場合、正常動作しない可能性がある。

      <!DOCTYPE html>
      <html lang="ja">
      （…中略…）
      <body>
      （…中略…）
      <canvas data-file="filename.csa" data-zero="0手目の表示" data-start="0"></canvas> ・・・①
      （…中略…）
      <script src="/src/candume.js" data-wm="WatarMark文字列"></script> ・・・②
      </body>
      </html>

      1. 詰将棋を表示させる位置（複数可）に、<canvas～～></canvas>を置く。
        盤面のサイズは、CSS等で指定できる。
        CSS等の指定が無い場合は、ブラウザのウィンドウ・サイズを基準に適当な大きさで表示する。
        1つのページの中の盤のサイズは、すべて同一になります。
        • 「data-file」は、棋譜情報が入った入力ファイル名。
          ファイルの場所を正しく指定する。
          （上記例は、HTMLファイルと同じディレクトリに"filename.csa"が存在する場合）
          「data-file」が無い<canvas>は、処理対象外になる。
        • 「data-file="*"」を指定すると、<canvas>と</canvas>の間の文字列を、CSA形式の棋譜として使用する。
        • 「data-zero」は、0手目局面（通常の詰将棋の初形）で右下に表示する任意の文字列を指定する。
          「data-zero」を省略すると、0手目局面の右下には詰手数を表示する。
        • 「data-start」は、最初に表示する局面（何手目の局面を表示するか）を指定する。
          例えば「data-start="15"」は最初の表示が15手目の局面になる。
          詰手数より大きな数値を指定すると、最初の表示は最終局面になる。
          「data-start」を省略すると、最初の表示は0手目になる（「data-start="0"」と同じ）。
      2. <body>～</body>の範囲の最後に、<script～～></script>を１つ置く。
        （正確にいうと、全てのcanvasより下なら良い）
        src=で、ツールの格納場所を正しく指定する。
        （上記例は、"/src"ディレクトリに"candume.js"が存在する場合）
        • 「data-wm」は、盤面を右クリック（画像コピー等のコンテキストメニュー表示）時に表示する、Watermark文字列を指定する。
          「data-wm」を省略すると、右クリック時にドメイン名を表示する。
          「data-wm=""」は、コンテキストメニューを表示しない。
      3. 同じページ内に他にcanvasタグがある等の問題がある場合は、処理対象のcanvasとscriptを<div>～～</div>で囲む。
        （例）
        <div>
        <canvas data-file="sample.csa"></canvas> ←処理対象
        <script src="/src/candume.js"></script>
        </div>
        <canvas ・・・></canvas> ←処理対象外

      4. data-fileとdata-zeroは、scriptタグで一括設定できる。
        canvasに個別設定があれば、個別設定が優先される。
        • scriptタグの中にdata-zeroを設定すると、data-zeroの設定がないcanvas全てに設定するのと同じ意味になる。
        • scriptタグの中にdata-fileを数値で設定すると、data-fileの設定がないcanvas全てに、１ずつ増加する「数値.csa」を設定するのと同じ意味になる。
          "1.txt"のように設定すると、入力ファイルの拡張子をcsaから変更する。
          （例）
          <div>
          <canvas></canvas> ←data-file="10.csa" と設定したのと同じ
          <canvas data-file="sample.csa"></canvas> ←個別の設定は有効
          <canvas></canvas> ←data-file="11.csa" と設定したのと同じ
          <script src="/src/candume.js" data-file="10"></script>
          </div>

    2. 入力ファイル
      入力ファイルは、CSA標準棋譜ファイル形式の「サブセット」である。
      「柿木将棋IX」などの一般的なソフトウェアで、CSA形式でファイルとして作成できる。
      CSA標準棋譜ファイル形式で規定されている機能のうち、下記には対応していない。
      • 2.5(1) "PI"による平手初期配置
      • 2.5(3) 駒別単独表現は、持駒の指定のみ使用可
        盤面配置は使用不可、"AL"「残りの駒すべてを持駒」は使用不可
      • 2.5(4) 手番は無視します
      • 2.6(2) 特殊な指し手は無視します
      CSA形式としてのエラー（駒配置や指し手のフォーマットエラー）があれば、コンソールに出力する（ブラウザの開発者ツールで確認できる）。 将棋のルールとしてのエラーチェックはしないので、CSA形式で表現できるなら、フェアリールールでもOK。
  3. 動作の概要（ツールの操作方法）
    1. タッチスクリーン
      タッチして盤面選択。
      盤面の右半面をタッチして１手進む。左半面をタッチして１手戻る。
      タッチし続けると加速。
    2. マウス
      クリックして盤面選択。
      盤面の右半面を左ボタンで１手進む。左半面を左ボタンで１手戻る。
      押し続けると加速。
    3. キーボード
      TABキーなどで盤面選択。
      「→」キーで１手進む。「←」キーで１手戻る。押し続けると加速。
    4. 盤面の表示について
      「杏」は成香、「圭」は成桂、「全」は成銀の表示。
  4. 対応ブラウザ
  5. スタイルシートのための参考情報
    1. サンプルの「dark.css」はダークテーマの設定（文字色と背景色）のみ。
    2. 盤面は正方形で、１辺は22pxの倍数。
    3. 選択した盤面のデザインの設定には、focus疑似クラスが使用できる。
  6. サンプルのHTMLについて補足説明
    1. ビューポートの設定
      （５行目　<meta name="viewport" content="width=device-width,initial-scale=1">）
      初期表示の横幅を、ブラウザのウィンドウ横幅に合わせる設定。
      （例えば、スマホの縦長画面では、横幅を合わせた表示になる）
    2. コンテンツ・セキュリティ・ポリシー（CSP）の設定
      （６行目　<meta http-equiv="Content-Security-Policy" content="default-src 'self'">）
      自身のドメイン（self）以外からの読み込みをブロックする設定。
      （サンプルのような単純な例では、あまり意味はない）