Back to Details

netsuite-uif-spa-reference

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

NetSuite UIF Reference

NetSuite UIF 参考文档

Complete type definitions for 
@uif-js/core
and 
@uif-js/component
, the two packages that power NetSuite SPA (single-page application) user interfaces.
为支撑NetSuite SPA（单页应用）用户界面的两个包
@uif-js/core
和
@uif-js/component
提供完整的类型定义。

When to Use

适用场景

  • Building or modifying a UIF SPA component (JSX files)
  • Looking up the exact API for a UIF class (Date, ArrayDataSource, Router, etc.)
  • Checking available props/methods on UIF components (DataGrid, StackPanel, Button, etc.)
  • Debugging runtime errors from UIF framework code
  • Verifying enum values (for example, 
    Button.Hierarchy
    , 
    GapSize
    , 
    DataGrid.ColumnType
    )
  • Understanding UIF Date vs. Native Date behavior
  • 构建或修改UIF SPA组件（JSX文件）
  • 查询UIF类（Date、ArrayDataSource、Router等）的精确API
  • 查看UIF组件（DataGrid、StackPanel、Button等）的可用属性/方法
  • 调试UIF框架代码引发的运行时错误
  • 验证枚举值（例如
    Button.Hierarchy
    、
    GapSize
    、
    DataGrid.ColumnType
    ）
  • 了解UIF Date与原生Date的行为差异

Reference Data

参考数据

The type definitions are located in the 
references/
subdirectory.
FilePackageContents
references/core.d.ts
@uif-js/core
Core framework: Date, ArrayDataSource, Ajax, Router, useState, useEffect, Context, etc.
references/component.d.ts
@uif-js/component
UI components: DataGrid, StackPanel, Button, Text, Badge, Heading, Card, ContentPanel, Modal, etc.
类型定义位于
references/
子目录中。
文件包内容
references/core.d.ts
@uif-js/core
核心框架：Date、ArrayDataSource、Ajax、Router、useState、useEffect、Context等
references/component.d.ts
@uif-js/component
UI组件：DataGrid、StackPanel、Button、Text、Badge、Heading、Card、ContentPanel、Modal等

Lookup Instructions

查询说明

To find information about a specific class or component:
  1. Search by class name:
    Search for `class Date` in the local `references/` directory.
  2. Search by method name:
    Search for `lastOfMonth`, `firstOfMonth`, or `addDay` in `references/core.d.ts`.
  3. Search by enum:
    Search for `enum GapSize`, `enum Hierarchy`, or `enum Type` in `references/component.d.ts`.
  4. Read a section: Once you find the line number, open that part of the file to view the full definition.
要查找特定类或组件的信息：
  1. 按类名搜索：
    在本地`references/`目录中搜索`class Date`。
  2. 按方法名搜索：
    在`references/core.d.ts`中搜索`lastOfMonth`、`firstOfMonth`或`addDay`。
  3. 按枚举搜索：
    在`references/component.d.ts`中搜索`enum GapSize`、`enum Hierarchy`或`enum Type`。
  4. 查看章节：找到行号后，打开文件的对应部分查看完整定义。

Key Classes Quick Reference

关键类快速参考

@uif-js/core

@uif-js/core

