# 组件样式设置

> ComponentStyle — 用于设置组件颜色、边框、圆角、间距、字体和阴影的流式 API。

Source: https://crossfly.dev/zh/docs/ui/theming/styling-components — CrossFly documentation. Full docs as one file: https://crossfly.dev/llms-full.txt

# 组件样式设置（`ComponentStyle`）

`ComponentStyle` 封装了一个组件的**全部**外观。它通过**流式 API** 构建，并用 `componente.style(...)`
应用。

## 完整示例（复制、粘贴并运行）
```java
package com.exemplo;

import dev.crossfly.ui.*;
import dev.crossfly.ui.layout.*;
import dev.crossfly.ui.style.*;   // ComponentStyle, Styles
import dev.crossfly.ui.graphics.*; // Relative

/** 可执行的主界面。将 launcher 指向此类（classname）并运行：gradlew :lwjgl3:run */
public class MainWindow extends Window
{
   @Override
   public void onShow() throws Exception
   {
      super.onShow();
      setLayout(new VerticalLayout());

      // 从零构建的 ComponentStyle，通过 .style(...) 应用
      Button salvar = new Button("Salvar");
      salvar.style(new ComponentStyle()
         .backColor(0xFF0173ED)          // 蓝色背景 (ARGB)
         .textColor(0xFFFFFFFF)          // 白色文字
         .borderColor(0)                 // 无边框
         .borderRadius(0.6f)             // 圆角
         .ingap(Gap.ofFont(0.8f, 0.4f, 0.8f, 0.4f))  // 内边距 (l,t,r,b)
         .autoWidth(Relative.ofScreen(0.6f))
         .pressable());                  // 响应触摸
      add(LAY_AUTO, salvar);

      // 推荐：从主题样式派生，只调整必要的部分
      Button tema = new Button("Cor do tema");
      tema.style(Styles.button()
         .backColor(Styles.primaryColor) // 主题的 PalColor（跟随亮色/暗色）
         .borderRadius(1f));
      add(LAY_AUTO, tema);
   }
}
```
> 下面的片段只展示了**核心部分**（放入 `onShow()` 内部的内容）。要运行它们，请将其放入上面的 `MainWindow` 骨架中。

## 基本用法
```java
Button salvar = new Button("Salvar");
salvar.style(new ComponentStyle()
   .backColor(0xFF0173ED)              // 蓝色背景 (ARGB)
   .textColor(0xFFFFFFFF)              // 白色文字
   .borderColor(0)                     // 无边框
   .borderRadius(0.6f)                 // 圆角
   .ingap(Gap.ofFont(0.8f, 0.4f, 0.8f, 0.4f))      // 内边距
   .pressable());                      // 响应触摸
```

## 按状态应用
```java
salvar.style(normal)
      .focusedStyle(comFoco)     // 聚焦时
      .pressedStyle(apertado);   // 按下时
```

## 从 Skin 的某个样式派生（推荐）
与其从零构建，不如从 `Skin` 的某个样式**派生**，以继承主题的字体/间距/颜色：
```java
// 取当前主题的按钮样式，只调整需要的部分
salvar.style(Styles.button()
   .backColor(Styles.primaryColor)     // 使用主题的主色
   .borderRadius(1f));
```

## 主要属性（流式 setter）
| Setter | 效果 |
|---|---|
| `backColor(int\|PalColor)` | 背景色（`0` = 透明） |
| `textColor(int\|PalColor)` | 文本颜色 |
| `borderColor(int)` · `borderThick(float)` | 边框（`0` = 无边框） |
| `borderRadius(float)` / `borderRadius(tl,tr,bl,br)` | 圆角 |
| `font(Font)` | 字体 — 例如 `Font.get(1.25f, BOLD)` |
| `ingap(Gap)` / `outgap(Gap)` | 内边距 / 外边距 |
| `icongap(Gap)` · `iconColor(int)` | 图标的间距和颜色 |
| `autoWidth(Relative)` / `autoHeight(Relative)` | 响应式自动尺寸 |
| `textAlign(Position h, Position v)` | 文本对齐 |
| `shadow(offX, offY, blur, color)` | 阴影 |
| `pressable()` | 启用按压时的高亮 |

## 颜色：`int` ARGB 或 `PalColor`
- **`int` ARGB**（`0xAARRGGBB`）— 固定颜色：`0xFF0173ED`。
- **`PalColor`**（来自 `Styles`/`ColorScheme`）— **主题**颜色，在切换明/暗时会自动重新解析：
  `Styles.primaryColor`、`Styles.textColor`。**优先使用 `PalColor`** 以跟随主题。

## 最佳实践
- 从 `Styles.button()`/`Styles.label()`/`Styles.textField()` 派生，而不是重新创建全部。
- 使用主题的 `PalColor`（`Styles.primaryColor`、`cs.surface`）— 固定颜色不会跟随暗色模式。
- 用 `Gap.ofFont(...)` 设置间距（随字体缩放）— 永远不要用固定像素。

## 常见错误
- 调用 `setStyle(...)` — 方法名是 **`style(...)`**。
- 使用 `new Color(...)` — `Color` 类已被移除；请使用 `int` ARGB 或 `ColorUtils`。
- 在整个 UI 中使用固定颜色，然后又奇怪为什么暗色模式"不生效"。

## 另请参阅
- [配色方案](/docs/ui/theming/color-schemes) · [明/暗模式](/docs/ui/theming/dark-mode) · [Skins](/docs/ui/theming/skins)