mdmark

ビューとコメントを使う

ビューの印の書き方・ボードと表形式の切り替え・列の絞り込み・コメントを付ける手順

項目の表をボード表示と表形式のビューで見せるとき、表形式のビューを列で絞り込めるようにするとき、読む人が本文の選んだ箇所にコメントを付けられるようにするときに実行する。

前提

手順

ビューを置く

項目の表を印で囲む

<!-- view: group=状態 -->

| 題 | 状態 | 担当 |
| --- | --- | --- |
| 配色の変数を洗い出す | 未着手 | 佐藤 |
| 余白の変数を決める | 進行中 | 鈴木 |
| 印刷の見え方を確かめる | 未着手 | 佐藤 |

<!-- /view -->

表の前に <!-- view: 引数 -->、後ろに <!-- /view --> を書く。 範囲の最初の表が項目になる。 見出しの行が列名、本文の行が項目、セルの文字が値。 group=列名 で、ボード表示で列に分ける列を決める。

ボード表示は、group= の列の値ごとの列を、表に出た順に横に並べる。 列の見出しに、値のアイコン・値・項目の数が出る。 項目は表の行の順に並び、先頭の列の値が題になり、残りの列は列名と値の組で出る。 group= の列と空の値は項目に出さない。 描く先の幅に収まらない列は、ボードの中で横にスクロールする。

ビューの上に、「ボード」「表」の切り替えが出る。 group= を書かないと切り替えを置かず、表形式のビューだけを描く。 閉じの印を書き忘れると、印から文書の終わりまでが範囲になり、書き方の警告が出る。

描いた直後のビューを選ぶ

<!-- view: group=状態 default=table -->

default=board か default=table で、描いた直後に出すビューを決める。 省くと、group= があればボード表示、無ければ表形式のビューを出す。

ボードの列の見出しのアイコンを変える

<!-- view: group=状態 icons=未着手:inbox,完了:archive -->

icons=値:アイコンの名前,… で、group= の列の値ごとのアイコンを上書きする。 書かなかった値は既定のアイコンになる。

値 既定のアイコン
未着手 circle-dashed
進行中 circle-dot
保留 circle-pause
完了 circle-check
中止 circle-x
上に無い値 circle

使えるアイコンは、上の 6 つと inbox・archive・clock・flag・star・bug・eye・lock・zap・ban。 使えない名前を書くと、その値の列には既定のアイコンを付けて描き、書き方の警告が出る。 アイコンは読み上げに含めず、列の見出しは値と項目の数だけが読み上げられる。

表形式のビューを列で絞り込む

絞り込む列を決める

<!-- view: group=状態 default=table filter=担当,題:text -->

filter=列名:種類 で、絞り込みを付ける列と種類を決める。 書き方は 表に機能を付ける の filter= と同じで、種類は select（値を選ぶ）・text（文字を含む行）・date（期間）。 種類を省くと select。 絞り込みのボタンは、ここで決めた列の見出しにだけ付く。

絞り込みは表形式のビューにだけ当たる。 ボード表示は常に全ての項目を出し、列の見出しの項目の数も変わらない。 ボード表示から表形式に戻すと、絞り込みは残っている。 ビューの上に、全ての列を検索する検索欄と件数は置かない。

書き方の誤りを直す

書き方の警告を読む

次の誤りは、ビューを描いたうえで、範囲の上に書き方の警告が出る。

誤り 描き方
group= の列が表に無い ボードにせず、表形式のビューで描く。「ボード」のボタンは押せない
filter= の列が表に無い その列に絞り込みを付けずに描く
filter= の種類が select・text・date でない その列に絞り込みを付けずに描く
icons= に使えないアイコンの名前がある その値の列に既定のアイコンを付けて描く
知らないキーを書いた その指定だけを当てずに描く
範囲に表が無い 範囲の中身をそのまま描く

警告の文言は 書き方の警告 を参照する。

コメントを付けられるようにする

comments をオンにする

features:
  comments: true

コメントの機能は既定でオフ。 使う側のサーバーが mdmark.config.yaml を読んだオブジェクトを、mount の config に渡す（文書を描く）。 文書の <!-- features: +comments --> でも、その文書だけオンにできる（機能をオン・オフする）。

コメントの読み書きの関数を渡す

import { mount } from "https://cdn.jsdelivr.net/gh/shuhei1101/mdmark@{タグ}/dist/index.js";

mount(document.querySelector("#doc"), {
  markdown,
  config: { features: { comments: true } },
  docId: "guide",
  commentStore: {
    load: ({ docId }) => fetch(`/api/comments/${docId}`).then((res) => res.json()),
    save: ({ docId, comment }) =>
      fetch(`/api/comments/${docId}`, {
        method: "POST",
        headers: { "content-type": "application/json" },
        body: JSON.stringify(comment),
      }).then((res) => res.json()),
  },
});

mdmark はコメントを保存しない。 使う側の保存先を呼ぶ load と save を commentStore に渡し、コメントを付ける対象の ID を docId に渡す。