ClassPurposeKey Members
Date
UIF date wrapper
.year
, 
.month
(0-indexed), 
.day
, 
.firstOfMonth()
, 
.lastOfMonth()
, 
.addDay()
, 
.addMonth()
, 
.stripTime()
, 
.toDate()
(→ native), 
Date.now()
, 
Date.today()
ArrayDataSource
Data provider for grids
ArrayDataSource<T>
– constructor takes 
T[]
Ajax
HTTP client
Ajax.post()
, 
Ajax.get()
, 
Ajax.DataType
, 
Ajax.ResponseType
Router
SPA routing
Router.Routes
, 
Router.Route
, 
Router.Hash
, 
Router.Path
useState
State hook
useState(initialValue)
→ 
[value, setter]
useEffect
Effect hook
useEffect(callback, deps)
useContext
Context hook
useContext(contextName: string)
– takes a string, for example, 
ContextType.ROUTER_LOCATION
Context
Context provider
Context.Provider
, 
Context.Consumer
ContextType
Context type string constants
ContextType.ROUTER_LOCATION
, 
ContextType.ROUTER_NAVIGATION
, 
ContextType.ROUTER_ROUTE
, 
ContextType.I18N
, 
ContextType.PREFERENCES
, 
ContextType.FOCUS_MANAGER
, 
ContextType.STORE
– full list: 31 values; search for 
ContextType
in 
core.d.ts
useCallback
Memoized callback
useCallback(fn, deps)
– prevents unnecessary re-renders
useMemo
Memoized value
useMemo(() => compute(), deps)
useRef
Mutable ref container
useRef(initialValue)
– 
.current
persists across renders
Translation
i18n support
Translation.get('key')
for localized strings
Store
Redux-like state container
Store.create({ reducer, initial })
; factory; 
Store.Provider
– wrap the tree in JSX; 
useSelector(fn)
– select slice; 
useDispatch()
– dispatch actions
Reducer
Creates typed reducers
Reducer.create(handlers)
; action handler map; 
Reducer.combine([{path, reduce}])
– combine reducers (takes array, not plain object)
useDispatch
Dispatch hook
var dispatch = useDispatch()
; dispatches Store actions; requires 
Store.Provider
ancestor
useSelector
State selector hook
var value = useSelector(function(state) { return state.data; })
– selects state slice from Store
CancellationTokenSource
Async operation cancellation
new CancellationTokenSource()
→ 
var token = source.token
(pass to async fn), 
source.cancel()
(call in useEffect cleanup)
CancellationToken
Cancellation check
token.cancelled
; check before updating state in async callbacks
TreeDataSource
Hierarchical grid/tree data
new TreeDataSource({ data, childAccessor: fn })
; 
fn
receives item, returns children array (or pass string property name). Use with 
DataGrid.ColumnType.TREE
or 
TreeView
LazyDataSource
On-demand data loading
new LazyDataSource(() => fetch().then(data => new ArrayDataSource(data)))
– wraps any async data load. 
.load()
triggers load; 
.loaded
checks status. Use with DataGrid 
paging
for server-side pagination
ImmutableArray
Immutable array helpers
ImmutableArray.push(arr, item)
, 
ImmutableArray.remove(arr, item)
, 
ImmutableArray.set(arr, index, item)
, 
ImmutableArray.filter(arr, fn)
, 
ImmutableArray.EMPTY
; all return new arrays
ImmutableObject
Immutable object helpers
ImmutableObject.set(obj, 'key', value)
, 
ImmutableObject.merge(obj, partial)
, 
ImmutableObject.remove(obj, 'key')
; all return new objects
FormatService
Locale-aware type formatting
FormatService.forI18n(i18n).format(date, Format.DATE)
; converts UIF Date to display string. 
Format
enum: 
DATE
, 
DATE_TIME
, 
TIME
, 
INTEGER
, 
FLOAT
. Get 
i18n
via 
useContext(ContextType.I18N)
SystemIcon
System icon constants (277)
SystemIcon.ADD
, 
SystemIcon.EDIT
, 
SystemIcon.DELETE
, 
SystemIcon.FILTER
, 
SystemIcon.HOME
, 
SystemIcon.SEARCH
, 
SystemIcon.SETTINGS
, 
SystemIcon.SAVE
, 
SystemIcon.CLOSE
, 
SystemIcon.ALERT
, 
SystemIcon.CALENDAR
, 
SystemIcon.DOWNLOAD_DOCUMENT
, 
SystemIcon.UPLOAD_DOCUMENT
, 
SystemIcon.PERSON
– search for 
SystemIcon
in 
core.d.ts
for full catalog
RecordIcon
NetSuite record icons (43)
RecordIcon.CUSTOMER
, 
RecordIcon.EMPLOYEE
, 
RecordIcon.INVOICE
, 
RecordIcon.SALES_ORDER
, 
RecordIcon.CONTACT
, 
RecordIcon.ITEM
, 
RecordIcon.CASE
, 
RecordIcon.TASK
EventBus
Pub/sub event bus
eventBus.subscribe(sender, listener)
, 
eventBus.publish(event)
– for decoupled cross-component communication without prop-drilling or shared state
KeyCode
Keyboard key constants (101)
KeyCode.ENTER
, 
KeyCode.ESCAPE
, 
KeyCode.TAB
, 
KeyCode.BACKSPACE
, 
KeyCode.SPACE
, 
KeyCode.ARROW_DOWN
, 
KeyCode.ARROW_UP
, 
KeyCode.F1
–
KeyCode.F12
, 
KeyCode.A
–
KeyCode.Z
, 
KeyCode.NUM_0
–
KeyCode.NUM_9
类用途关键成员
Date
UIF日期包装类
.year
、
.month
（0索引）、
.day
、
.firstOfMonth()
、
.lastOfMonth()
、
.addDay()
、
.addMonth()
、
.stripTime()
、
.toDate()
（→ 原生Date）、
Date.now()
、
Date.today()
ArrayDataSource
表格数据提供器
ArrayDataSource<T>
– 构造函数接收
T[]
Ajax
HTTP客户端
Ajax.post()
、
Ajax.get()
、
Ajax.DataType
、
Ajax.ResponseType
Router
SPA路由
Router.Routes
、
Router.Route
、
Router.Hash
、
Router.Path
useState
状态钩子
useState(initialValue)
→ 
[value, setter]
useEffect
副作用钩子
useEffect(callback, deps)
useContext
上下文钩子
useContext(contextName: string)
– 接收字符串，例如
ContextType.ROUTER_LOCATION
Context
上下文提供器
Context.Provider
、
Context.Consumer
ContextType
上下文类型字符串常量
ContextType.ROUTER_LOCATION
、
ContextType.ROUTER_NAVIGATION
、
ContextType.ROUTER_ROUTE
、
ContextType.I18N
、
ContextType.PREFERENCES
、
ContextType.FOCUS_MANAGER
、
ContextType.STORE
– 完整列表：31个值；在
core.d.ts
中搜索
ContextType
查看
useCallback
记忆化回调
useCallback(fn, deps)
– 防止不必要的重渲染
useMemo
记忆化值
useMemo(() => compute(), deps)
useRef
可变引用容器
useRef(initialValue)
– 
.current
在渲染间持久化
Translation
国际化支持
Translation.get('key')
获取本地化字符串
Store
类Redux状态容器
Store.create({ reducer, initial })
；工厂函数；
Store.Provider
– 在JSX中包裹组件树；
useSelector(fn)
– 选择状态切片；
useDispatch()
– 分发动作
Reducer
创建类型化reducer
Reducer.create(handlers)
；动作处理映射；
Reducer.combine([{path, reduce}])
– 合并reducer（接收数组而非普通对象）
useDispatch
分发钩子
var dispatch = useDispatch()
；分发Store动作；需要
Store.Provider
作为祖先组件
useSelector
状态选择器钩子
var value = useSelector(function(state) { return state.data; })
– 从Store中选择状态切片
CancellationTokenSource
异步操作取消
new CancellationTokenSource()
→ 
var token = source.token
（传递给异步函数），
source.cancel()
（在useEffect清理函数中调用）
CancellationToken
取消状态检查
token.cancelled
；在异步回调中更新状态前检查
TreeDataSource
层级表格/树数据
new TreeDataSource({ data, childAccessor: fn })
；
fn
接收项并返回子项数组（或传递字符串属性名）。与
DataGrid.ColumnType.TREE
或
TreeView
配合使用
LazyDataSource
按需数据加载
new LazyDataSource(() => fetch().then(data => new ArrayDataSource(data)))
– 包装任何异步数据加载。
.load()
触发加载；
.loaded
检查状态。与DataGrid的
paging
配合实现服务端分页
ImmutableArray
不可变数组工具
ImmutableArray.push(arr, item)
、
ImmutableArray.remove(arr, item)
、
ImmutableArray.set(arr, index, item)
、
ImmutableArray.filter(arr, fn)
、
ImmutableArray.EMPTY
；所有方法都返回新数组
ImmutableObject
不可变对象工具
ImmutableObject.set(obj, 'key', value)
、
ImmutableObject.merge(obj, partial)
、
ImmutableObject.remove(obj, 'key')
；所有方法都返回新对象
FormatService
区域感知类型格式化
FormatService.forI18n(i18n).format(date, Format.DATE)
；将UIF Date转换为显示字符串。
Format
枚举：
DATE
、
DATE_TIME
、
TIME
、
INTEGER
、
FLOAT
。通过
useContext(ContextType.I18N)
获取
i18n
SystemIcon
系统图标常量（277个）
SystemIcon.ADD
、
SystemIcon.EDIT
、
SystemIcon.DELETE
、
SystemIcon.FILTER
、
SystemIcon.HOME
、
SystemIcon.SEARCH
、
SystemIcon.SETTINGS
、
SystemIcon.SAVE
、
SystemIcon.CLOSE
、
SystemIcon.ALERT
、
SystemIcon.CALENDAR
、
SystemIcon.DOWNLOAD_DOCUMENT
、
SystemIcon.UPLOAD_DOCUMENT
、
SystemIcon.PERSON
– 在
core.d.ts
中搜索
SystemIcon
查看完整列表
RecordIcon
NetSuite记录图标（43个）
RecordIcon.CUSTOMER
、
RecordIcon.EMPLOYEE
、
RecordIcon.INVOICE
、
RecordIcon.SALES_ORDER
、
RecordIcon.CONTACT
、
RecordIcon.ITEM
、
RecordIcon.CASE
、
RecordIcon.TASK
EventBus
发布/订阅事件总线
eventBus.subscribe(sender, listener)
、
eventBus.publish(event)
– 用于解耦跨组件通信，无需属性透传或共享状态
KeyCode
键盘按键常量（101个）
KeyCode.ENTER
、
KeyCode.ESCAPE
、
KeyCode.TAB
、
KeyCode.BACKSPACE
、
KeyCode.SPACE
、
KeyCode.ARROW_DOWN
、
KeyCode.ARROW_UP
、
KeyCode.F1
–
KeyCode.F12
、
KeyCode.A
–
KeyCode.Z
、
KeyCode.NUM_0
–
KeyCode.NUM_9

@uif-js/component

@uif-js/component

