fineui-foundation

FineUI 地基技能（Foundation）

搭建任何 FineUI 页面的通用基础。先用本技能判定“哪种写法”、搭好页面骨架、掌握可信 HTML；再进具体组件技能（如 fineui-grid）。

术语：4 部署栈（Core 含 3 种开发模式）

部署栈	开发模式	前台写法
F.js	—（纯 JavaScript）	F.create({ type:'Xxx', ... })
Pro	WebForms	<f:Xxx runat="server">
Core	MVC（经典 MVC）	Fluent API Html.F().Xxx()...
Core	RazorForms（Core 推荐）	TagHelper <f:Xxx>（PascalCase）
Core	RazorPages	TagHelper <f:Xxx>（PascalCase）
Java	Spring Boot	Thymeleaf 方言标签 <f:xxx>（kebab-case）

Fluent API / TagHelper 是前台写法、不是模式名；Core 模式说 MVC / RazorForms / RazorPages。RazorForms 与 RazorPages 共用 TagHelper 标签，但数据初始化/事件不同。 FineUI.Java 是 Core-RazorForms 的「孪生栈」：同样是「标签式有状态服务端组件」，但用 Spring Boot + Thymeleaf 方言，标签/属性全 kebab-case，页面类用 Java。客户端 F.js 运行时四栈完全相同（F.ui.Grid1.xxx()、渲染函数、监听器 JS 一字不差）。详见 references/stacks.md。

何时使用（When to Use）

• 判定一个 FineUI 项目属于哪种写法，避免生成错端代码
• 从零搭一个页面（页面骨架、PageManager、Region/ViewPort 布局）
• 用 F.create / Fluent / TagHelper 创建组件
• 让文本按 HTML 原样输出（可信 HTML / RawHtml）
• 理解属性命名、全局配置项

开始前（Before You Start）—— 先判定写法

