FineUI

Classes

Accordion

AccordionPane

Base

Button

ButtonGroup

Calendar

CheckBox

CheckBoxList

Component

Container

DataList

DatePicker

DropDownBox

DropDownList

Field

FileUpload

Form

Grid

GridColumn

GroupPanel

Hidden

HtmlEditor

HyperLink

Image

Label

LinkButton

Menu

MenuCheckBox

MenuItem

MenuItemBase

MenuSeparator

MessageBox

NumberBox

PagingToolbar

Panel

PanelBase

RadioButton

RadioButtonList

Tab

TabStrip

TextArea

TextBox

TimePicker

Tool

Toolbar

ToolbarFill

ToolbarItemBase

ToolbarSeparator

ToolbarText

Tree

TriggerBox

ViewPort

Window

Members

(static) KEY

Description:

• 键盘按键代码

Methods

(static) addCSS(id, content, isCSSFile)

Description:

• 向页面添加CSS内容或者引用CSS文件

Parameters:

(static) addCommas(string) → {string}

Description:

• 添加千分位分隔符

Parameters:

Returns:

Type

string

(static) addDotSeparator(string, dotSeparator, commaSeparator) → {string}

Description:

• 添加小数分隔符

Parameters:

Returns:

Type

string

(static) addJS(id, content, isJSFile)

Description:

• 向页面添加JS内容或者引用JS文件

Parameters:

(static) addMainTab(tabstripInstance, options)

Description:

• 添加选项卡

Parameters:

(static) addMainTabByHref(tabstripInstance, treeInstance, href, activedopt, moveToEndopt)

Description:

• 添加选项卡（在树中查找拥有href的树节点）

Parameters:

(static) alert(options)

Description:

• 弹出提示对话框

Parameters:

(static) beforeAjaxError(callback)

Description:

• 注册 AJAX 回发失败回调函数。返回 false 则不执行默认错误提示。

  回调参数为 data、textStatus、xhr。data 是错误响应原文，网络错误与超时时为空字符串； textStatus 为 error、timeout 或 parsererror。xhr 与成功钩子同形态，无法获取 HTTP 状态时 status 为 0。 错误正文可能是 HTML、JSON 或空文本，页面应按自己的错误协议处理。

Example

自定义错误提示框

FineUI.beforeAjaxError(function (data, textStatus, xhr) {
	FineUI.alert('服务器返回错误！');
	return false;
});

Parameters:

(static) beforeAjaxSuccess(callback)

Description:

• 注册 AJAX 回发成功回调函数。每次成功回发在应用响应前调用一次；返回 false 阻止整份响应应用。

  回调参数为 data、textStatus、xhr。Core 三种模式与 Java 的 data 为原始 JSON 文本，Pro 为响应脚本； 检查 JSON 响应时可自行 JSON.parse(data)。xhr 是兼容对象，提供 status、statusText、responseText 和响应头读取方法； responseText 保留传输正文，需要查看完整原文时可读取它。 textStatus 为 success。Pro、Core、Java 的普通首屏加载均不触发此钩子；它只处理 FineUI AJAX 回发。

Examples

Pro 页面跳转前弹出系统确认对话框

FineUI.beforeAjaxSuccess(function (data, textStatus, xhr) {
	// 通过返回的字符串，判断是否即将执行页面跳转
	if (data.indexOf('window.location.href=') === 0) {
		if (!window.confirm('是否执行页面跳转？')) {
			return false; // 继续留在当前页面
		}
	}
});

Core / Java 在严格 CSP 下异步确认跳转

FineUI.beforeAjaxSuccess(function (data, textStatus, xhr) {
    // 典型响应：{"commands":[{"type":"page.redirect","url":"/"}]}
    // find 在 commands 数组中找出跳转命令。
    var commands = JSON.parse(data).commands || [];
    var redirect = commands.find(function (command) {
        return command.type === 'page.redirect';
    });
    if (redirect) {
        var url = redirect.url;
        FineUI.confirm({
            message: '是否执行页面跳转？',
            ok: function () {
                window.location.assign(url);
            }
        });
        return false;
    }
});