ComponentPurposeKey Props
DataGrid
Table/grid display
dataSource
, 
columns
, 
columnStretch
, 
rootStyle
, 
dataRowHeight
, 
highlightRowsOnHover
StackPanel
Layout container
orientation
, 
itemGap
, 
outerGap
, 
alignment
Button
Clickable button
label
, 
action
, 
enabled
(not 
disabled
– constructor-only). Enums: 
Button.Hierarchy
: PRIMARY/SECONDARY/DANGER; 
Button.Type
: DEFAULT/PRIMARY/PURE/EMBEDDED/GHOST/DANGER/LINK; 
Button.Size
: SMALLER/SMALL/MEDIUM/LARGE; 
Button.Behavior
: DEFAULT/TOGGLE
Text
Text display
type
(WEAK, STRONG, etc.)
Badge
Status badges
label
, 
classList
(single class only!)
Heading
Section headings
type
(LARGE_HEADING, MEDIUM_HEADING, etc.)
Card
Card containerContent wrapper
ContentPanel
Content wrapper
outerGap
, 
horizontalAlignment
ApplicationHeader
Page header
title
Modal
Dialog overlay
title
, 
size
(DEFAULT/SMALL/MEDIUM/LARGE), 
rootStyle
, 
owner
, 
content
, 
closeButton
Loader
Loading spinner
label
GridPanel
CSS Grid layout
columns
, 
defaultColumnWidth
, 
gap
; prefer over horizontal StackPanel
ScrollPanel
Scrollable container
orientation
– requires bounded parent height
NavigationDrawer
Vertical nav
selectedValue
, items with 
route
, 
icon
, 
label
Dropdown
Select input
dataSource
, 
selectedValue
, 
onSelectedValueChanged
; do not use 
Select
TextBox
Text input
text
, 
onTextChanged
, 
placeholder
, 
maxLength
CheckBox
Boolean input
value
, 
onValueChanged
, 
label
TabPanel
Tab navigation
selectedValue
, 
selectedIndex
, items as 
Tab
children with 
label
, 
value
, 
icon
. Event: 
onSelectionChanged
. Enum: 
TabPanel.ContentUpdateReason
Tooltip
Hover tooltipVia component 
tooltip
prop – every Component has it
Portlet
Dashboard card
title
, 
description
, collapsible container
Skeleton
Loading placeholder
Skeleton.Table
, width/height for loading states
Link
Anchor element
url
, 
content
– standard hyperlink
Image
Image display
image
(ImageMetadata), 
alt
ListView
Rich data list
ListView.ofStaticData()
, layout config, search
DatePicker
Date input
date
, 
onDateChanged
, 
withTimePicker
for datetime
Switch
Toggle switch
value
, 
onValueChanged
– on/off toggle
Popover
Popup content
owner
, closing strategy, positioned relative to owner
SplitPanel
Resizable sections
orientation
– horizontal or vertical resizable panes
Field
Form field wrapper
label
, 
control
(the input component), 
mode
(EDIT/VIEW), 
mandatory
, 
orientation
(HORIZONTAL/VERTICAL), 
size
(AUTO/SMALL/MEDIUM/LARGE/XLARGE/XXLARGE/STRETCH). Use 
Field.Mode.EDIT
for editable forms, 
Field.Mode.VIEW
for read-only display
FieldGroup
Grouped fields
title
, 
collapsed
, 
collapsible
, 
color
(
FieldGroup.Color
: THEMED/NEUTRAL) – wraps related 
Field
components with a section header
TextArea
Multi-line text input
text
, 
onTextChanged
, 
placeholder
, 
maxLength
, 
resizable
(
TextArea.ResizeDirection
) – use instead of 
TextBox
when users need multi-line input
RadioButtonGroup
Radio button group
selectedData
, 
onSelectionChanged
, 
columns
– use 
RadioButton
children with 
label
, 
data
, 
value
props
Banner
Inline alert/feedback
title
, 
content
, 
color
– 
Banner.Color
: BLUE, BLUE_DARK, GREEN, ORANGE. Use 
Banner.Color.GREEN
for success, 
Banner.Color.ORANGE
for warning
GrowlPanel
Toast notification container
position
, 
messages
– add to root layout; manages all toast messages. Use once per SPA shell. Imperative: 
growlPanelRef.current.add(msg)
GrowlMessage
Single toast message
title
, 
content
, 
type
(INFO/SUCCESS/WARNING/ERROR), 
showCloseButton
– add to a GrowlPanel
AccordionPanel
Collapsible sections
items
(AccordionPanelItem children with 
label
, 
icon
, 
collapsed
), 
multiple
(allow multiple open), 
fullyCollapsible
. Enum: 
AccordionPanel.Orientation
: VERTICAL/HORIZONTAL
Pagination
Page navigation
selectedPageIndex
, 
pages
, 
rowsPerPage
, 
rowsCount
. Event: 
onPageSelected
. Enum: 
Pagination.RowsCounter
: COMPLETE/TOTAL/UNKNOWN/CUSTOM/NONE
ToolBar
Action button container
components
, 
children
, 
orientation
, 
wrap
. 
ToolBarGroup
groups related tools with spacing. Enum: 
ToolBar.VisualStyle
: SMALL/MEDIUM/LARGE/XLARGE/PLAIN
Menu
Dropdown menu
items
(MenuItem/MenuGroup children), 
orientation
, 
size
. 
MenuItem
has 
label
, 
icon
, 
action
. Enum: 
Menu.ItemType
: MENU_ITEM/ITEM/GROUP
MenuButton
Button with dropdown
label
, 
icon
, 
menu
(Menu component). Combines Button + Menu in one component. Search 
component.d.ts
for full props
FilterPanel
Filter container
values
, 
activeFilters
, 
showClearAll
, 
onFiltersChanged
. Contains 
FilterChip
children. Enum: 
FilterPanel.Orientation
: VERTICAL/HORIZONTAL
FilterChip
Single filter input
label
, 
selectedValue
, 
picker
(dropdown/listbox picker), 
onValueChanged
, 
onValueAccepted
. Enum: 
FilterChip.Size
: SMALL/MEDIUM
MultiselectDropdown
Multi-value dropdown
selectedItems
, 
dataSource
, 
empty
, 
mandatory
, 
onSelectionChanged
. Enum: 
MultiselectDropdown.VisualStyle
: STANDALONE/EMBEDDED/REDWOOD_FIELD
Stepper
Multi-step wizard
items
(StepperItem children with 
label
, 
description
, 
done
, 
disabled
), 
selectedStepIndex
, 
orientation
, 
onSelectionChanged
. Enum: 
Stepper.Reason
: CALL
Breadcrumbs
Navigation trail
items
(BreadcrumbsItem with 
label
, 
url
/
route
, 
icon
), 
expanded
, 
expandStrategy
. Enum: 
Breadcrumbs.ExpandStrategy
: EXPAND/MENU/NONE
组件用途关键属性
DataGrid
表格/网格展示
dataSource
、
columns
、
columnStretch
、
rootStyle
、
dataRowHeight
、
highlightRowsOnHover
StackPanel
布局容器
orientation
、
itemGap
、
outerGap
、
alignment
Button
可点击按钮
label
、
action
、
enabled
（不是
disabled
– 仅构造函数可用）。枚举：
Button.Hierarchy
: PRIMARY/SECONDARY/DANGER；
Button.Type
: DEFAULT/PRIMARY/PURE/EMBEDDED/GHOST/DANGER/LINK；
Button.Size
: SMALLER/SMALL/MEDIUM/LARGE；
Button.Behavior
: DEFAULT/TOGGLE
Text
文本展示
type
（WEAK、STRONG等）
Badge
状态徽章
label
、
classList
（仅支持单个类名！）
Heading
章节标题
type
（LARGE_HEADING、MEDIUM_HEADING等）
Card
卡片容器内容包装器
ContentPanel
内容包装器
outerGap
、
horizontalAlignment
ApplicationHeader
页面头部
title
Modal
对话框浮层
title
、
size
（DEFAULT/SMALL/MEDIUM/LARGE）、
rootStyle
、
owner
、
content
、
closeButton
Loader
加载动画
label
GridPanel
CSS Grid布局
columns
、
defaultColumnWidth
、
gap
；优先于水平StackPanel使用
ScrollPanel
可滚动容器
orientation
– 需要父容器有固定高度
NavigationDrawer
垂直导航
selectedValue
、包含
route
、
icon
、
label
的菜单项
Dropdown
选择输入框
dataSource
、
selectedValue
、
onSelectedValueChanged
；不要使用
Select
TextBox
文本输入框
text
、
onTextChanged
、
placeholder
、
maxLength
CheckBox
布尔输入框
value
、
onValueChanged
、
label
TabPanel
标签页导航
selectedValue
、
selectedIndex
、作为
Tab
子项的标签页（包含
label
、
value
、
icon
）。事件：
onSelectionChanged
。枚举：
TabPanel.ContentUpdateReason
Tooltip
悬停提示通过组件的
tooltip
属性使用 – 所有UIF组件都支持
Portlet
仪表盘卡片
title
、
description
、可折叠容器
Skeleton
加载占位符
Skeleton.Table
、用于加载状态的宽/高属性
Link
锚点元素
url
、
content
– 标准超链接
Image
图片展示
image
（ImageMetadata）、
alt
ListView
富数据列表
ListView.ofStaticData()
、布局配置、搜索
DatePicker
日期输入框
date
、
onDateChanged
、
withTimePicker
用于日期时间选择
Switch
切换开关
value
、
onValueChanged
– 开/关切换
Popover
弹出内容
owner
、关闭策略、相对于owner定位
SplitPanel
可调整大小的区域
orientation
– 水平或垂直可调整大小的面板
Field
表单字段包装器
label
、
control
（输入组件）、
mode
（EDIT/VIEW）、
mandatory
、
orientation
（HORIZONTAL/VERTICAL）、
size
（AUTO/SMALL/MEDIUM/LARGE/XLARGE/XXLARGE/STRETCH）。使用
Field.Mode.EDIT
用于可编辑表单，
Field.Mode.VIEW
用于只读展示
FieldGroup
字段组
title
、
collapsed
、
collapsible
、
color
（
FieldGroup.Color
: THEMED/NEUTRAL） – 用章节标题包裹相关
Field
组件
TextArea
多行文本输入框
text
、
onTextChanged
、
placeholder
、
maxLength
、
resizable
（
TextArea.ResizeDirection
） – 当用户需要多行输入时替代
TextBox
RadioButtonGroup
单选按钮组
selectedData
、
onSelectionChanged
、
columns
– 使用包含
label
、
data
、
value
属性的
RadioButton
子项
Banner
内联提示/反馈
title
、
content
、
color
– 
Banner.Color
: BLUE、BLUE_DARK、GREEN、ORANGE。使用
Banner.Color.GREEN
表示成功，
Banner.Color.ORANGE
表示警告
GrowlPanel
通知消息容器
position
、
messages
– 添加到根布局；管理所有通知消息。每个SPA外壳只使用一次。命令式调用：
growlPanelRef.current.add(msg)
GrowlMessage
单个通知消息
title
、
content
、
type
（INFO/SUCCESS/WARNING/ERROR）、
showCloseButton
– 添加到GrowlPanel中
AccordionPanel
可折叠章节
items
（包含
label
、
icon
、
collapsed
的AccordionPanelItem子项）、
multiple
（允许多个展开）、
fullyCollapsible
。枚举：
AccordionPanel.Orientation
: VERTICAL/HORIZONTAL
Pagination
分页导航
selectedPageIndex
、
pages
、
rowsPerPage
、
rowsCount
。事件：
onPageSelected
。枚举：
Pagination.RowsCounter
: COMPLETE/TOTAL/UNKNOWN/CUSTOM/NONE
ToolBar
操作按钮容器
components
、
children
、
orientation
、
wrap
。
ToolBarGroup
将相关工具分组并添加间距。枚举：
ToolBar.VisualStyle
: SMALL/MEDIUM/LARGE/XLARGE/PLAIN
Menu
下拉菜单
items
（MenuItem/MenuGroup子项）、
orientation
、
size
。
MenuItem
包含
label
、
icon
、
action
。枚举：
Menu.ItemType
: MENU_ITEM/ITEM/GROUP
MenuButton
带下拉菜单的按钮
label
、
icon
、
menu
（Menu组件）。结合Button和Menu为一个组件。在
component.d.ts
中搜索查看完整属性
FilterPanel
筛选器容器
values
、
activeFilters
、
showClearAll
、
onFiltersChanged
。包含
FilterChip
子项。枚举：
FilterPanel.Orientation
: VERTICAL/HORIZONTAL
FilterChip
单个筛选器输入
label
、
selectedValue
、
picker
（下拉/列表选择器）、
onValueChanged
、
onValueAccepted
。枚举：
FilterChip.Size
: SMALL/MEDIUM
MultiselectDropdown
多选下拉框
selectedItems
、
dataSource
、
empty
、
mandatory
、
onSelectionChanged
。枚举：
MultiselectDropdown.VisualStyle
: STANDALONE/EMBEDDED/REDWOOD_FIELD
Stepper
多步骤向导
items
（包含
label
、
description
、
done
、
disabled
的StepperItem子项）、
selectedStepIndex
、
orientation
、
onSelectionChanged
。枚举：
Stepper.Reason
: CALL
Breadcrumbs
导航路径
items
（包含
label
、
url
/
route
、
icon
的BreadcrumbsItem）、
expanded
、
expandStrategy
。枚举：
Breadcrumbs.ExpandStrategy
: EXPAND/MENU/NONE

