jaspr-styling

スタイル設定のルール

Jaspr では、Styles クラスを使って、ネイティブで型安全な CSS-in-Dart スタイル設定 API を利用できます。

1. コンポーネントレベルのスタイル（@css アノテーション）

Jaspr でスタイルを定義する際は、コードの局所性を高めるため、コンポーネント内で定義する方法を推奨します。

• ルール 1： コンポーネントにスタイルをスコープするには、List<StyleRule> を返す静的ゲッターに @css アノテーションを付ける必要があります。
• ルール 2： @css スタイルはレンダリング時にグローバル化されるため、スタイルがほかのコンポーネントに漏れないよう、css() 内では .main クラスや #id ID など、具体的な CSS セレクターを使用する必要があります。

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

  @override
  Component build(BuildContext context) {
    return div(classes: 'main', [
      p([.text('Hello World')]),
    ]);
  }

  @css
  static List<StyleRule> get styles => [
    css('.main', [
      // Use css('&') to refer to the parent selector (.main)
      css('&').styles(
        width: 100.px, // Note: Use `.px`, `.rem`, `.percent` extensions on numbers.
        padding: .all(10.rem),
        display: .flex,
      ),
      css('&:hover').styles(
        backgroundColor: Colors.blue,
      ),
      css('p').styles(
        color: Colors.blue,
      ),
    ]),
    // Responsive queries
    css.media(MediaQuery.screen(maxWidth: 600.px), [
      css('.main').styles(flexDirection: .column),
    ])
  ];
}

2. インラインスタイル

Styles インスタンスをネイティブ HTML コンポーネントに直接渡すことができます。これは style="..." HTML 属性としてレンダリングされます。

• ルール 1： インラインスタイルは、状態やパラメーターに応じて変化するスタイルなど、動的なスタイルにのみ使用する必要があります。
• ルール 2： 静的なスタイルには、コンポーネントレベルの @css アノテーションを使用する必要があります。
• ルール 3： メディアクエリ、ホバー状態、アニメーションなどの複雑なルールには、インラインスタイルを使用してはいけません。

// Example of dynamic inline styling driven by state
class ColorBox extends StatelessComponent {
  final Color boxColor;

  const ColorBox({required this.boxColor, super.key});

  @override
  Component build(BuildContext context) {
    return div(styles: Styles(backgroundColor: boxColor), []);
  }
}

3. グローバルな @css スタイル

グローバル変数またはゲッターに @css アノテーションを付けることで、Dart から直接グローバルなスタイルセットを定義できます。

• ルール 1： コンポーネントレベルの @css と同様に、グローバルな @css は サーバー モードと 静的 モードでのみサポートされます。
• ルール 2： グローバルな @css アノテーションは、List<StyleRule> を返すトップレベルのゲッターまたは静的ゲッターに付ける必要があります。

@css
List<StyleRule> get globalStyles => [
  css('body').styles(
    margin: .zero,
    fontFamily: .list([FontFamily('Roboto'), FontFamilies.sansSerif]),
    backgroundColor: Colors.white,
  ),
  css('a').styles(
    textDecoration: TextDecoration(line: .none),
    color: Colors.blue,
  ),
];

4. グローバルな外部スタイルシート

• ルール： 生の .css ファイル（または sass/scss、tailwind などの CSS フレームワーク）を使用する場合は、（サーバー／静的モードでは）Document(head: [...]) コンポーネント内の <link rel="stylesheet"> 要素、または（クライアントモードでは）web/index.html に含める必要があります。

---

Jaspr のスタイルプロパティ

CSS プロパティを推測する必要がなく、コンテキストが過剰にならないよう、Jaspr では CSS プロパティが型安全性の高い Dart クラスに対応付けられています。

Styles() クラスと .styles() メソッドの両方でサポートされているプロパティの全一覧は次のとおりです。

Styles({ // or .styles({
  All? all,
  // Box Styles
  String? content,
  Display? display,
  Position? position,
  ZIndex? zIndex,
  Unit? width,
  Unit? height,
  Unit? minWidth,
  Unit? minHeight,
  Unit? maxWidth,
  Unit? maxHeight,
  AspectRatio? aspectRatio,
  Padding? padding,
  Margin? margin,
  BoxSizing? boxSizing,
  Border? border,
  BorderRadius? radius,
  Outline? outline,
  double? opacity,
  Visibility? visibility,
  Overflow? overflow,
  Appearance? appearance,
  BoxShadow? shadow,
  Filter? filter,
  Filter? backdropFilter,
  Cursor? cursor,
  UserSelect? userSelect,
  PointerEvents? pointerEvents,
  Animation? animation,
  Transition? transition,
  Transform? transform,
  // Flexbox Styles
  FlexDirection? flexDirection,
  FlexWrap? flexWrap,
  JustifyContent? justifyContent,
  AlignItems? alignItems,
  AlignContent? alignContent,
  // Grid Styles
  GridTemplate? gridTemplate,
  List<TrackSize>? autoRows,
  List<TrackSize>? autoColumns,
  JustifyItems? justifyItems,
  Gap? gap,
  // Item Styles
  Flex? flex,
  int? order,
  AlignSelf? alignSelf,
  JustifySelf? justifySelf,
  GridPlacement? gridPlacement,
  // List Styles
  ListStyle? listStyle,
  ImageStyle? listImage,
  ListStylePosition? listPosition,
  // Text Styles
  Color? color,
  TextAlign? textAlign,
  FontFamily? fontFamily,
  Unit? fontSize,
  FontWeight? fontWeight,
  FontStyle? fontStyle,
  TextDecoration? textDecoration,
  TextTransform? textTransform,
  Unit? textIndent,
  Unit? letterSpacing,
  Unit? wordSpacing,
  Unit? lineHeight,
  TextShadow? textShadow,
  TextOverflow? textOverflow,
  WhiteSpace? whiteSpace,
  Quotes? quotes,
  // Background Styles
  Color? backgroundColor,
  ImageStyle? backgroundImage,
  BackgroundOrigin? backgroundOrigin,
  BackgroundPosition? backgroundPosition,
  BackgroundAttachment? backgroundAttachment,
  BackgroundRepeat? backgroundRepeat,
  BackgroundSize? backgroundSize,
  BackgroundClip? backgroundClip,
  // Raw Styles
  Map<String, String>? raw,
})

• ルール 1： すべてのプロパティは、Styles クラス内で定義されている順序で記述する必要があります。
• ルール 2： 該当する場合は、すべてのスタイルプロパティと値にドット省略記法を使用する必要があります（例：padding: Padding.all(Unit.pixels(10)) ではなく padding: .all(10.px)、または justifyContent: JustifyContent.center ではなく justifyContent: .center）。
• ルール 3： Styles クラスでサポートされていないプロパティには、raw を使用する必要があります。

重要： 以下の領域のスタイルを書く前に、このスキルに付属する該当のリファレンスファイルを必ず読んでください。

• references/sizing.md（.px、.percent などの単位、寸法、マージン、パディング、ボーダー、角丸）
• references/color.md（色、HEX、RGB、HSL 値）
• references/box.md（位置、オーバーフロー、変形、背景、カーソル、フィルター、z-index、可視性）
• references/typography.md（テキストの配置、フォント、テキスト装飾、文字間隔）
• references/flexbox.md（Flexbox のコンテナー／アイテム、フレックスレイアウト、配置）
• references/grid.md（Grid レイアウト、トラックサイズ、ギャップ、テンプレート）
• references/animation.md（トランジション、アニメーション、キーフレーム、曲線、継続時間）