判定线索：纯前端 .html + F.create → F.js；.aspx + <f:Xxx runat="server"> → Pro；Controllers/ + Views/*/Index.cshtml 用 Html.F() → Core-MVC；Pages/*.cshtml + <f:Xxx> 标签 → Core-RazorForms（有 .designer.cs）或 Core-RazorPages（无 designer）；.html 里 <html xmlns:f="http://fineui.com/java"> + <f:xxx> 小写标签、pom.xml/mvnw + 页面类带 @FineUIPage → Java（Spring Boot）。

各写法速览（创建一个组件）

// F.js
F.create({ type: 'Panel', renderTo: '#wrap', id: 'Panel1', title: '面板', bodyPadding: 10 });

<%-- Pro（WebForms）--%>
<f:Panel ID="Panel1" runat="server" Title="面板" BodyPadding="10px"></f:Panel>

// Core-MVC（Fluent API）
@(Html.F().Panel().ID("Panel1").Title("面板").BodyPadding(10))

<!-- Core-TagHelper（RazorForms / RazorPages 相同）-->
<f:Panel ID="Panel1" Title="面板" BodyPadding="10"></f:Panel>

<!-- FineUI.Java（Thymeleaf 方言：标签 + 属性全 kebab-case）-->
<f:panel id="Panel1" title="面板" body-padding="10"></f:panel>

参考文档（Documentation Reference Files）

文件	何时读
references/stacks.md	各写法差异总表、判定线索、命名约定、全局配置
references/page-scaffold.md	最小页面骨架、PageManager 位置、Region/ViewPort 布局、共享 _Layout
references/events-postback.md	ClickHandler、服务端事件、Core RazorForms 同步／异步事件命名、F.customEvent、Pro 两个兼容开关与 Grid 行命令
references/rawhtml.md	可信 HTML：F.rawHtml / XxxRawHtml / new RawHtml(...)

相关技能（Related Skills）

• fineui-grid：数据表格（最复杂组件，各写法完整对照（含 Java））
• fineui-form / fineui-datalist / fineui-tree / fineui-window / fineui-panel / fineui-layout / fineui-button / fineui-theming：各组件与主题
• fineui-upgrade：版本升级（识别破坏性变更）

约束与规则（Constraints & Rules）

1. 先定写法、不混用：一个页面只用一种写法。F.js 属性 camelCase，C# 三模式 PascalCase，Java 标签/属性全 kebab-case（枚举/图标等属性「值」仍保持 PascalCase，如 text-mode="Password"）；Fluent API（MVC）与 TagHelper（RazorForms/RazorPages）不要混写。
2. PageManager 位置：Pro 写在 aspx 页面内（<f:PageManager>）；Core 三模式统一放在共享 _Layout.cshtml 的 @F.PageManager；Java 放在共享 shared/layout.html（<f:styles>/<f:scripts> 槽）+ 可选实现 FineUIPageManagerInitializer bean 做页面级配置。三者业务页都不写 PageManager。
3. 文本默认 HTML 编码（v15.2）：要原样输出 HTML 必须声明可信 HTML（F.rawHtml / XxxRawHtml / new RawHtml(...)），来自用户输入/数据库的内容不要声明。详见 references/rawhtml.md。
4. 绝不编造 API：不确定的属性/方法去查官网 API 或 F/doc/ 的 JSDoc。不同写法名称不同，别硬套（如 Grid 列 F.js text/field ↔ C# HeaderText/DataField ↔ Java header-text/data-field）。
5. 各栈启用标签：Core 启用 TagHelper 需 _ViewImports.cshtml 的 @addTagHelper *, FineUI.Core，CSS/JS 用 @F.RenderCss() / @F.RenderScript()；Java 页面根标签声明方言命名空间 <html xmlns:f="http://fineui.com/java">，CSS/JS 由母版里的 <f:styles> / <f:scripts> 输出。
6. 消息框与回发返回值必须按模式区分：F.js 用 F.alert({ message: ... }) / showNotify(...)；Pro 与 Core-RazorForms 的同步控件事件返回 void、直接操作控件，不写 OnPostXxx、不返回 IActionResult、不调用 UIHelper.Result()。按钮点击可写 void Xxx_Click(object sender, EventArgs e)；分页、排序、行命令等事件的第二参数必须使用各自的专用 EventArgs。RazorForms 后台类必须是 partial 并继承项目现有的 RazorForms 页面基类（官方示例为 XxxModel : BaseModel，而 BaseModel 本身可继承 PageModel）；不要改成非 partial 的 RazorPages 页面并使用 OnGet / OnPostXxx。只有 Core-MVC 的 action 和 Core-RazorPages 的 OnPostXxx 返回 IActionResult，结尾 return UIHelper.Result();；Java 用消息类 Alert.show(...)、Confirm.show(...) 或 new Notify().show()，同步处理器返回 void，事件参数同样按事件类型选择。
7. 客户端动作只写具名函数：Pro/Core 用 ClickHandler="onXxxClick"，Java 用 click-handler="onXxxClick"，函数首参为 event。不要在新代码中使用 OnClientClick / on-client-click 或把脚本塞进 Handler；详见 references/events-postback.md。
8. Core RazorForms 事件名默认省略 Async：标签推荐写 OnClick="btnSave_Click"，后台可用同步的 void btnSave_Click(...) 或异步的 async Task btnSave_ClickAsync(...)，切换实现时标签不变；两者并存时优先异步方法，异步事件不要使用 async void。完整 Async 名称只作兼容说明，详见 references/events-postback.md；此命名规则不套用到 Pro、Java 或 Core 的其他模式。

官方资源（Official Resources）

• 在线 API：JS https://fineui.com/js/api/ · Pro https://fineui.com/pro/api/ · Core https://fineui.com/core/api/
• 官网与示例：https://www.fineui.com/
• FineUI.Java：控件属性语义与 Core 一致（属性名 kebab-case、值同 Core），客户端 F.js API 与 JS 端完全相同；查属性时参考 Core API 再按命名约定转 kebab-case。