Global Component Enums

全局组件枚举

These enums are available directly from 
@uif-js/component
and are used across many components.
这些枚举可直接从
@uif-js/component
获取，并在多个组件中使用。

GapSize

GapSize

Used for 
itemGap
, 
outerGap
, 
contentGap
on StackPanel, GridPanel, ContentPanel, AccordionPanel, etc.
NONE
, 
XXXXS
, 
XXXS
, 
XXS
, 
XS
, 
S
, 
M
, 
L
, 
XL
, 
XXL
, 
XXXL
, 
XXXXL
SPACING1X
through 
SPACING12X
, 
SMALL
, 
MEDIUM
, 
LARGE
.
jsx
import { GapSize } from '@uif-js/component';
<StackPanel itemGap={GapSize.M} outerGap={GapSize.L} ... />
Note: Some components (StackPanel, GridPanel) expose their own nested 
GapSize
type. The top-level 
GapSize
export from 
@uif-js/component
is the standard enum to use.
用于StackPanel、GridPanel、ContentPanel、AccordionPanel等的
itemGap
、
outerGap
、
contentGap
属性。
NONE
、
XXXXS
、
XXXS
、
XXS
、
XS
、
S
、
M
、
L
、
XL
、
XXL
、
XXXL
、
XXXXL
SPACING1X
至
SPACING12X
、
SMALL
、
MEDIUM
、
LARGE
。
jsx
import { GapSize } from '@uif-js/component';
<StackPanel itemGap={GapSize.M} outerGap={GapSize.L} ... />
注意：部分组件（StackPanel、GridPanel）暴露自己的嵌套
GapSize
类型。从
@uif-js/component
导出的顶层
GapSize
是标准枚举，建议使用该版本。

InputSize

InputSize

Used for 
size
on 
TextBox
, 
Dropdown
, 
DatePicker
, 
TimePicker
, 
Switch
, etc.
AUTO
, 
XXS
, 
XS
, 
S
, 
M
, 
L
, 
XL
, 
XXL
用于
TextBox
、
Dropdown
、
DatePicker
、
TimePicker
、
Switch
等的
size
属性。
AUTO
、
XXS
、
XS
、
S
、
M
、
L
、
XL
、
XXL

VisualizationColor

VisualizationColor

Semantic color set for 
Kpi
, 
Reminder
, 
Banner
, 
Avatar
, 
Badge
color props:
NEUTRAL
, 
SUCCESS
, 
WARNING
, 
DANGER
, 
INFO
, 
TEAL
, 
ORANGE
, 
TURQUOISE
, 
TAUPE
, 
GREEN
, 
PINK
, 
BROWN
, 
LILAC
, 
YELLOW
, 
PURPLE
, 
BLUE
, 
PINE
用于
Kpi
、
Reminder
、
Banner
、
Avatar
、
Badge
颜色属性的语义化颜色集合：
NEUTRAL
、
SUCCESS
、
WARNING
、
DANGER
、
INFO
、
TEAL
、
ORANGE
、
TURQUOISE
、
TAUPE
、
GREEN
、
PINK
、
BROWN
、
LILAC
、
YELLOW
、
PURPLE
、
BLUE
、
PINE

Known Pitfalls from Production Experience

生产经验中的常见陷阱

UIF Date

UIF Date

  • Date.now()
    returns a UIF Date object, not a number like native 
    Date.now()
    .
  • UIF Date uses 
    .year
    , 
    .month
    , 
    .day
    properties (not 
    .getFullYear()
    , 
    .getMonth()
    , 
    .getDate()
    ).
  • .month
    is 0-indexed (January = 0).
  • UIF SPA runtime does not replace global 
    Date
    ; 
    new Date()
    creates a native JS Date.
  • Only 
    import { Date } from '@uif-js/core'
    returns UIF Date.
  • If the import fails silently, 
    Date
    falls back to native 
    Date
    and 
    Date.now()
    returns milliseconds.
  • Date.now()
    返回UIF Date对象，而非原生
    Date.now()
    那样的数字。
  • UIF Date使用
    .year
    、
    .month
    、
    .day
    属性（不是
    .getFullYear()
    、
    .getMonth()
    、
    .getDate()
    ）。
  • .month
    是0索引的（一月=0）。
  • UIF SPA运行时不会替换全局
    Date
    ；
    new Date()
    创建的是原生JS Date。
  • 只有
    import { Date } from '@uif-js/core'
    才会返回UIF Date。
  • 如果导入失败，
    Date
    会回退到原生
    Date
    ，此时
    Date.now()
    返回毫秒数。

StackPanel

StackPanel

  • StackPanel rejects all null children; 
    {cond ? <Item>... : null}
    will throw an error.
  • Empty arrays are also rejected; 
    {emptyArray}
    inside StackPanel causes "Invalid StackPanel item" error. Never spread or inline an array that may be empty. Use a for-loop to append items: 
    for (var i = 0; i < items.length; i++) rootItems.push(items[i]);
    .
  • Only safe pattern: Imperative array building: 
    var items = []; if (x) items.push(<Item>...</Item>);
    .
  • StackPanel.Item
    must have exactly one child.
  • StackPanel会拒绝所有null子项；
    {cond ? <Item>... : null}
    会抛出错误。
  • 空数组也会被拒绝；在StackPanel中使用
    {emptyArray}
    会导致"Invalid StackPanel item"错误。永远不要展开或内联可能为空的数组。使用for循环添加项：
    for (var i = 0; i < items.length; i++) rootItems.push(items[i]);
    。
  • 唯一安全的模式：命令式构建数组：
    var items = []; if (x) items.push(<Item>...</Item>);
    。
  • StackPanel.Item
    必须恰好有一个子项。

Modal Placement

Modal 放置

  • Modals must be at the root component level. Placing modals inside deeply nested containers (for example, GridPanel > ContentPanel > StackPanel) causes stacking context issues where the modal renders inline behind page content instead of as a floating overlay.
  • Push modal 
    <StackPanel.Item>
    elements into the root-level items array, not into a nested content array.
  • Always use imperative array pattern for modals: build a 
    modalItems
    array, then append to root items via for-loop.
  • Modal必须位于根组件层级。 将Modal放置在深层嵌套容器中（例如GridPanel > ContentPanel > StackPanel）会导致堆叠上下文问题，Modal会内联渲染在页面内容后方，而非作为浮层显示。
  • 将Modal的
    <StackPanel.Item>
    元素添加到根层级的items数组中，而非嵌套的内容数组。
  • 始终为Modal使用命令式数组模式：构建
    modalItems
    数组，然后通过for循环添加到根items中。

Badge

