jaspr-styling

样式规则

Jaspr 通过 Styles 类提供原生、类型安全的 Dart 中的 CSS 样式 API。

1. 组件级样式（@css 注解）

在 Jaspr 中，推荐在组件内部定义样式，以确保代码具有更好的内聚性。

• 规则 1： 必须在返回 List<StyleRule> 的静态 getter 上使用 @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 样式

可以在 Dart 中直接使用全局变量或 getter 上的 @css 注解来定义一组全局样式。

• 规则 1： 与组件级 @css 一样，全局 @css 仅支持 server 和 static 模式。
• 规则 2： 必须将全局 @css 注解放在返回 List<StyleRule> 的顶层 getter 或静态 getter 上。

@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 框架），必须通过 <link rel="stylesheet"> 元素在 Document(head: [...]) 组件中（server/static 模式）或 web/index.html 中（client 模式）引入这些文件。

---

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: .all(10.px)，而不是 padding: Padding.all(Unit.pixels(10))；或使用 justifyContent: .center，而不是 justifyContent: 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（过渡、动画、关键帧、曲线、持续时间）