jaspr-fundamentals

コンポーネント

Jaspr は、Flutter のウィジェットと非常によく似たコンポーネントベースのアーキテクチャを採用しています。UI の構成、アーキテクチャ、状態管理などの概念は、そのまま応用できます。

• StatelessComponent：変更可能な状態を必要としないコンポーネントに使用します。Component build(BuildContext context) をオーバーライドする必要があります。
• StatefulComponent：変更可能な状態を持つコンポーネントに使用します。対応する State クラスが必要です。状態には initState() や dispose() などのライフサイクルメソッドがあります。状態クラスで Component build(BuildContext context) をオーバーライドする必要があります。
• InheritedComponent：コンポーネントツリーの下層へコンテキストや状態を効率よく伝播させるために使用します。

build からコンポーネントを返す

Jaspr で UI を構築するには、build() から単一の Component を返す必要があります。

• ルール 1： Iterable<Component> build(BuildContext context) sync* は使用してはいけません。これはレガシーコードです。
• ルール 2： フラグメント、テキスト、空のノードには、大文字で始まるコンポーネント名ではなく、ドット短縮記法を使用してください。
  • .fragment([...]) を使用します（Fragment([...]) や fragment([...]) は使用しないでください）。
  • .text('...') を使用します（Text('...') や text('...') は使用しないでください）。
  • 空のスペースを安全に返すには .empty() を使用します。

使用例：

import 'package:jaspr/jaspr.dart';
import 'package:jaspr/dom.dart';

class MyComponent extends StatelessComponent {
  const MyComponent({super.key});

  @override
  Component build(BuildContext context) {
    // 1. Return a single component (e.g. div)
    // 2. Use dot-shorthand (.text) instead of Text()
    return div(classes: 'my-class', [
      .text('Hello World'),
    ]);
  }
}

HTML コンポーネント

Jaspr は、標準的な HTML 要素（例：div()、p()、a()、button()）に対応する型付きコンポーネントを提供します。これらを使用するには、package:jaspr/dom.dart をインポートします。

すべての HTML コンポーネントは、標準的な名前付きパラメーター Key? key、String? id、String? classes、Styles? style、Map<String, String>? attributes、Map<String, void Function(Event)>? events を受け取ります。 ほとんどの HTML コンポーネントは、位置引数の List<Component> children パラメーターを受け取ります（img、input、br などの自己終了タグを除きます）。

• ルール 1： children リストは、すべての名前付きパラメーターの後、必ず最後に指定してください。
• ルール 2： 生の attributes: マップや events: マップを使用するより、利用可能な型付きパラメーター（例：href、src、onClick）を必ず優先してください。
• ルール 3： HTML コンポーネントで利用できる型付きパラメーターがわからない場合は、このスキルとともに提供されている該当のリファレンスファイルを必ず確認してください。
  • references/html/<tag>.md には、指定したタグのコンポーネントのシグネチャーと使用例がすべて記載されています（例：div() の references/html/div.md、button() の references/html/button.md など）。
• ルール 4： タグに対応するリファレンスファイルが存在しない場合（したがって、そのコンポーネント自体も存在しない場合）は、代わりに汎用の .element(tag: '...', /* other standard params, */ children: [ /* ... */ ]) コンストラクターを必ず使用してください。

使用例：

import 'package:jaspr/jaspr.dart';
import 'package:jaspr/dom.dart';

class MyHtmlComponent extends StatelessComponent {
  const MyHtmlComponent({super.key});

  @override
  Component build(BuildContext context) {
    return div(id: 'my-container', classes: 'my-class', [ 
      p(attributes: {'aria-label': 'Example Paragraph'}, [
        .text('Hello World'),
      ]),
      // E.g. signature as found at 'references/html/a.md'
      a(href: 'https://example.com', [
        .text('Click me'),
      ]),
    ]);
  }
}

コンポーネントのスタイリング

Jaspr は、CSS-in-Dart を使用したコンポーネントのスタイリングを標準でサポートしています。 詳しくは、jaspr-styling スキルを参照してください。

インタラクティブ機能とイベント

1. ブラウザー API へのアクセス

• ルール 1： server モードまたは static モードでは、ブラウザー API へのアクセスに package:universal_web/web.dart を、js interop API へのアクセスに package:universal_web/js_interop.dart を必ず使用してください。
• ルール 2： server モードまたは static モードで package:universal_web を使用する場合は、サーバーのレンダリング時にクラッシュしないよう、すべての API 呼び出しを if (kIsWeb) チェックで必ず囲んでください。
• ルール 3： client モードでは、dart:js_interop と package:web を直接使用できます。
• ルール 4： グローバルイベントを扱う場合、window または document のイベントをリッスンするには、型付きの Dart Stream を提供する web.EventStreamProviders を必ず使用してください。

// Example of safe usage in server/static mode:
import 'package:universal_web/web.dart' as web;

void logSize() {
  if (kIsWeb) {
    print('Window size: ${web.window.innerWidth}x${web.window.innerHeight}');

    // Example of global event listener
    final sub = web.EventStreamProviders.resizeEvent.forTarget(web.window).listen((event) {
      print('Window resized');
    });
  }
}

2. イベントの処理

すべての DOM コンポーネントは events: パラメーターに対応しており、インタラクティブなコンポーネントは onClick や onChange などの型付きイベントコールバックを備えています。

• ルール 1： 生のイベントに型を指定する場合は、必ず web.Event を使用してください。
• ルール 2： 必要に応じて、型安全なコールバックを作成するために events() ヘルパー関数を使用してください。

import 'package:jaspr/jaspr.dart';
import 'package:jaspr/dom.dart';
import 'package:universal_web/web.dart' as web;

class MyButton extends StatelessComponent {
  @override
  Component build(BuildContext context) {
    return div(
      // Using raw events
      events: {'click': (web.Event event) {
        print('Div clicked');
      }},
      [
        // Using typed parameters
        button(
          onClick: () => print('Button clicked'),
          [.text('Click me')]
        )
      ]
    );
  }
}

3. 要素へのアクセス（GlobalNodeKey）

Jaspr がレンダリングした DOM 要素を直接参照する必要がある場合は、GlobalNodeKey を割り当てることができます。

import 'package:jaspr/jaspr.dart';
import 'package:jaspr/dom.dart';
import 'package:universal_web/web.dart' as web;

class MyInput extends StatefulComponent {
  @override
  State<MyInput> createState() => _MyInputState();
}

class _MyInputState extends State<MyInput> {
  final GlobalNodeKey<web.HTMLInputElement> inputKey = GlobalNodeKey();

  void focusInput() {
    inputKey.currentNode?.focus();
  }

  @override
  Component build(BuildContext context) {
    return input(key: inputKey, type: .text);
  }
}

---

参考資料

• プリレンダリング、非同期データ取得、ハイドレーション、@client アノテーションについては、関連スキル jaspr-pre-rendering-and-hydration をご覧ください。
• コンポーネントのスタイリングについては、関連スキル jaspr-styling をご覧ください。
• HTML を Jaspr コードに変換する方法については、関連スキル jaspr-convert-html をご覧ください。
• 利用可能なドキュメントの一覧は、https://jaspr.site/llms.txt でご確認いただけます。