Badge

  • Badge.Size
    exists with values 
    DEFAULT
    and 
    SMALL
    ; use 
    size={Badge.Size.SMALL}
    for compact badges.
  • classList
    prop uses 
    DOMTokenList.add()
    internally; space-separated strings throw 
    InvalidCharacterError
    .
  • Always use a single class name per classList value.
  • 存在
    Badge.Size
    枚举，值为
    DEFAULT
    和
    SMALL
    ；使用
    size={Badge.Size.SMALL}
    获取紧凑徽章。
  • classList
    属性内部使用
    DOMTokenList.add()
    ；空格分隔的字符串会抛出
    InvalidCharacterError
    。
  • 始终为classList值使用单个类名。

DataGrid

DataGrid

  • Full-width grids: 
    columnStretch={true}
    distributes column space proportionally, but only within the grid's own computed width; it does not make the grid fill its container. To achieve full-width:
    1. Always keep explicit 
      width
      on every column; these act as proportional weights for 
      columnStretch
      . Without them, columns collapse to tiny minimums.
    2. Add 
      rootStyle={{ width: '100%' }}
      on the DataGrid to make it fill its parent container's width.
    3. Give wider columns a larger 
      width
      value (for example, Description: 500, Name: 250, Badge: 70) so they get more proportional share.
  • rootStyle
    is inherited from the base 
    Component
    class; all UIF components accept 
    rootStyle={{ ... }}
    for inline CSS on the root DOM element.
  • Do not use 
    stretchStrategy={{}}
    ; it is constructor-only and causes VDom "Writable property not found" errors on re-render.
  • TEMPLATED column 
    content
    callback: 
    args
    has 
    {cell, context}
    , use 
    args.cell.value
    or 
    args.cell.row.dataItem
    .
  • Always wrap TEMPLATED callbacks in try/catch; unhandled throws blank all remaining columns.
  • dataRowHeight
    is the correct prop for row height; 
    rowHeight
    is silently ignored.
  • CHECK_BOX
    columns require grid-level 
    editable={true}
    ; setting 
    editable: true
    on the column definition alone is not sufficient. Without 
    editable={true}
    on the DataGrid itself, the column space renders but the checkbox widget is invisible.
  • CHECK_BOX
    columns + 
    CELL_UPDATE
    is unreliable    ; 
    DataGrid.Event.CELL_UPDATE
    may not fire when checkboxes are toggled, making it impossible to track selection state. Preferred pattern: Use a TEMPLATED column with a toggle Button (for example, 
    label={checked ? '\u2611' : '\u2610'}
    ). Manage checked state in a 
    useRef({})
    keyed by row ID. The Button 
    action
    flips the ref entry and calls a 
    setState
    counter to trigger re-render.
  • DataGrid.Options – key constructor-only vs writable props: The Options interface (constructor) accepts many properties that are NOT writable after construction:
    • Constructor-only: 
      stretchStrategy
      , 
      autoSize
      , 
      bindingController
      , 
      editingMode
      , 
      preload
      , 
      defaultColumnOptions
      , 
      lockedLevels
      , 
      beforeEditCell
      , 
      stripedRows
      , 
      multiColumnSort
      , 
      allowUnsort
    • Writable: 
      columnStretch
      , 
      editable
      , 
      paging
      , 
      pageSize
      , 
      pageNumber
      , 
      sortable
      , 
      placeholder
      , 
      showHeader
      , 
      highlightRowsOnHover
  • maxViewportWidth
     – Similar to 
    maxViewportHeight
    , limits horizontal viewport. Use for grids with many columns to prevent horizontal overflow.
  • stripedRows={true}
     – Enables alternating row stripes for readability. Constructor option.
  • editingMode
     – 
    DataGrid.EditingMode.CELL
    (default) or 
    DataGrid.EditingMode.ROW
    . ROW mode edits all cells in a row simultaneously.
  • multiColumnSort={true}
     – Enables sorting by multiple columns. Off by default.
  • allowUnsort={true}
     – Lets users click a sorted column back to unsorted state.
  • Selection system – DataGrid has built-in selection via 
    SelectionColumn
    type and 
    DataGrid.SingleSelection
    /
    DataGrid.MultiSelection
    strategies. More reliable than CHECK_BOX columns for row selection.
  • Useful imperative methods – 
    autoSize()
    , 
    stretchColumns()
    , 
    reload()
    , 
    rowForDataItem(dataItem)
    , 
    scrollTo({cell/row/column})
    , 
    pinRow(row, section)
    .
  • 全宽表格：
    columnStretch={true}
    会按比例分配列空间，但仅在表格自身计算的宽度内生效；它不会让表格填满容器。要实现全宽：
    1. 始终为每个列设置明确的
      width
      ；这些值在
      columnStretch
      下作为比例权重。如果没有设置，列会收缩到极小的最小宽度。
    2. 在DataGrid上添加
      rootStyle={{ width: '100%' }}
      使其填满父容器宽度。
    3. 为较宽的列设置更大的
      width
      值（例如Description:500，Name:250，Badge:70），使其获得更多比例空间。
  • rootStyle
    继承自基础
    Component
    类；所有UIF组件都接受
    rootStyle={{ ... }}
    用于根DOM元素的内联CSS。
  • 不要使用
    stretchStrategy={{}}
    ；它仅在构造函数中可用，在重渲染时会导致VDom "Writable property not found"错误。
  • TEMPLATED列的
    content
    回调：
    args
    包含
    {cell, context}
    ，使用
    args.cell.value
    或
    args.cell.row.dataItem
    。
  • 始终将TEMPLATED回调包裹在try/catch中；未处理的异常会导致剩余所有列显示为空。
  • dataRowHeight
    是设置行高的正确属性；
    rowHeight
    会被静默忽略。
  • CHECK_BOX
    列需要表格级别的
    editable={true}
    ；仅在列定义上设置
    editable: true
    是不够的。如果DataGrid本身没有
    editable={true}
    ，列空间会渲染，但复选框小部件不可见。
  • CHECK_BOX
    列 + 
    CELL_UPDATE
    不可靠    ；
    DataGrid.Event.CELL_UPDATE
    在切换复选框时可能不会触发，导致无法跟踪选择状态。推荐模式：使用包含切换Button的TEMPLATED列（例如
    label={checked ? '\u2611' : '\u2610'}
    ）。在
    useRef({})
    中按行ID管理选中状态。Button的
    action
    切换ref中的值并调用
    setState
    计数器触发重渲染。
  • DataGrid.Options – 区分构造函数专属属性与可写属性：Options接口（构造函数）接受许多在构造后不可写的属性：
    • 仅构造函数可用：
      stretchStrategy
      、
      autoSize
      、
      bindingController
      、
      editingMode
      、
      preload
      、
      defaultColumnOptions
      、
      lockedLevels
      、
      beforeEditCell
      、
      stripedRows
      、
      multiColumnSort
      、
      allowUnsort
    • 可写：
      columnStretch
      、
      editable
      、
      paging
      、
      pageSize
      、
      pageNumber
      、
      sortable
      、
      placeholder
      、
      showHeader
      、
      highlightRowsOnHover
  • maxViewportWidth
     – 与
    maxViewportHeight
    类似，限制水平视口宽度。用于列数较多的表格以防止水平溢出。
  • stripedRows={true}
     – 启用交替行条纹以提高可读性。构造函数选项。
  • editingMode
     – 
    DataGrid.EditingMode.CELL
    （默认）或
    DataGrid.EditingMode.ROW
    。ROW模式允许同时编辑一行中的所有单元格。
  • multiColumnSort={true}
     – 启用多列排序。默认关闭。
  • allowUnsort={true}
     – 允许用户点击已排序的列回到未排序状态。
  • 选择系统 – DataGrid通过
    SelectionColumn
    类型和
    DataGrid.SingleSelection
    /
    DataGrid.MultiSelection
    策略提供内置选择功能。对于行选择，这比CHECK_BOX列更可靠。
  • 有用的命令式方法 – 
    autoSize()
    、
    stretchColumns()
    、
    reload()
    、
    rowForDataItem(dataItem)
    、
    scrollTo({cell/row/column})
    、
    pinRow(row, section)
    。

Select / Dropdown