Parameters:

(static) confirm(options)

Description:

• 弹出确认对话框

Parameters:

(static) cookie(key, value, options)

Description:

• 新增或者修改Cookie

Parameters:

(static) customEvent(eventName, eventArgumentsopt)

Description:

• 触发页面级自定义业务事件，由后台 Page_CustomEvent 接收

  适用于 FineUI.Pro、FineUI.Core RazorForms 和 FineUI.Java；纯 JavaScript 构建及 Core MVC / RazorPages 不使用这个入口。 只需事件名和业务参数时使用本函数；需要加载提示、临时禁用、完成回调等请求选项时，使用 FineUI.doPostBack。

  参数与后台读取

  事件名标识要执行的业务操作。多个相关字段放在一个普通对象中，集合直接使用数组；框架负责 JSON 序列化和 URL 编码， 不要自行 JSON.stringify、encodeURIComponent 或拼接“事件名$参数”。字符串中的 $、+、%、中文和换行会完整保留，0 和 false 也会作为明确参数发送。

  后台	事件名	业务参数
  C#（Pro / Core RazorForms）	e.EventName	字符串：e.EventArguments；对象：e.EventArgumentsAsJObject；数组：e.EventArgumentsAsJArray
  Java	e.getEventName()	e.getArgument() 取得字符串；对象和数组取得 JSON 文本后，使用应用自己的 JSON 工具解析

  表单输入和当前控件状态会自动随回发提交，无需在第二个参数中重复复制。只有客户端临时计算等附加数据才需要显式传递。 自定义事件不会自动验证表单，需要时先调用 F.validateForm；普通标量在后台按字符串读取，再按业务类型转换。

  Pro 旧写法中第二个布尔参数曾表示是否验证表单；以事件名为首参的新写法中，布尔值只表示业务参数。 业务代码不要借 eventTarget 或手工拼接内置事件格式来调用普通控件事件。

  相关示例与文档

  • Core 自定义业务事件
  • F.customEvent 开发指南、内置控件事件与页面自定义事件的边界

Examples

不带参数：后台直接读取当前控件状态

F.customEvent('Refresh');

字符串参数：特殊字符无需自行编码

F.customEvent('SelectCustomer', '客户$105+杭州');

对象参数：一次发送多个相关字段

F.customEvent('DeleteRows', {
    rowIDs: ['102', '103'],
    source: 'Grid1'
});

数组参数：集合可以直接发送

F.customEvent('DeleteRows', ['102', '103']);

数字和布尔值：0 与 false 都会保留

F.customEvent('SetQuantity', 0);
F.customEvent('SetEnabled', false);

需要表单验证时先验证；返回 false 避免继续执行按钮默认动作（Core RazorForms / Java）

function onSaveClick(event) {
    if (!F.validateForm('Form1', { target: '_top' })) {
        return false;
    }
    F.customEvent('Save');
    return false;
}

Parameters:

(static) doPostBack(options)

Description:

