gomponents

gomponents

概要

gomponents は、HTML 要素を合成可能な Go の値として扱う、純粋な Go 製 HTML コンポーネントライブラリです。すべてが Node インターフェースを基盤として構築されており、型安全で合成可能な HTML を作成できます。

このスキルを使用する場面

次の場合にこのスキルを使用します。

• gomponents のコードを読んだり書いたりするとき
• Go アプリケーションでサーバーサイドの HTML ビューを構築するとき
• Go で再利用可能な HTML コンポーネントを作成するとき

コアインターフェース

gomponents のすべての要素が Node インターフェースを実装しています。

type Node interface {
    Render(w io.Writer) error
}

主な関数

要素と属性の作成

• El(name string, children ...Node) - カスタム HTML 要素を作成します
• Attr(name string, value ...string) - カスタム属性を作成します

標準的な HTML5 要素と属性の多くは、html パッケージの関数として利用できます。

• 要素：Div()、Span()、P()、A() など
• 属性：Class()、ID()、Href()、Src() など

注： nil の Node はレンダリング時に無視されるため、要素に nil ノードを渡しても安全です。

テキストコンテンツ

• Text(string) - HTML エスケープされたテキストコンテンツ
• Textf(format string, args...) - 書式指定された、エスケープ済みテキスト
• Raw(string) - エスケープされていない HTML
• Rawf(format string, args...) - 書式指定された、エスケープされていないコンテンツ

合成

• Group([]Node) - 複数のノードを結合します
• Map[T]([]T, func(T) Node) - スライスをノード列に変換します
• If(condition bool, node Node) - 条件付きでレンダリングします
• Iff(condition bool, func() Node) - 遅延条件付きレンダリング（評価を遅延します）

インポート規約

一般的な Go の慣習とは異なり、gomponents では DSL のような構文を実現するために、ドットインポートが推奨されています。

import (
    . "maragu.dev/gomponents"
    . "maragu.dev/gomponents/html"
    . "maragu.dev/gomponents/components"
)

これにより、HTML のように読みやすいコードを記述できます。

Div(Class("container"),
    H1(Text("Hello World")),
    P(Text("Welcome to gomponents")),
)

パッケージ構成

• maragu.dev/gomponents - コアインターフェースとヘルパー関数
• maragu.dev/gomponents/html - すべての HTML5 要素と属性
• maragu.dev/gomponents/http - コンポーネントをレスポンスとしてレンダリングする HTTP ヘルパー
• maragu.dev/gomponents/components - より高水準のユーティリティ（HTML5 ドキュメント構造、動的クラス）

よく使われるパターン

基本的なコンポーネント

func UserCard(name, email string) Node {
    return Div(Class("user-card"),
        H2(Text(name)),
        P(Text(email)),
    )
}

条件付きレンダリング

func Alert(message string, isError bool) Node {
    return Div(
        If(isError, Class("error")),
        If(!isError, Class("info")),
        P(Text(message)),
    )
}

ノードを常に安全に評価できる場合は If を使用します。ノードが nil の可能性があり、条件が true の場合にのみ評価すべき場合は Iff を使用します。

func UserProfile(user *User) Node {
    return Div(
        H1(Text(user.Name)),
        // Use Iff to avoid nil pointer dereference when user.Avatar is nil
        Iff(user.Avatar != nil, func() Node {
            return Img(Src(user.Avatar.URL))
        }),
    )
}

親要素なしでのグループ化

複数のノードを親要素で囲まずにまとめるには、Group を使用します。

func FormFields(required bool) Node {
    return Group{
        Label(For("email"), Text("Email")),
        Input(Type("email"), ID("email")),
        If(required, Span(Class("required"), Text("*"))),
    }
}

リストのレンダリング

func TodoList(todos []Todo) Node {
    return Ul(Class("todo-list"),
        Map(todos, func(t Todo) Node {
            return Li(Text(t.Title))
        }),
    )
}

HTML ドキュメント

func Page(title string, body Node) Node {
    return HTML5(HTML5Props{
        Title:    title,
        Language: "en",
        Head: []Node{
            Link(Rel("stylesheet"), Href("/styles.css")),
        },
        Body: []Node{body},
    })
}

HTTP ハンドラー

import ghttp "maragu.dev/gomponents/http"

func HomeHandler(w http.ResponseWriter, r *http.Request) (Node, error) {
    return Page("My App",
        Div(Class("container"),
            H1(Text("Hello, World!")),
        ),
    ), nil
}

// In main:
http.HandleFunc("/", ghttp.Adapt(HomeHandler))

http パッケージでは、次の機能を利用できます。

• Handler 型 - (Node, error) を返す関数シグネチャ
• Adapt(Handler) - Handler を http.HandlerFunc に変換します
• StatusCode() int インターフェースを使用した、カスタムステータスコードによるエラー処理