Select / Dropdown

  • Select
    does not exist in 
    @uif-js/component
    ; importing it resolves to 
    undefined
    . Using 
    <Select>
    in a TEMPLATED column silently throws, and try/catch fallbacks mask the error (renders em-dash or blank instead of a dropdown).
  • For dropdown components inside DataGrid: Use 
    DataGrid.ColumnType.DROPDOWN
    with these key options: 
    • inputMode: DataGrid.InputMode.EDIT_ONLY
      ; makes the dropdown always visible (not just on click).
    • valueMember: 'value'
      , 
      displayMember: 'label'
      , 
      bindToValue: true
      ; binds to the value property, displays the label.
    • dataSource
      : static 
      ArrayDataSource
      (cache via 
      useRef
      to avoid recreation each render).
    • dataSourceConfigurator: function(row) { return new ArrayDataSource([...]); }
      ; for per-row dynamic options.
    • widgetOptions: { allowEmpty: true, placeholder: 'Unassigned' }
      ; passed through to the underlying 
      Dropdown
      widget.
    • Wire value changes via 
      DataGrid.Event.CELL_UPDATE
      on the grid's 
      on
      prop, not via onChange on individual cells.
    • The grid itself must have 
      editable={true}
      for DROPDOWN columns to be interactive.
  • For standalone dropdowns outside DataGrid: Use 
    Dropdown
    from 
    @uif-js/component
    (not 
    Select
    ).
  • @uif-js/component
    中不存在
    Select
    ；导入它会得到
    undefined
    。在TEMPLATED列中使用
    <Select>
    会静默抛出异常，try/catch回退会掩盖错误（显示破折号或空白而非下拉框）。
  • DataGrid内的下拉组件：使用
    DataGrid.ColumnType.DROPDOWN
    并设置以下关键选项： 
    • inputMode: DataGrid.InputMode.EDIT_ONLY
      ；使下拉框始终可见（不仅在点击时）。
    • valueMember: 'value'
      、
      displayMember: 'label'
      、
      bindToValue: true
      ；绑定到value属性，显示label。
    • dataSource
      : 静态
      ArrayDataSource
      （通过
      useRef
      缓存以避免每次渲染都重新创建）。
    • dataSourceConfigurator: function(row) { return new ArrayDataSource([...]); }
      ；用于每行动态选项。
    • widgetOptions: { allowEmpty: true, placeholder: '未分配' }
      ；传递给底层
      Dropdown
      小部件。
    • 通过表格
      on
      属性上的
      DataGrid.Event.CELL_UPDATE
      监听值变化，而非单个单元格的onChange。
    • 表格本身必须设置
      editable={true}
      才能使DROPDOWN列可交互。
  • DataGrid外的独立下拉框：使用
    @uif-js/component
    中的
    Dropdown
    （不要使用
    Select
    ）。

Modal

Modal

  • Modal.Size
    enum only has: 
    DEFAULT
    , 
    SMALL
    , 
    MEDIUM
    , 
    LARGE
    ; there is no 
    EXTRA_LARGE
    .
  • Modal.Size.LARGE
    has an internal max-width that 
    rootStyle
    cannot override     when both are set. The 
    size
    prop's CSS takes precedence.
  • For wider-than-LARGE modals: Remove the 
    size
    prop entirely and control width via 
    rootStyle
    only:
    jsx
    <Modal rootStyle={{ width: '80vw', maxWidth: '1200px' }} ... />
  • When a DataGrid is inside a Modal, always add 
    rootStyle={{ width: '100%' }}
    on the DataGrid so it fills the modal's content area.
  • onClose
    is not a valid prop    ; using 
    onClose={handler}
    throws "VDom: Writable property onClose not found" and prevents the modal from rendering. Modal/Window has no 
    onClose
    callback prop. To handle close, use 
    closeButton={false}
    and provide your own Close 
    <Button>
    inside the modal content. For event-based close handling, use 
    on={{ [Window.Event.CLOSED]: handler }}
    .
  • Modal.Size
    枚举只有：
    DEFAULT
    、
    SMALL
    、
    MEDIUM
    、
    LARGE
    ；没有
    EXTRA_LARGE
    。
  • Modal.Size.LARGE
    有内部最大宽度，当同时设置
    rootStyle
    时无法覆盖    ；
    size
    属性的CSS优先级更高。
  • 要比LARGE更宽的Modal：完全移除
    size
    属性，仅通过
    rootStyle
    控制宽度：
    jsx
    <Modal rootStyle={{ width: '80vw', maxWidth: '1200px' }} ... />
  • 当DataGrid在Modal内部时，始终在DataGrid上添加
    rootStyle={{ width: '100%' }}
    使其填满Modal的内容区域。
  • onClose
    不是有效属性    ；使用
    onClose={handler}
    会抛出"VDom: Writable property onClose not found"并阻止Modal渲染。Modal/Window没有
    onClose
    回调属性。要处理关闭，使用
    closeButton={false}
    并在Modal内容中提供自定义的关闭
    <Button>
    。要基于事件处理关闭，使用
    on={{ [Window.Event.CLOSED]: handler }}
    。

MenuButton

MenuButton

  • MenuButton
    extends 
    Button
    ; accepts all Button props (
    label
    , 
    icon
    , 
    type
    , 
    hierarchy
    , etc.) plus 
    menu
    (array of 
    MenuItem.ItemDefinition
    or 
    Menu.Options
    ).
  • Menu items are 
    ActionItemDefinition
     objects: 
    { label: 'Text', action: function() { ... } }
    . The 
    action
    property is what makes UIF treat them as clickable action items (vs submenu items which only have 
    label
    /
    icon
    ).
  • Do not set 
    icon: null
    on menu items    ; this can interfere with UIF's internal type discrimination between 
    ActionItemDefinition
    and 
    SubmenuItemDefinition
    , causing clicks to silently do nothing.
  • Use 
    SystemIcon.OVERFLOW
    for the standard three-dot menu icon    : 
    <MenuButton icon={SystemIcon.OVERFLOW} type={Button.Type.GHOST} menu={items} />
    .
  • Suppress tooltip with 
    tooltip={null}
    ; MenuButton inherits Button's tooltip behavior which can persist after the dropdown opens.
  • In TEMPLATED DataGrid columns use ref-based handlers in menu item actions to avoid stale closures: 
    { action: function() { myRef.current(item); } }
    .
  • MenuButton
    继承自
    Button
    ；接受所有Button属性（
    label
    、
    icon
    、
    type
    、
    hierarchy
    等）以及
    menu
    （
    MenuItem.ItemDefinition
    或
    Menu.Options
    数组）。
  • 菜单项是
    ActionItemDefinition
    对象    ：
    { label: '文本', action: function() { ... } }
    。
    action
    属性是UIF将其视为可点击操作项的标识（与仅包含
    label
    /
    icon
    的子菜单项区分开）。
  • 不要在菜单项上设置
    icon: null
    ；这会干扰UIF对
    ActionItemDefinition
    和
    SubmenuItemDefinition
    的内部类型判断，导致点击无响应。
  • 使用
    SystemIcon.OVERFLOW
    作为标准三点菜单图标    ：
    <MenuButton icon={SystemIcon.OVERFLOW} type={Button.Type.GHOST} menu={items} />
    。
  • 使用
    tooltip={null}
    禁用提示    ；MenuButton继承了Button的提示行为，下拉菜单打开后提示可能会持续显示。
  • 在DataGrid的TEMPLATED列中，菜单项的action使用基于ref的处理程序以避免闭包过时：
    { action: function() { myRef.current(item); } }
    。

General

通用注意事项

  • rootStyle
    is available on all UIF components (inherited from base 
    Component
    class). Accepts 
    Record<string, string>
    for inline CSS on the root DOM element. Useful for 
    width
    , 
    height
    , 
    minWidth
    , 
    maxWidth
    , etc.
  • Never use empty 
    <Text />
    as conditional fallback; use 
    null
    (but not inside StackPanel!).
  • Large datasets: Cap ArrayDataSource at ~500 rows for preview grids.
  • 所有UIF组件都支持
    rootStyle
    （继承自基础
    Component
    类）。接受
    Record<string, string>
    用于根DOM元素的内联CSS。适用于设置
    width
    、
    height
    、
    minWidth
    、
    maxWidth
    等。
  • 永远不要使用空的
    <Text />
    作为条件回退；使用
    null
    （但不要在StackPanel中使用！）。
  • 大数据集：预览表格的ArrayDataSource限制在约500行。

Store / State Management

Store / 状态管理

  • Store.Provider
    must wrap the component tree above any component calling 
    useDispatch()
    or 
    useSelector()
    ; missing it throws an error from both hooks.
  • Reducer.create()
    takes an object mapping action type strings to handler functions. Each handler receives 
    (state, action)
    and must return a new state object (never mutate).
  • Use 
    ImmutableObject.set(state, 'key', value)
    inside reducers to return updated state without mutation.
  • Store.create()
    is constructor-only; create once at module level, not inside a component.
  • Access the existing store in deep child components via 
    useContext(ContextType.STORE)
    instead of prop-drilling.
  • Store.Provider
    必须包裹在任何调用
    useDispatch()
    或
    useSelector()
    的组件树上方；缺少它会导致两个钩子抛出错误。
  • Reducer.create()
    接收一个将动作类型字符串映射到处理函数的对象。每个处理函数接收
    (state, action)
    并必须返回新的状态对象（永远不要修改原状态）。
  • 在reducers中使用
    ImmutableObject.set(state, 'key', value)
    返回更新后的状态，避免修改原状态。
  • Store.create()
    仅在构造时可用；在模块级别创建一次，不要在组件内部创建。
  • 在深层子组件中通过
    useContext(ContextType.STORE)
    访问现有Store，而非属性透传。