• 发起回发请求，可设置业务参数、加载提示、临时禁用控件和单次回调

  只发送事件名和业务参数时，优先使用 FineUI.customEvent；需要完整请求选项时使用本函数。 页面级自定义事件由后台 Page_CustomEvent 接收，普通控件事件仍使用标签或服务端代码声明。

  产品与开发模式

  产品 / 模式	请求入口与选项	默认控件响应
  FineUI.Pro	向当前 WebForms 页面发送 eventName / eventArgument；可用 enableAjax 切换整页提交。不支持 url、fields、params。	响应脚本
  FineUI.Core RazorForms	页面事件不填 url，提交到当前完整网址并保留查询参数；控件状态和文件自动收集，可用 params 增加命名字段。	JSON
  FineUI.Core MVC / RazorPages	必须提供 Action / Handler 的 url，用 fields 收集表单、params 增加参数；不使用 Page_CustomEvent。	JSON
  FineUI.Java	向当前页面发送 eventName / eventArgument，自动收集控件状态和文件。不支持 url、fields、params；eventTarget 非空时仅同步状态。	JSON

  纯 JavaScript 构建不提供本函数。以上模式的 AJAX 请求都支持加载提示、disableControl 和 complete / success / error。 普通提交与文件上传共用 fetch；有已选择且带文件名的有效文件时使用 FormData，无需隐藏 iframe。 Pro 设置 enableAjax: false 后使用整页提交，不执行这些 AJAX 回调。

  本函数用于 FineUI 控件回发，Core 三种模式始终处理控件 JSON 响应。独立业务 JSON 或文本接口直接使用原生 fetch 或 jQuery.ajax。 RazorForms 的控件交互必须经过本页事件，不能用另一个 MVC / RazorPages UI 接口修改本页控件。

  回调顺序与响应处理

  1. 收到响应后先调用 complete，成功和失败都会调用。
  2. 成功时依次调用 success、F.beforeAjaxSuccess，再应用响应；失败时依次调用 error、F.beforeAjaxError，再显示默认错误提示。
  3. 框架负责恢复临时禁用状态、清理加载提示；回调中断不会跳过清理。

  上述回调严格返回 false 时，停止该分支的后续处理。complete 和 success 均早于控件更新，适合收起动画或检查响应， 不能用来读取更新后的控件。需要在响应更新后运行代码时，由后台追加具名客户端函数调用。 回调按同步函数执行，返回的 Promise 不会被等待；不要依靠 async 回调延后响应应用。

  相关示例与文档

  • Core 自定义回发、表单自定义加载动画
  • Java 表单自定义加载动画
  • F.doPostBack 开发指南、Java 服务端事件映射

Examples

页面级事件：验证表单、显示局部动画，请求结束后收起动画（Core RazorForms / Java）

function onSubmitClick(event) {
    var form = F('Form1');
    if (!F.validateForm('Form1', { target: '_top' })) {
        return false;
    }

    form.showLoading();
    F.doPostBack({
        eventName: 'Form1_Submit',
        disableControl: 'btnSubmit',
        enableAjaxLoading: false,
        complete: function (data, textStatus, xhr) {
            // 无论成功、错误还是超时，都要收起本次表单动画。
            form.hideLoading();
        }
    });
    return false;
}

Core RazorForms：附加命名字段，供后台 [BindProperty] 属性 ReportType 接收

F.doPostBack({
    eventName: 'GenerateReport',
    params: {
        ReportType: 'monthly'
    }
});

Core MVC / RazorPages：收集表单并向明确的 Action / Handler 发送请求

F.doPostBack({
    url: '/Orders/Save',
    fields: 'Form1',
    params: {
        source: 'toolbar'
    }
});
// RazorPages 可将 url 换成 '/Orders/Edit?handler=Save'。
// 接口返回 FineUI JSON 控件响应，由框架更新页面。

单次错误处理：接管 403 提示，其余错误继续使用默认处理

F.doPostBack({
    eventName: 'Save',
    error: function (data, textStatus, xhr) {
        if (xhr.status === 403) {
            F.alert('当前账号无权保存此记录。');
            return false;
        }
    }
});

Parameters:

(static) endsWith(value, source) → {boolean}

Description:

• 判断一个字符串是否以某个字符串结束

Parameters:

Returns:

Type

boolean

(static) formatDate(value, format) → {Date}

Description:

• 将日期对象转换为字符串

Example

日期格式规则请参考：FineUI.parseDate

Parameters:

Returns:

Type

Date

(static) formatNumber(number, format, trimZeroopt) → {string}

Description:

• 将数字格式化为字符串

Example

// 标准格式（小数位固定，不足补零）
FineUI.formatNumber(12345.6789, 'N2');    // "12,345.68"
FineUI.formatNumber(12345.6789, 'F2');    // "12345.68"
FineUI.formatNumber(0.1234, 'P2');        // "12.34%"
FineUI.formatNumber(12345.6789, 'E2');    // "1.23E+4"
FineUI.formatNumber(123, 'D5');           // "00123"