関数 受け取る値 返す値
load { docId } そのコメントの配列を返す Promise
save { docId, comment } 保存したコメントを返す Promise

comment は、選んだ文字 quote・その前の最大 32 文字 prefix・後の最大 32 文字 suffix・コメントの本文 body の文字列。 save が返すコメントと load が返す配列の要素は、これに空でない文字列の id を加えたもの。 load は描くたび（mount・update）に 1 回呼ぶ。 commentStore を渡して docId を渡さないと、mount は何も描かずに TypeError を投げる。

使う側が自分で書いた要素にコメントを付けるときは 部品をJavaScriptから使う。

読む人の操作を確かめる

コメントは、読む人が次の順で付ける。

  1. 本文の文字を、段落・リストの項目・表のセル・見出し・引用のどれか 1 つの中で選ぶ。選んだ文字の終わりの下に「コメント」のボタンが出る。
  2. ボタンを押す。選んだ文字の下に入力欄が開き、本文の欄にフォーカスが移る。
  3. コメントを書き、「コメントを保存」を押す。入力欄が閉じ、選んだ文字に印が付く。
  4. 印を押す（フォーカスして Enter・Space でもよい）。付いたコメントの吹き出しが開く。

入力欄の中・ビューの切り替え・コード・既にある印の中で文字を選んでも、ボタンは出ない。 入力欄は「キャンセル」か Esc で閉じる。 本文があるときは、書いたコメントを捨てて閉じますか？ と確かめる。 入力欄の外を押しても閉じない。 吹き出しは、閉じるボタン・外側を押す・Esc で閉じる。 選んだ文字とコメントの本文は文字として出し、HTML として解釈しない。

保存できないときの動きを知る

本文を書かずに保存すると、入力欄のそばに コメントを書いてから保存してください。 と出る。 save が失敗すると、入力欄と書いた本文を残し、コメントを保存できませんでした。書いたコメントは残っています。もう一度「コメントを保存」を押してください。 と出る。 どちらも選んだ文字に印は付かない。 save の失敗は console.error にも出る。

本文を書き換えたときの付き直しを知る

mount・update で描くたびに、コメントごとに、前後の文字を含めた prefix + quote + suffix が一致する箇所を探す。 無ければ、quote が 1 か所だけ一致する箇所に付ける。 どちらも見つからないコメントは、文書の末尾の 箇所が見つからないコメント の一覧に、選んだ文字と本文を並べる。 同じ箇所のコメントは 1 つの印にまとめ、吹き出しに並べる。

印刷と書き出しでの見え方を知る

印刷では、ビューは今出しているほうを出し、切り替えと絞り込みのボタンを出さない。 コメントは印の地の色を外して下線だけを残し、ボタン・入力欄・吹き出しを出さない。

mdmark export・mdmark build で書き出した 1 枚の HTML でも、ビューと列の絞り込みは外を読まずに動く（文書を書き出す）。 書き出した HTML はコメントの読み書きの関数を持たないため、コメントは付かない。

反映

即時。mount と update で描くたびに、そのとき描く文書の印で決め直す。

確認

ボード表示が描かれている

document.querySelectorAll(".mdmark .mdmark-view-column").length

group= の列の値の種類の数が出る。 列の見出しに値と項目の数が出て、ビューの前後に印の文字が出ていない。

切り替えが働く

「表」を押す。

document.querySelector(".mdmark .mdmark-view-switch-item[data-mode='table']").getAttribute("aria-pressed")

true が出る。 表の行が項目の数だけ並び、ボード表示は隠れる。

列の絞り込みが働く

filter= で指定した列の見出しの絞り込みのボタンを押し、値を選ぶか文字を入れる。 その値・文字に合う行だけが表に残る。 ボード表示に切り替えると、全ての項目が出る。 表形式に戻すと、絞り込みが残っている。

コメントが付く

comments をオンにして commentStore を渡した文書で、本文の文字を選ぶ。 「コメント」のボタンが出る。 本文を書いて保存すると、save が { docId, comment: { quote, prefix, suffix, body } } で 1 回呼ばれる。

document.querySelector(".mdmark .mdmark-comment-mark").textContent

選んだ文字が出る。 印を押すと、書いたコメントの吹き出しが開く。

コメントが付かない

comments をオフ（既定）にした文書で、本文の文字を選ぶ。 ボタンが出ず、load も呼ばれない。 comments をオンにして commentStore を渡さないと、ボタンは出ず、console.error に読み書きの関数が要ることが 1 回だけ出る。

書き方の警告が出る

group= に表に無い列名を書いて描く。 範囲の上に題 書き方の警告 の枠が出て、「ボード」のボタンが押せず、表形式のビューが描かれる。

元に戻す

ビューは、印と閉じの印を消すと、表が普通の表に戻る。 機能ごと止めるときは、機能をオン・オフする で views をオフにする。 コメントは、comments をオフにするか commentStore を渡さないと、ボタンが出なくなる。 保存したコメントは使う側の保存先に残るため、消すときは保存先で消す。