useEffect / Async Cleanup

useEffect / 异步清理

  • Never update state after component unmount; always create a 
    CancellationTokenSource
    at the top of 
    useEffect
    , declare 
    var token = source.token
    , pass token to async operations, call 
    source.cancel()
    in the cleanup function, and check 
    token.cancelled
    before calling any state setter.
  • Correct pattern:
    javascript
    useEffect(function() {
    var source = new CancellationTokenSource();
    var token = source.token;
    Ajax.get({ url: '/api/data' }).then(function(result) {
        if (token.cancelled) return;
        setData(result.data);
    });
    return function() { source.cancel(); };
}, []);
  • 永远不要在组件卸载后更新状态；始终在
    useEffect
    顶部创建
    CancellationTokenSource
    ，声明
    var token = source.token
    ，将token传递给异步操作，在清理函数中调用
    source.cancel()
    ，并在调用任何状态设置器前检查
    token.cancelled
    。
  • 正确模式：
    javascript
    useEffect(function() {
    var source = new CancellationTokenSource();
    var token = source.token;
    Ajax.get({ url: '/api/data' }).then(function(result) {
        if (token.cancelled) return;
        setData(result.data);
    });
    return function() { source.cancel(); };
}, []);

DataGrid – TreeDataSource

DataGrid – TreeDataSource

  • TreeDataSource
    for hierarchy    : Use 
    new TreeDataSource({ data: items, childAccessor: (item) => item.children })
    as the 
    dataSource
    prop. The first column must be 
    DataGrid.ColumnType.TREE
    (not 
    TEXT_BOX
    ) to render the expand/collapse control. 
    ArrayDataSource
    with manual indent does not support expand/collapse.
  • 层级数据使用
    TreeDataSource
    ：使用
    new TreeDataSource({ data: items, childAccessor: (item) => item.children })
    作为
    dataSource
    属性。第一列必须是
    DataGrid.ColumnType.TREE
    （不是
    TEXT_BOX
    ）才能渲染展开/折叠控件。使用
    ArrayDataSource
    手动缩进不支持展开/折叠。

Form Building

表单构建

  • Always wrap form controls in 
    Field
    for consistent label spacing, accessibility, and mandatory indicators; bare 
    TextBox
    + adjacent 
    Text
    label is not the correct pattern.
  • Field.Mode.VIEW
    renders the control as read-only display text; use for detail/view screens without creating separate read-only components.
  • FieldGroup
    collapses a logical group of fields with a section title; preferred over bare 
    StackPanel
    dividers for long forms.
  • RadioButtonGroup
    (not individual 
    RadioButton
    for groups) manages selection state automatically.
  • Field.Size
    full enum: 
    AUTO
    , 
    SMALL
    , 
    MEDIUM
    , 
    LARGE
    , 
    XLARGE
    , 
    XXLARGE
    , 
    STRETCH
    .
  • 始终将表单控件包裹在
    Field
    中以获得一致的标签间距、可访问性和必填标识；裸
    TextBox
    + 相邻
    Text
    标签不是正确的模式。
  • Field.Mode.VIEW
    将控件渲染为只读展示文本；用于详情/查看页面，无需创建单独的只读组件。
  • FieldGroup
    用章节标题折叠一组相关字段；对于长表单，优先于裸StackPanel分隔符使用。
  • RadioButtonGroup
    （而非单个
    RadioButton
    ）自动管理选择状态。
  • Field.Size
    完整枚举：
    AUTO
    、
    SMALL
    、
    MEDIUM
    、
    LARGE
    、
    XLARGE
    、
    XXLARGE
    、
    STRETCH
    。

User Feedback (Banner / Growl)

用户反馈（Banner / Growl）

  • GrowlPanel
    must be in the component tree; it is not a service call. Add it once in the root shell, obtain a ref to it, then call 
    .add(msg)
    (not 
    .addMessage()
    ) to push a 
    GrowlMessage
    .
  • Do not use 
    Modal
    for success/error feedback; use 
    GrowlMessage
    for transient feedback and 
    Banner
    for persistent inline alerts.
  • Banner
    is always visible until dismissed; 
    GrowlMessage
    auto-dismisses on a timer unless 
    manual={true}
    is set on the parent 
    GrowlPanel
    .
  • Banner.Color
    values: 
    BLUE
    (informational), 
    BLUE_DARK
    (emphasis), 
    GREEN
    (success), 
    ORANGE
    (warning).
  • GrowlPanel
    必须在组件树中；它不是服务调用。在根外壳中添加一次，获取其ref，然后调用
    .add(msg)
    （不是
    .addMessage()
    ）添加
    GrowlMessage
    。
  • 不要使用
    Modal
    进行成功/错误反馈；使用
    GrowlMessage
    进行临时反馈，使用
    Banner
    进行持久内联提示。
  • Banner
    始终可见直到被关闭；
    GrowlMessage
    会在计时器到期后自动关闭，除非父
    GrowlPanel
    设置了
    manual={true}
    。
  • Banner.Color
    值：
    BLUE
    （信息）、
    BLUE_DARK
    （强调）、
    GREEN
    （成功）、
    ORANGE
    （警告）。

FilterPanel

FilterPanel

  • FilterPanel.filters
    and 
    FilterPanel.filtersVisibilityToggle
    are deprecated; use 
    activeFilters
    + 
    showClearAll
    instead.
  • FilterChip
    requires a 
    picker
    prop (for example, 
    FilterChip.textBox
    , 
    FilterChip.date
    static pickers) to open the selection UI; without it the chip is display-only.
  • FilterPanel.filters
    和
    FilterPanel.filtersVisibilityToggle
    已废弃；使用
    activeFilters
    + 
    showClearAll
    替代。
  • FilterChip
    需要
    picker
    属性（例如
    FilterChip.textBox
    、
    FilterChip.date
    静态选择器）才能打开选择界面；没有该属性的话，芯片仅用于展示。

Immutable State Updates

不可变状态更新

  • Never mutate state directly; 
    state.items.push(x)
    does not trigger re-render; use 
    ImmutableArray.push(state.items, x)
    and pass the result to the state setter.
  • ImmutableObject.set(state, 'loading', true)
    is the correct pattern inside Store reducers; always return a new object, never 
    Object.assign(state, ...)
    .
  • 永远不要直接修改状态；
    state.items.push(x)
    不会触发重渲染；使用
    ImmutableArray.push(state.items, x)
    并将结果传递给状态设置器。
  • 在Store reducers中，
    ImmutableObject.set(state, 'loading', true)
    是正确的模式；始终返回新对象，永远不要使用
    Object.assign(state, ...)
    。

Component API Quick Reference – DataGrid

组件API快速参考 – DataGrid

DataGrid Props

DataGrid 属性

PropTypeDescription
dataSource
ArrayDataSourceData provider
columns
ColumnDefinition[]Column definitions
columnStretch
BooleanStretch columns to fill width (writable)
rootStyle
ObjectInline CSS on root element
dataRowHeight
Number (px)Row height (
rowHeight
is silently ignored)
highlightRowsOnHover
BooleanHover highlighting
maxViewportHeight
Number (px)Max height before internal scroll
maxViewportWidth
Number (px)Max width before horizontal scroll
editable
BooleanEnables cell editing (required for CHECK_BOX/DROPDOWN columns)
editingMode
CELL
, 
ROW
Cell vs row editing mode (constructor-only)
stripedRows
BooleanAlternating row stripes (constructor-only)
multiColumnSort
BooleanMulti-column sort support (constructor-only)
allowUnsort
BooleanAllow unsort back to natural order (constructor-only)
preload
ALL
, 
VISIBLE
, 
NONE
Virtualization preload strategy (constructor-only)
showHeader
BooleanShow/hide header row (writable)
placeholder
String or ComponentEmpty grid placeholder (writable)
paging
BooleanEnable pagination (writable)
pageSize
NumberRows per page (writable)
pageNumber
NumberCurrent page (writable)
sortable
BooleanEnable column sorting (writable)
onSort
SortCallbackSort event handler
属性类型描述
dataSource
ArrayDataSource数据提供器
columns
ColumnDefinition[]列定义
columnStretch
Boolean拉伸列以填满宽度（可写）
rootStyle
Object根元素的内联CSS
dataRowHeight
Number（px）行高（
rowHeight
会被静默忽略）
highlightRowsOnHover
Boolean悬停高亮
maxViewportHeight
Number（px）内部滚动前的最大高度
maxViewportWidth
Number（px）水平滚动前的最大宽度
editable
Boolean启用单元格编辑（CHECK_BOX/DROPDOWN列必填）
editingMode
CELL
、
ROW
单元格 vs 行编辑模式（仅构造函数可用）
stripedRows
Boolean交替行条纹（仅构造函数可用）
multiColumnSort
Boolean多列排序支持（仅构造函数可用）
allowUnsort
Boolean允许恢复到自然排序（仅构造函数可用）
preload
ALL
、
VISIBLE
、
NONE
虚拟化预加载策略（仅构造函数可用）
showHeader
Boolean显示/隐藏表头行（可写）
placeholder
String 或 Component空表格占位符（可写）
paging
Boolean启用分页（可写）
pageSize
Number每页行数（可写）
pageNumber
Number当前页码（可写）
sortable
Boolean启用列排序（可写）
onSort
SortCallback排序事件处理函数