// 尾零省略（第三个参数传入 true）
FineUI.formatNumber(8500,    'N2', true);   // "8,500"    （原本 "8,500.00"，尾零省略）
FineUI.formatNumber(8500.1,  'N2', true);   // "8,500.1"  （原本 "8,500.10"，尾零省略）
FineUI.formatNumber(8500.75, 'N2', true);   // "8,500.75" （无尾零，保持不变）
FineUI.formatNumber(5,       'F2', true);   // "5"        （原本 "5.00"，尾零省略）
FineUI.formatNumber(0.5,     'P2', true);   // "50%"      （原本 "50.00%"，尾零省略）
FineUI.formatNumber(0.123,   'P2', true);   // "12.3%"    （原本 "12.30%"，尾零省略）
FineUI.formatNumber(10000,   'E2', true);   // "1E+4"     （原本 "1.00E+4"，尾零省略）
FineUI.formatNumber(15000,   'E2', true);   // "1.5E+4"   （原本 "1.50E+4"，尾零省略）

Parameters:

Returns:

Type

string

(static) formatString(form, …param)

Description:

• 格式化字符串

Parameters:

(static) getActiveWindow() → {FineUI.Window}

Description:

• 获取当前激活的窗体对象

Returns:

Type

FineUI.Window

(static) getHidden(fieldId) → {string}

Description:

• 获取隐藏字段的值（）

Parameters:

Returns:

Type

string

(static) getType(typeName) → {object}

Description:

• 获取类型字符串对应的类型（例如从字符串 'tabstrip' 获取类型 FineUI.TabStrip）

Parameters:

Returns:

Type

object

(static) hasHScrollbar(el) → {boolean}

Description:

• 是否存在水平滚动条

Parameters:

Returns:

Type

boolean

(static) hasVScrollbar(el) → {boolean}

Description:

• 是否存在垂直滚动条

Parameters:

Returns:

Type

boolean

(static) htmlDecode(value) → {string}

Description:

• HTML解码

Parameters:

Returns:

Type

string

(static) htmlEncode(value) → {string}

Description:

• HTML编码

Parameters:

Returns:

Type

string

(static) init(options)

Description:

• 初始化全局配置，应在创建控件之前调用。

Parameters:

(static) initTreeTabStrip(treeMenu, mainTabStrip, options)

Description:

• 初始化官网示例框架（左侧树与右侧选项卡面板交互）

Example

FineUI.initTreeTabStrip(FineUI.ui.Tree1, FineUI.ui.TabStrip1, {
    maxTabCount: 10,
    maxTabMessage: '请先关闭一些选项卡（最多允许打开 10 个）！'
});

Parameters:

(static) isARR(value) → {boolean}

Description:

• 测试对象是否为数组

Parameters:

Returns:

Type

boolean

(static) isBOO(value) → {boolean}

Description:

• 测试对象是否为布尔型

Parameters:

Returns:

Type

boolean

(static) isDAT(value) → {boolean}

Description:

• 测试对象是否为日期对象

Parameters:

Returns:

Type

boolean

(static) isELE(value) → {boolean}

Description:

• 测试对象是否为DOM节点元素

Parameters:

Returns:

Type

boolean

(static) isEMP(value) → {boolean}

Description:

• 测试对象是否为空（undefined, null 或者 空字符串）

Parameters:

Returns:

Type

boolean

(static) isEOBJ(value) → {boolean}

Description:

• 测试对象是否为空对象（不包含任何属性）

Parameters:

Returns:

Type

boolean

(static) isFUN(value) → {boolean}

Description:

• 测试对象是否为函数

Parameters:

Returns:

Type

boolean

(static) isNAN(value) → {boolean}

Description:

• 测试对象是否为NaN

Parameters:

Returns:

Type

boolean

(static) isNUM(value) → {boolean}

Description:

• 测试对象是否为数字

Parameters:

Returns:

Type

boolean

(static) isPOBJ(value) → {boolean}

Description:

• 测试对象是否为纯粹对象（通过 {} 或者 new Object 创建的对象）

Parameters:

Returns:

Type

boolean

(static) isSTR(value) → {boolean}

Description:

• 测试对象是否为字符串

Parameters:

