Md2Form engine documentation

基本的な使い方

6 min read

基本的な使い方

このページでは、md2formのインストールから基本的な使用方法までを説明します。

インストール

npmを使用する場合

npm install md2form

Bunを使用する場合（推奨）

bun add md2form

開発環境のセットアップ

プロジェクトの開発やカスタマイズを行う場合：

git clone <repository-url>
cd md2form
bun install

開発環境ではBun v1.2.18以降を推奨しています。

基本的な使い方

シンプルな例

最も基本的な使用方法から始めましょう：

import { parseMarkdownToForm } from "md2form"
 
const markdown = `
# 基本的なフォーム
 
## 質問セクション
### お名前
#type short_text
#required true
`
 
const form = await parseMarkdownToForm(markdown)
console.log(form)

この例では、以下の構造のフォームが作成されます：

  • フォームタイトル: “基本的なフォーム”
  • 1つのページ（セクション）: “質問セクション”
  • 1つの必須テキスト入力: “お名前”

フロントマター付きの例

より詳細な設定を含む例：

const markdown = `
---
collectEmail: true
showProgressBar: true
allowMultipleResponses: false
themeColor: "#3B82F6"
---
 
# お客様アンケート
 
お客様の声をお聞かせください。
 
## 基本情報
 
### お名前を入力してください
#type short_text
#placeholder "山田 太郎"
#required true
 
### メールアドレス
#type email
#placeholder "example@example.com"
#required true
 
## 評価
 
### サービスの満足度
#type rating
#scale 5
#labels "不満","とても満足"
#required true
`
 
const form = await parseMarkdownToForm(markdown)
 
// フォーム情報にアクセス
console.log(form.title) // "お客様アンケート"
console.log(form.settings?.collectEmail) // true
console.log(form.settings?.themeColor) // "#3B82F6"
console.log(form.pages.length) // 2 (基本情報、評価)

返されるオブジェクトの構造

パースされたフォームは以下の構造を持ちます：

{
  title: "お客様アンケート",
  description: "お客様の声をお聞かせください。",
  settings: {
    collectEmail: true,
    showProgressBar: true,
    allowMultipleResponses: false,
    themeColor: "#3B82F6"
  },
  pages: [
    {
      title: "基本情報",
      elements: [
        {
          type: "short_text",
          label: "お名前を入力してください",
          placeholder: "山田 太郎",
          required: true
        },
        {
          type: "email",
          label: "メールアドレス",
          placeholder: "example@example.com",
          required: true
        }
      ]
    },
    {
      title: "評価",
      elements: [
        {
          type: "rating",
          label: "サービスの満足度",
          scale: 5,
          labels: { low: "不満", high: "とても満足" },
          required: true
        }
      ]
    }
  ]
}

サンプルの実行

プロジェクトには完全なサンプルが含まれています：

# サンプルフォームをパースして結果を確認
bun run workspace

これにより：

  1. workspace/sample-form.md がパースされます
  2. 結果が workspace.json に出力されます
  3. コンソールにフォーム構造が表示されます

サンプルフォームの内容

workspace/sample-form.md にはすべての質問タイプを含む完全なサンプルがあります：

  • テキスト入力（短文・長文）
  • 数値入力
  • メール・電話番号
  • 選択系（ドロップダウン・ラジオ・チェックボックス）
  • 日時選択
  • 評価系（星評価・リッカート尺度・マトリクス・スケール）
  • ファイルアップロード
  • 電子署名
  • メディア表示
  • その他

エラーハンドリング

パースエラーが発生した場合の処理：

try {
  const form = await parseMarkdownToForm(markdown)
  // 正常な処理
} catch (error) {
  console.error("パースエラー:", error)
  // エラー処理
}

型安全性の活用

TypeScriptを使用している場合、型定義を活用して安全にデータを扱えます：

import { parseMarkdownToForm } from "md2form"
import type { FormDocument, ShortText, NumberField } from "md2form"
 
const form: FormDocument = await parseMarkdownToForm(markdown)
 
// 型安全なアクセス
form.pages.forEach((page) => {
  page.elements.forEach((element) => {
    if (element.type === "short_text") {
      const shortText = element as ShortText
      console.log(shortText.placeholder) // 型安全
    }
 
    if (element.type === "number") {
      const numberField = element as NumberField
      console.log(numberField.min, numberField.max) // 型安全
    }
  })
})

次のステップ

基本的な使い方を理解したら、以下のページでより詳細な情報を確認してください：

よくある質問

Q: Bunではなくnpmやyarnでも使用できますか？

A: はい、md2formはnpmやyarnでも正常に動作します。ただし、開発環境ではBunの使用を推奨しています。

Q: ブラウザで直接使用できますか？

A: md2formはNode.js環境での使用を想定しています。ブラウザで使用する場合は、バンドラー（webpack、Viteなど）を使用してください。

Q: パース結果をJSONファイルに保存したい場合は？

A: 以下のようにして保存できます：

import { writeFile } from "fs/promises"
 
const form = await parseMarkdownToForm(markdown)
await writeFile("form.json", JSON.stringify(form, null, 2))

Graph View

Backlinks