DataGrid Column Definition

DataGrid 列定义

PropertyTypeDescription
name
StringColumn ID
type
ColumnType enumColumn type (TEXT_BOX, TEMPLATED, DROPDOWN, etc.)
binding
StringData field binding
label
StringHeader label
width
NumberInitial pixel width (also serves as proportional weight for stretch)
maxWidth
NumberMaximum pixel width (set to 9999 to allow stretch)
minWidth
NumberMinimum pixel width
editable
BooleanColumn-level editability
sortable
BooleanColumn-level sortability
content
CallbackTEMPLATED column render function: 
(args) => JSX
stretchFactor
NumberRelative stretch weight (alternative to width)
stretchable
BooleanWhether column participates in stretching
horizontalAlignment
LEFT
, 
CENTER
, 
RIGHT
, 
STRETCH
Cell content alignment
verticalAlignment
TOP
, 
CENTER
, 
BOTTOM
, 
STRETCH
Cell vertical alignment
inputMode
DEFAULT
, 
EDIT_ONLY
When editable widgets are shown
mandatory
BooleanMandatory field indicator
customizeCell
CallbackPer-cell customization function
visibility
VisibilityBreakpoint enumResponsive column visibility
属性类型描述
name
String列ID
type
ColumnType枚举列类型（TEXT_BOX、TEMPLATED、DROPDOWN等）
binding
String数据字段绑定
label
String表头标签
width
Number初始像素宽度（也作为拉伸的比例权重）
maxWidth
Number最大像素宽度（设置为9999以允许拉伸）
minWidth
Number最小像素宽度
editable
Boolean列级可编辑性
sortable
Boolean列级可排序性
content
CallbackTEMPLATED列的渲染函数：
(args) => JSX
stretchFactor
Number相对拉伸权重（替代width）
stretchable
Boolean列是否参与拉伸
horizontalAlignment
LEFT
、
CENTER
、
RIGHT
、
STRETCH
单元格内容对齐方式
verticalAlignment
TOP
、
CENTER
、
BOTTOM
、
STRETCH
单元格垂直对齐方式
inputMode
DEFAULT
、
EDIT_ONLY
可编辑小部件的显示时机
mandatory
Boolean必填字段标识
customizeCell
Callback单元格自定义函数
visibility
VisibilityBreakpoint枚举响应式列可见性

DataGrid Enumerations

DataGrid 枚举

EnumValuesAccess
DataGrid.ColumnType
ACTION
, 
CHECK_BOX
, 
DATE_PICKER
, 
DETAIL
, 
DROPDOWN
, 
GRAB
, 
LINK
, 
MULTI_SELECT_DROPDOWN
, 
SELECTION
, 
TEMPLATED
, 
TEXT_AREA
, 
TEXT_BOX
, 
TIME_PICKER
, 
TREE
Column 
type
prop
DataGrid.InputMode
DEFAULT
, 
EDIT_ONLY
Column/grid 
inputMode
DataGrid.EditingMode
CELL
, 
ROW
Grid 
editingMode
DataGrid.SortDirection
NONE
, 
ASCENDING
, 
DESCENDING
Column sort
DataGrid.CursorVisibility
FOCUS
, 
ALWAYS
Grid 
cursorVisibility
DataGrid.Preload
ALL
, 
VISIBLE
, 
NONE
Grid 
preload
DataGrid.VisualStyle
DEFAULT
, 
EMBEDDED
Grid visual style
DataGrid.RowSection
HEADER
, 
BODY
, 
FOOTER
Row pinning target
DataGrid.ColumnSection
LEFT
, 
BODY
, 
RIGHT
Column section
DataGrid.SizingStrategy
MANUAL
, 
INITIAL_WIDTH
Auto-size strategy
GridColumn.HorizontalAlignment
LEFT
, 
CENTER
, 
RIGHT
, 
STRETCH
Column alignment
GridColumn.VerticalAlignment
TOP
, 
CENTER
, 
BOTTOM
, 
STRETCH
Column vertical alignment
GridColumn.VisibilityBreakpoint
XX_SMALL
, 
X_SMALL
, 
SMALL
, 
MEDIUM
, 
LARGE
, 
X_LARGE
Responsive visibility
枚举值访问方式
DataGrid.ColumnType
ACTION
、
CHECK_BOX
、
DATE_PICKER
、
DETAIL
、
DROPDOWN
、
GRAB
、
LINK
、
MULTI_SELECT_DROPDOWN
、
SELECTION
、
TEMPLATED
、
TEXT_AREA
、
TEXT_BOX
、
TIME_PICKER
、
TREE
列
type
属性
DataGrid.InputMode
DEFAULT
、
EDIT_ONLY
列/表格
inputMode
DataGrid.EditingMode
CELL
、
ROW
表格
editingMode
DataGrid.SortDirection
NONE
、
ASCENDING
、
DESCENDING
列排序
DataGrid.CursorVisibility
FOCUS
、
ALWAYS
表格
cursorVisibility
DataGrid.Preload
ALL
、
VISIBLE
、
NONE
表格
preload
DataGrid.VisualStyle
DEFAULT
、
EMBEDDED
表格视觉样式
DataGrid.RowSection
HEADER
、
BODY
、
FOOTER
行固定目标区域
DataGrid.ColumnSection
LEFT
、
BODY
、
RIGHT
列区域
DataGrid.SizingStrategy
MANUAL
、
INITIAL_WIDTH
自动调整大小策略
GridColumn.HorizontalAlignment
LEFT
、
CENTER
、
RIGHT
、
STRETCH
列对齐方式
GridColumn.VerticalAlignment
TOP
、
CENTER
、
BOTTOM
、
STRETCH
列垂直对齐方式
GridColumn.VisibilityBreakpoint
XX_SMALL
、
X_SMALL
、
SMALL
、
MEDIUM
、
LARGE
、
X_LARGE
响应式可见性

DataGrid Events

DataGrid 事件

EventFires WhenAccess
DataGrid.Event.CELL_UPDATE
Cell value changes
on={{ [DataGrid.Event.CELL_UPDATE]: handler }}
DataGrid.Event.ROW_UPDATE
Row added/removed/movedRow lifecycle
DataGrid.Event.COLUMN_UPDATE
Column changesColumn lifecycle
DataGrid.Event.ROW_SELECTION_CHANGED
Row selection changesSelection tracking
DataGrid.Event.CURSOR_UPDATED
Cursor movesCursor tracking
DataGrid.Event.SORT
Sort direction changesSort handling
DataGrid.Event.SCROLLABILITY_CHANGED
Scroll state changedScroll tracking
DataGrid.Event.DATA_BOUND
Data binding complete (inherited)Data lifecycle
事件触发时机访问方式
DataGrid.Event.CELL_UPDATE
单元格值变化
on={{ [DataGrid.Event.CELL_UPDATE]: handler }}
DataGrid.Event.ROW_UPDATE
行添加/删除/移动行生命周期
DataGrid.Event.COLUMN_UPDATE
列变化列生命周期
DataGrid.Event.ROW_SELECTION_CHANGED
行选择变化选择跟踪
DataGrid.Event.CURSOR_UPDATED
光标移动光标跟踪
DataGrid.Event.SORT
排序方向变化排序处理
DataGrid.Event.SCROLLABILITY_CHANGED
滚动状态变化滚动跟踪
DataGrid.Event.DATA_BOUND
数据绑定完成（继承）数据生命周期