Returns:

Type

boolean

(static) isUND(value) → {boolean}

Description:

• 测试对象是否为undefined或者null

Parameters:

Returns:

Type

boolean

(static) noAnimation(fn)

Description:

• 回调函数中不进行动画操作

Parameters:

(static) noConflict()

Description:

• 释放window.F命名空间，以便其他脚本可以使用它

(static) noEvent(fn)

Description:

• 回调函数中不触发事件

Parameters:

(static) noLayout(fn)

Description:

• 回调函数中不进行布局操作

Parameters:

(static) noValidate(fn)

Description:

• 回调函数中不验证表单字段

Parameters:

(static) notify(options)

Description:

• 弹出通知对话框

Parameters:

(static) parseDate(value, format) → {Date}

Description:

• 将字符串转换为日期对象

Examples

// 基本日期解析
FineUI.parseDate('2023-12-25', 'yyyy-MM-dd');        
// 返回: 2023年12月25日

FineUI.parseDate('25/12/2023', 'dd/MM/yyyy');        
// 返回: 2023年12月25日

FineUI.parseDate('Dec 25, 2023', 'MMM dd, yyyy');    
// 返回: 2023年12月25日

// 日期时间解析
FineUI.parseDate('2023-12-25 14:30:45', 'yyyy-MM-dd HH:mm:ss');
// 返回: 2023年12月25日 14:30:45

FineUI.parseDate('12/25/2023 02:30', 'MM/dd/yyyy hh:mm');
// 返回: 2023年12月25日 14:30:00

FineUI.parseDate('December 25, 2023', 'MMMM dd, yyyy');
// 返回: 2023年12月25日

// 短格式和缩写格式
FineUI.parseDate('23-12-25', 'yy-M-d');              
// 返回: 2023年12月25日

FineUI.parseDate('12/25/23', 'M/d/yy');              
// 返回: 2023年12月25日

// 时间格式解析
FineUI.parseDate('14:30', 'HH:mm');                  
// 返回: 今天14:30:00

FineUI.parseDate('14:30:45', 'H:m:s');               
// 返回: 今天14:30:45

Parameters:

Returns:

Type

Date

(static) parseJSON(value) → {Object}

Description:

• 将JSON字符串转换为JavaScript对象

Parameters:

Returns:

Type

Object

(static) progressHtml(value, options)

Description:

• 生成进度条HTML片段

Parameters:

(static) prompt(options)

Description:

• 弹出输入对话框

Parameters:

(static) queryString(name, urlopt) → {string}

Description:

• 获取URL中的参数值

Parameters:

Returns:

Type

string

(static) rateEvents(container, callback)

Description:

• 注册评分事件

Parameters:

(static) rateHtml(value, options)

Description:

• 生成评分HTML片段

Parameters:

(static) rawHtml(value, …param) → {object}

Description:

• 声明一段“可信 HTML”。控件的文本类属性（如 text、title、tooltip 等）默认会做 HTML 转义（防 XSS）， 当你确信某段 HTML 可信、需要原样输出（不转义）时，用它包裹后赋给对应属性即可。 详见文档：安全策略（用 RawHtml / F.rawHtml 安全输出 HTML）

Example

// 用法1：创建控件时，把带 HTML 的文本声明为可信，原样输出（不转义）
F.create({ type: 'Button', text: F.rawHtml('<i class="f-icon f-iconfont f-iconfont-add"></i> 新增') });

// 用法2：运行时调用控件方法更新文本，同样用 F.rawHtml 包裹
F.ui.label1.setText(F.rawHtml('<b>已保存</b>'));

// 用法3：菜单项、面板标题等文本类属性通用
F.create({ type: 'MenuItem', text: F.rawHtml('<span class="hot">热门</span> 推荐') });

// 特例：表格列渲染函数 renderer 的返回值本就原样输出（不转义），故【无需】用 F.rawHtml 包裹，
// 直接返回 HTML 字符串即可；因为不转义，其中若含用户数据务必先自行 F.htmlEncode
F.create({ type: 'Grid', columns: [{
    field: 'status',
    renderer: function (value) { return '<span class="tag">' + F.htmlEncode(value) + '</span>'; }
}] });

