# FAQ — 常见问题

> 对 CrossFly 最常见疑问的简短解答，每条都附有指向权威页面的链接。

Source: https://crossfly.dev/zh/docs/faq/perguntas-frequentes — CrossFly documentation. Full docs as one file: https://crossfly.dev/llms-full.txt

# FAQ — 常见问题

用一两句话回答，并始终附上来源链接。要**学习**，请查看
[`learn/`](/docs/learn)；要**修复错误**，请查看 [`troubleshooting/`](/docs/troubleshooting)。

## 概述
**CrossFly 是什么？** 一个基于 **Java、构建在 libGDX/OpenGL 之上**的 UI 框架——一切都通过 GPU 绘制，不使用原生
控件，因此在所有平台上外观完全一致。（第 1 章）

**我需要懂 libGDX 吗？** 日常使用不需要——你只跟 `Window`/`Component` 打交道。
（第 4 章）

## 引导启动与生命周期
**应用是如何启动的？** `Main` **通过反射**（借助*类名*）实例化 `MainWindow`。
（第 4 章）

**我的 `MainWindow` 加载不出来。** 它必须**继承 `Window`**，并具有**公共无参构造函数**。
（[项目结构剖析](/docs/get-started/project-structure)）

**我应该在哪里搭建 UI？** 在 **`onShow()`** 中（并调用 `super.onShow()`），绝不要在构造函数里。
（第 7 章）

## 线程与渲染
**我可以在其他线程操作 UI 吗？** **不可以**——用 `Component.onUI(r)` /
`Main.runOnPaintThread(r)` 回到主线程。（[paint 线程](/docs/concepts/the-paint-thread)）

**我改了某些东西但界面不刷新。** 渲染是**按需**进行的：调用 `Component.repaint()`（如果改变了尺寸/位置，还要
调用 `setValidLayout(false)`）。（第 4 章 §4.6）

**长耗时操作如何不卡界面？** 在一个 `Thread` 中运行，然后用 `onUI` 回到主线程。
（[后台工作](/docs/data-and-services/background-work)）

## 布局
**`add()` 里的数字是什么意思？** `LAY_FILL = -1f` 填满剩余空间；`LAY_AUTO = 0f` = 内容大小；
`>0` = **容器的比例**（不是像素）。（第 12 章）

**内边距和外边距？** `ingap`（内部）和 `outgap`（外部），在样式中设置。
（[样式化组件](/docs/ui/theming/styling-components)）

**响应式 UI？** 使用 `Relative` + `LAY_FILL`/`LAY_AUTO`，绝不用像素。
（[响应式设计](/docs/best-practices/responsividade)）

**`GridLayout`？** 先传**所有宽度，再传所有组件**：`add(w0,w1,…,c0,c1,…)`。
（[GridLayout](/docs/ui/layouts/grid-layout)）

## 导航
**如何在屏幕之间导航？** `novaWindow.show()` = 入栈，`hide()` = 出栈（这是一个 **`Window` 栈**）。
（[导航](/docs/ui/navigation/navigate-between-screens)）

**如何向另一个屏幕传递数据？** 通过目标 `Window` 的**构造函数**——没有命名路由。

**如何接收返回结果？** pickers 用 `picker.show(onAnswer)`；普通屏幕通过构造函数传入回调；
`Alert` 通过 `buttonAction` 响应。（[返回值](/docs/ui/navigation/returning-results)）

## 样式、主题与颜色
**切换浅色/深色？** `Styles.setDarkMode(true/false)` / `toggleDarkMode()`——会自动重新装饰一切。
（[浅色/深色模式](/docs/ui/theming/dark-mode)）

**改变 Material/iOS 的“外观”？** `Skin.set(new MaterialSkin()|new IOSSkin()|new FlutterSkin())`。
（[Skins](/docs/ui/theming/skins)）

**定义颜色？** 从一个种子色生成一个 `ColorScheme`。
（[配色方案](/docs/ui/theming/color-schemes)）

**我的颜色变得看不见了。** 它是 `int` 类型的 ARGB `0xAARRGGBB`——alpha 不带 `FF` 就会消失。用 `0xFF…`。
（第 11 章）

## 数据与持久化
**保存简单的偏好设置？** **不再有内置的 prefs**（`Settings.appSettings` 已移除）——
请使用 SQLite 或 `Device.homeFolder` 中的文件。（[文件与偏好设置](/docs/data-and-services/files-and-preferences)）

**使用数据库？** `dev.crossfly.sqlite`（`SqliteDb`/`SqliteStmt`/`SqliteCursor`），带 SQLite3MC 加密，
在 paint 线程之外运行。（[使用 SQLite 持久化](/docs/data-and-services/storage-sqlite)）

**有现成的 HTTP/同步客户端吗？** **没有**——用 `java.net`/OkHttp；JSON 用 Jackson。
（[网络与 HTTP](/docs/data-and-services/networking-http)）

**文本的 i18n？** 框架**不**做翻译——只按 locale 格式化日期/数字（`LocaleFormats`）；
翻译由你自己负责。（[国际化](/docs/best-practices/internacionalizacao)）

**大列表很慢？** 使用 `VirtualListView`/`PagedDataAdapter`。
（[性能与大列表](/docs/best-practices/performance-e-listas-grandes)）

## 平台与设备
**在哪些平台上运行？** Android、iOS、桌面（通过 LWJGL3 的 Windows/macOS/Linux）以及 Web（TeaVM）。
（[平台矩阵](/docs/platforms/overview)）

**相机/GPS/蓝牙/生物识别？** `dev.crossfly.device` 包；蓝牙是 **BLE/GATT 异步**方式。
（第 24 章）

**热敏打印机？** **支持已移除**——直接通过 BLE/GATT 通信。
（[Bluetooth BLE](/docs/data-and-services/device-bluetooth-ble)）

**UI 在旧设备上卡顿？** 检查 `Screen.slowGPU` 并减少阴影/渐变/玻璃效果。
（第 8 章）

**自动测试 UI？** `dev.crossfly.test` 框架（`TestCase` + 截图比对）。
（[测试](/docs/best-practices/testes)）

**Javadoc 与实际行为矛盾？** 请以**代码和本文档**为准。
（[参考文档如何组织](/docs/reference/overview)）

## 另请参阅
- 权威来源：第 34 章 — FAQ · [`troubleshooting/`](/docs/troubleshooting) · [`reference/`](/docs/reference)