# Flor Website

## 花 · 框架

- [唠叨之书](/website/zh/guide/book-index.md)
- [](/website/zh/guide/startup.md)
- [术语表](/website/zh/guide/glossary.md): 这一页用于统一 Flor 文档里的称呼。遇到中英文或 API 命名不完全一致的地方，以这里为准。
- [AI](/website/zh/guide/ai.md): Flor 的 框架 DSL 与 React 系的函数式 UI 表达有异曲同工之处。 这意味着，在使用 AI 辅助编写 Flor 界面时，AI 并不一定需要提前接受过针对 Flor 的专门训练。由于大量大模型已经在 React、JSX、函数式组件、声明式 UI 等内容上形成了较强的理解能力，Flor 的 DSL 可以在一定程度上复用这种表达习惯。 换句话说，当你向 AI 描述一个界面结构时，它可以借助自己对 React 式 UI 组织方式的理解，较快地迁移到 Flor 的 DSL 上，帮助你完成界面的快速搭建、结构调整和样式组织。具体的控件封装写法见 框架 DSL。 这也是 Flor “既要，又要，还要”理念的又一次体现： 既要传统 GUI 框架中控件式开发的清晰结构， 也要现代前端声明式 UI 的表达效率， 还要尽可能利用 AI 已经熟悉的函数式 UI 思维，让布局设计变得更容易被生成、修改和迭代。 当然，说句悄悄话：Flor 最开始的设计并不是刻意为了贴近 AI 使用场景而生的。它只是沿着 DSL API 的设计自然演化，最后才发现，这套设计天然适合被 AI 理解和生成。 因此，Flor 的文档站点也选择了带有 AI 支持能力的文档框架来构建。除了面向开发者阅读的普通文档外，本站还提供了面向大语言模型的文档入口，方便你在使用 AI 辅助开发时，将更适合模型阅读的资料提供给它。 如果你想让 AI 帮你编写 Flor 界面、解释 Flor 的 DSL，或者根据描述快速生成一个布局，可以优先使用下面提供的 LLM 文档链接。
- [](/website/zh/guide/use/init.md)
- [](/website/zh/guide/use/window.md)
- [Flor Signal 响应式系统](/website/zh/guide/use/signal.md): Flor 框架内置了一个轻量级的响应式信号系统。该信号系统受 Floem 启发，参考了其 API 设计，但由我们完全独立实现。与 Floem 不同的是，因为 Flor 的设计目标，Flor Signal 天生支持跨线程使用，信号可以在多线程环境下安全地读写和传递。 本文主要说明如何使用 Signal。完整函数签名和 trait 列表见 Signal API 参考。
- [外置事件](/website/zh/guide/use/handler.md): 外置事件是给已经存在的控件追加事件逻辑的方式。你不需要为了处理一次点击、一次鼠标移动、一个快捷键，就去实现一个新的 View。把控件创建出来以后，接着链式调用 on_* 方法，把闭包交给 Flor 就可以。 这些 on_* 方法来自 EventBuilder，使用前先导入它： 完整签名见 Handler API。这一页先按使用过程来学：从一次点击开始，再逐步用到鼠标位置、键盘、焦点、生命周期和拖放。
- [控件状态](/website/zh/guide/use/control-state.md): Flor 框架已经实现了完整的控件状态系统，用于管理控件在不同交互场景下的状态表现。
- [焦点 Builder](/website/zh/guide/use/builder/focus.md): 这一页只介绍用于配置焦点表的 builder 方法。焦点机制的整体说明见 焦点机制，运行时通过 ViewId 操控焦点的 API 见 ViewId。 实际公开的 trait 是：
- [事件 Builder](/website/zh/guide/use/builder/event.md): 事件 Builder 用来给控件挂外置事件处理函数。它适合应用侧代码：你不需要写一个新的控件类型，也不需要实现 View，直接在创建控件时链式绑定事件。 完整方法列表、handler 类型和派发状态见 Handler API。这一页只讲怎么用。
- [布局 Builder](/website/zh/guide/use/builder/layout.md): 布局 Builder 用来在创建控件时配置显示方式、尺寸、间距、定位、Flex/Grid 等布局属性。基本写法是在控件后调用 .layout(|layout| { ... })，在闭包里连续调用布局方法，最后返回修改后的 layout。
- [原子类支持](/website/zh/guide/use/builder/class.md): 原子类指 .class(...) builder 带来的能力。它适合在创建控件时用一串类名快速配置布局和样式。 使用 .class(...) 需要启用 class feature。具体类名语法见 class 语法解析基础，内置 layout class 清单见 layout class 语法。
- [样式 Builder](/website/zh/guide/use/builder/style.md): 样式 Builder 的入口是 .style(|style| { ... })。它用于手动编写控件样式的链式配置，适合你想直接调用控件提供的强类型样式方法，而不是把样式写成 class 字符串时使用。
- [禁用 Builder](/website/zh/guide/use/builder/disable.md): 禁用 Builder 用来把控件切到 ControlState::Disabled。它是应用侧配置控件状态的 builder，不是自定义控件作者需要在 View trait 里重写的方法。 当前公开接口是：
- [层级 Builder](/website/zh/guide/use/builder/z-index.md): 层级 Builder 用来给控件设置 z_index。它只影响同一个父控件下的兄弟节点排序，不是全局层叠上下文。
- [变换 Builder](/website/zh/guide/use/builder/transform.md): 变换 Builder 用来给控件设置声明式 Transform2D。它影响控件自身及其子控件的绘制和命中测试，但不改变 Taffy 布局计算出来的位置和尺寸。
- [Resolver Layer 机制](/website/zh/guide/use/resolver-layer.md): Resolver Layer 是 Flor 用来组织控件配置的机制。它让控件的布局和样式可以分段写、重复写、按需覆盖，而不是要求你一次性把所有配置拼成一整块。 在使用代码里，.class(...)、.layout(...)、.style(...) 都会使用这套 Layer 机制。每调用一次这些 builder，都可以理解成给控件追加一层配置。 Layer 的合并规则很简单： 也就是说，你可以把 class、layout、style 拆开多次写，也可以混在一起写。后面的调用不会把前面整层配置清空；它只会覆盖自己重新写过的属性。
- [框架 DSL](/website/zh/guide/use/framework-dsl.md): Flor 的界面代码可以当作一套普通 Rust DSL 来写：函数负责组合控件，参数负责传入属性、信号和 handler，返回值就是已经配置好的控件。 这和 JSX 的使用感受有相似之处：页面不是一大段字符串模板，而是一组可以拆分、复用、传参的控件函数。区别是 Flor 不需要额外的模板语言，组合本身就是 Rust 的函数调用和链式方法。 如果还不熟悉 .class(...)、.layout(...)、.style(...) 多次调用如何合并，先看 Resolver Layer 机制。
- [焦点机制](/website/zh/guide/use/focus.md): Flor 的焦点是显式机制。控件不会因为能点击、能显示文字、绑定了键盘事件，就自动进入焦点系统。一个控件只有进入焦点表，才会被 Tab 访问，才会成为控件级 on_key_* 的派发目标，也才会由焦点管理器触发 on_focus 和 on_blur。 先看一个最小例子： 没有 focus_index 的控件不会进入焦点表。它不会被 Tab 选中；点击它时，框架无法把焦点设置到这个控件；它的控件级 on_focus / on_blur 不会由焦点管理器触发；它的控件级 on_key_* 也不会因为“这个控件获得焦点”而触发。 具体的 builder 写法见 焦点 Builder。运行时通过 ViewId 操控焦点的 API 见 ViewId。
- [框架能力](/website/zh/guide/features/overview.md): 框架能力这一栏专门介绍 flor 的可选能力。它们大多通过 Cargo feature 开启，启用后会暴露对应的 API、事件 builder 或平台行为。 如果只是想查所有 feature 的名字，先看 快速了解。这一栏会把平台能力拆开讲清楚：启用后能做什么、入口在哪里、和哪些教程/API 有关。
- [剪贴板](/website/zh/guide/features/clipboard.md): clipboard feature 用来启用系统剪贴板读写能力。它适合实现复制、粘贴、导入导出临时文本等功能。
- [拖放](/website/zh/guide/features/drag-drop.md): drag-drop feature 用来启用系统拖放事件。启用后，控件可以通过事件 builder 接收拖入、悬停、离开和释放。
- [系统托盘](/website/zh/guide/features/tray.md): tray feature 用来启用系统托盘图标能力。启用后可以添加、更新、删除托盘图标，并接收托盘图标上的鼠标事件。
- [主题变化](/website/zh/guide/features/theme-change.md): theme-change feature 用来启用系统主题变化相关类型和事件 builder。它适合在系统从浅色模式切换到深色模式时，更新应用主题或重建相关样式。
- [显示器信息](/website/zh/guide/features/monitor.md): monitor feature 用来启用显示器查询能力。它适合做窗口初始定位、多屏适配、读取工作区大小、按显示器 DPI 调整自定义逻辑等。
- [高 DPI](/website/zh/guide/features/hi-dpi.md): hi-dpi feature 用来启用进程级 DPI 感知。它会让应用接收更准确的 DPI 信息，并让 Flor 在窗口 DPI 变化时更新渲染缩放和布局单位。
- [跨线程窗口创建](/website/zh/guide/features/cross-thread-window-creation.md): cross-thread-window-creation feature 允许在事件循环线程之外调用 WindowOption::open(...) 创建窗口。
- [ViewId](/website/zh/guide/control/view-id.md): ViewId 是控件在 Flor 运行时里的标识和操作句柄。控件树、布局状态、事件 handler、焦点表、滚动状态、鼠标捕获和渲染资源都通过它关联到同一个控件。 这一页面面向两类场景：在事件回调中操作当前控件，或在自定义控件实现里通过 self.view_id 访问运行时能力。只想配置焦点顺序时，优先看 焦点 Builder。
- [View Trait](/website/zh/guide/control/view-trait.md): View 是 Flor 的控件实现接口。一个具体控件通过它提供自己的 ViewId，并按需覆盖测量、绘制、命中测试、焦点、输入事件、tooltip、拖放和状态更新钩子。 应用侧组合界面时通常使用独立控件库（例如 flor_lys）提供的控件，再配合 builder 做配置。只有在编写新控件、封装底层绘制逻辑或实现复杂交互时，才需要直接实现 View。 控件作者应该把注意力放在 on_* 方法上。除了必须实现的 view_id()，以及临时调试用的 tag()，不要重写 call_*、bus_*、visual_rect() 这类非 on_* 派发方法；它们是框架内部调度层。
- [样式单位](/website/zh/guide/control/resolver/style-unit.md): Flor 的布局系统使用 Unit 和 Length 类型表示尺寸单位。所有单位在传递给布局引擎前都会转换为像素值。
- [Resolver 结构体](/website/zh/guide/control/resolver/resolver-struct.md): 这个页面不需要刻意学习，读过有个印象就够了。控件开发时直接使用 Resolver 派生宏 即可。 Resolver 是 Flor 框架内部的样式/布局解析器，用于管理状态变体、单位换算和计算缓存。控件作者通常不需要直接操作 Resolver，而是通过 Resolver 派生宏 自动生成实现。
- [Resolver 派生宏](/website/zh/guide/control/resolver/resolver-derive.md): #[derive(Resolver)] 是 Flor 提供的样式解析派生宏。它为样式枚举自动生成 Resolver 类型、链式方法、状态变体支持和响应式更新能力。 这个宏内置控件状态机制，主要用于控件的样式系统。它可以与 class 系统 配合使用，在 on_update_class 中解析类名并更新样式。 控件作者只需要定义样式枚举，派生宏会自动生成所有 Resolver 相关代码。
- [类名解析辅助函数](/website/zh/guide/control/resolver/class-resolve.md): flor::view::resolver::shared 提供类名解析的辅助函数，用于解析状态前缀、颜色、圆角、字重等常见样式类名。
- [从零开发一个 Switch 控件](/website/zh/guide/control/create-widget.md): 本章我们将从零开始，完整实现一个 Switch（开关）控件。通过这个过程，你会掌握控件开发的所有核心环节：定义样式枚举、实现 View trait、绘制、测量、支持原子类、响应鼠标事件。 Switch 是一个合适的学习案例：它有"开/关"两种状态，需要绘制轨道和滑块，需要响应点击，还能通过原子类定制颜色和尺寸。学完这一章，你就可以按照同样的模式开发自己的控件了。

## API

- [API 概览](/website/zh/api/index.md): 这里放置面向查询的 API 参考。 class 语法解析基础layout class 语法Signal APIView 转换 APIHandler API
- [class 语法解析基础](/website/zh/api/class-syntax.md): 本页是 .class(...) 字符串的通用解析规则。使用教程见 原子类支持，layout class 的完整清单见 layout class 语法。
- [layout class 语法](/website/zh/api/layout-class.md): 本页列出 Flor 内置 layout class 的当前支持范围。使用 .class(...) 的教程见 原子类支持，通用 class 字符串解析规则见 class 语法解析基础。 layout class 由 Flor 统一解析，对所有控件可用。Flex、Grid、Block 相关类受 feature 控制。
- [Signal API](/website/zh/api/signal.md): 本页用于查询 flor::signal 的主要公开 API。使用教程见 Signal 响应式系统。
- [View 转换 API](/website/zh/api/view.md): 本页用于查询 flor::view 中和控件身份、通用控件对象、子控件序列相关的公开 API。使用教程见 框架 DSL。
- [Handler API](/website/zh/api/handler.md): 本页用于查询 flor::view::handler 和 flor::view::builder::EventBuilder 的主要公开 API。使用教程见 外置事件。