// 用法5：模板 + 用户数据——先对用户数据 HTML 编码，再用 {0}、{1} 占位放进可信 HTML（防 XSS）
F.rawHtml('<b>{0}</b>：{1}', F.htmlEncode(userName), F.htmlEncode(userInput));

// 反例：不要把用户输入直接包成可信 HTML（会导致 XSS）
// F.create({ type: 'Label', text: F.rawHtml(userInput) });  // ❌ 危险

Parameters:

Returns:

Type

object

(static) ready(callback)

Description:

• 注册页面渲染完毕回调函数

Parameters:

(static) removeCommas(string) → {string}

Description:

• 移除千分位分隔符

Parameters:

Returns:

Type

string

(static) removeCookie(key, options)

Description:

• 删除Cookie

Parameters:

(static) removeDotSeparator(string, dotSeparator, commaSeparator) → {string}

Description:

• 移除小数分隔符

Parameters:

Returns:

Type

string

(static) removeHidden(fieldId)

Description:

• 删除隐藏字段（）

Parameters:

(static) reset(containerId)

Description:

• 重置容器内的全部表单字段

Parameters:

(static) resolveUrl(url) → {string}

Description:

• 将「相对 Web 根/子应用根」的路径解析为客户端可用的完整 URL。 内部基于 FineUI.baseUrl 拼接，调用者无需关心 baseUrl 是否以 / 结尾，也无需关心页面部署在站点根还是子目录。 绝对 URL（http(s):// 、协议相对 // 、data:、blob: 等）原样返回；否则去掉前导的 ~ 和 / 后拼到 baseUrl 之后。

Parameters:

Returns:

Type

string

(static) setHidden(fieldId, fieldValue)

Description:

• 设置隐藏字段的值（）

Parameters:

(static) smartLayout(fn)

Description:

• 回调函数执行完毕后再进行布局操作

Parameters:

(static) startsWith(value, source) → {boolean}

Description:

• 判断一个字符串是否以某个字符串开头

Parameters:

Returns:

Type

boolean

(static) toJSON(value) → {string}

Description:

• 将JavaScript对象转换为JSON字符串

Parameters:

Returns:

Type

string

(static) ui(options) → {FineUI.Component}

Description:

• 创建控件实例

Parameters:

Returns:

Type

FineUI.Component

(static) urlDecode(url) → {string}

Description:

• URL解码

Parameters:

Returns:

Type

string

(static) urlEncode(url) → {string}

Description:

• URL编码

Parameters:

Returns:

Type

string

(static) validateForm(formId, optionsopt) → {boolean}

Description:

• 验证单个表单——FineUI.validateForms 的单表单形式，参数与返回值完全一致。

Example

验证一个表单：

if (FineUI.validateForm('form1')) {
	FineUI.alert('表单验证通过');
}

Parameters:

Returns:

Type

boolean

(static) validateForms(formIds, optionsopt) → {boolean}

Description:

• 验证多个表单，验证失败时弹出提示对话框并把焦点定位到第一个非法字段。

  大多数场景不需要手工调用：按钮、工具图标、菜单项、链接按钮都有 validateForm / validateForms 属性，点击时会自动验证、不通过就不再执行后续逻辑 （见 FineUI.Button）。本方法用于没有控件可挂的场景，例如自定义回发前的手工校验。

Examples

验证两个表单，失败时用简洁样式的提示框：

if (FineUI.validateForms(['form1', 'form2'], { messageBoxPlain: true })) {
	// 全部通过后才做的事
}

提示框弹到顶层窗口（本页处于 IFrame 中时常用）：

FineUI.validateForms(['form1'], { target: '_top' });

只想拿验证结果、不弹提示框：

if (!FineUI.validateForms(['form1'], { messageBox: false })) {
	// 自行处理
}

Parameters:

Returns:

Type

boolean

(static) windowResize(fn)

Description:

• 注册页面大小改变事件（延迟 500 毫秒触发）

Parameters: