Alert

Alert 是 CrossFly 的模态对话框——相当于 MessageBox/AlertDialog。它显示一个标题、一条消息（自动换行）以及一个或多个按行排列的操作按钮。每个按钮都可以有自己的回调；没有回调时，按钮只是关闭对话框。视觉效果（颜色、字体、按钮布局）来自当前激活的 Skin。

🟢 · 包： dev.crossfly.ui · 继承： Window · 样式： AlertStyle + WindowStyle

何时使用

需要用户确认的确认操作（删除？保存？丢弃？）。
简单的是/否选择，或需要一个“确定”的消息。

何时不要使用

被动且短暂的反馈（成功/错误/状态） → 使用 Hint。
针对某个条目的上下文操作列表（分享/编辑/删除） → 使用 ActionSheet。

外观

居中的卡片，顶部为标题，中间为消息，底部为一行按钮。默认情况下背景不会变暗——调整 WindowStyle.fadeBackground 以获得经典的模态效果。

完整示例（复制、粘贴并运行）

package com.exemplo;

import dev.crossfly.ui.*;
import dev.crossfly.ui.layout.*;

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

      Button abrir = new Button("Abrir alerta");
      abrir.onAction(c ->
      {
         Alert a = new Alert("Excluir item",
            "Tem certeza que deseja excluir este item? Esta ação não pode ser desfeita.",
            "Excluir", "Cancelar");
         // 背景变暗以强化模态感 (alpha 0..255)
         WindowStyle ws = a.getStyle();
         ws.fadeBackground(150);
         // 按钮 0 = 删除 -> 执行、关闭并给出反馈
         a.buttonAction(0, origin ->
         {
            a.hide();
            Hint.show("Item excluído", 2000);
         });
         // 按钮 1 = 取消：无回调 -> 默认已调用 hide()
         a.show();
      });
      add(LAY_AUTO, abrir);
   }
}

下面的代码片段只展示核心部分（放进 onShow() 内的内容）。要运行它们，请把它们放入上面的 MainWindow 骨架中。

基本用法

// buttonTexts 是可选的可变参数 — 若为空/null，则变为 {"OK"}
Alert a = new Alert("Aviso", "Operação concluída com sucesso.", "OK");
a.show();

构造函数

构造函数	描述
`Alert(String title, String message, String... buttonTexts)`	`title` 可以是 `""`（视觉上隐藏标题）。`buttonTexts` 可选；为空/`null` → `{"OK"}`。

⚠️ 不存在静态的 Alert.show(...)，也没有会触发回调的构造函数。 始终用 new Alert(...) 实例化，为每个按钮注册回调，然后调用 show()。

属性与自定义

属性 / 方法	类型	默认值	作用
`style()`	`AlertStyle`	skin	返回当前的 `AlertStyle`。
`style(AlertStyle)`	流式	—	设置自定义的 `AlertStyle`。
`style().buttonLayout(...)`	`IOS`/`FLUTTER`/`MATERIAL`	`MATERIAL`	按钮的排列样式。
`style().maxButtonsPerRow(int)`	`int`	skin	每行按钮数；超出的换到新行。
`skin(Skin)`	流式	—	切换 skin 并重新更新 `AlertStyle`。
`getButton(int index)`	`Button`	—	`show()` 之后的按钮（在此之前为 `null`）。
`getAutoWidth()` / `getAutoHeight()`	`int`	—	计算得出的尺寸。

回调与事件

回调	触发时机
`buttonAction(int index, Component.Action action)`	点击索引为 `index` 的按钮时（从 0 开始）。

⚠️ 响应不通过 show(onAnswer) 传回。 Alert 继承自 Window 而非 Picker——而 Window.hide() 只有在 this instanceof Picker 时才会传递 onAnswer。因此，要对每个按钮做出响应，请使用 buttonAction(index, action)。Alert 中没有 getAnswer()。

回调的类型是 Component.Action，其方法为 void run(Component origin)——lambda 体不返回值（不要写 return null;）。

状态

未注册回调的按钮 → 接收默认动作 hide()（关闭对话框）。
有回调的按钮 → 执行回调；如果回调不关闭，对话框会保持打开（请自己调用 a.hide()）。
“返回”/back 手势 → 若 WindowStyle.canHide（默认 true）则被尊重。

带变暗背景的确认

Alert confirm = new Alert("Excluir item",
   "Tem certeza que deseja excluir este item? Esta ação não pode ser desfeita.",
   "Excluir", "Cancelar");

// 背景变暗以强化模态感 (alpha 0..255)
WindowStyle ws = confirm.getStyle();
ws.fadeBackground(150);

// 按钮 0 = 删除 -> 执行、关闭并给出反馈
confirm.buttonAction(0, origin ->
{
   excluirItem();
   confirm.hide();
   Hint.show("Item excluído", 2000);
});
// 按钮 1 = 取消：无回调 -> 默认已调用 hide()

confirm.show();

选择按钮布局

Alert a = new Alert("Salvar", "Deseja salvar as alterações?", "Salvar", "Descartar");
a.style().buttonLayout(AlertStyle.ButtonLayout.IOS)  // IOS / FLUTTER / MATERIAL
         .maxButtonsPerRow(2);
a.show();

最佳实践

用于需要确认的决策。对于被动反馈，优先使用 Hint。
保持按钮数量较少——太多会换行并使对话框变高。
每当想要经典模态效果时，配合 fadeBackground 使用。

常见错误

期望通过 show(onAnswer) 获得响应 —— 那是 Picker 专属的。请注册 buttonAction(...)。
在 show() 之前访问 getButton(i) —— 按钮在 onAdd 中创建，在此之前返回 null。
让 buttonAction 的 lambda 返回值 —— Action.run(...) 是 void。

另见

该领域指南：ui/ · 食谱：cookbook/
相关组件：ActionSheet · Hint