bitrix-ui

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Bitrix UI Library

Bitrix UI库

Modern admin and public interfaces use JS extensions from
ui
and
main
modules. Load via
Extension::load()
in PHP, import classes in modular JS.
现代后台界面和公共界面使用来自
ui
main
模块的JS扩展。在PHP中通过
Extension::load()
加载,在模块化JS中导入类。

Choosing a Component

组件选择

ScenarioExtension
Full modern dialog (title, content, custom layout)
ui.system.dialog
(
Dialog
) — preferred for new UI
Simple confirm / alert / message box
ui.dialogs.messagebox
(
MessageBox
)
Context/dropdown menu (modern)
ui.system.menu
Popup with custom positioning, legacy
main.popup
Slide-over panel (CRM-style)
main.sidepanel
Toast notifications
ui.notification
(
BX.UI.Notification.Center
)
Alerts/banners (inline UI alerts)
ui.alerts
Form inputs (modern)
ui.system.input
,
ui.system.label
,
ui.system.chip
Pick users/departments/custom entities
ui.entity-selector
(
Dialog
,
TagSelector
)
Data table: columns, sorting, paging, row actionsPHP component
bitrix:main.ui.grid
Search + filter fields with presets above a listPHP component
bitrix:main.ui.filter
Icons
ui.icon-set.api.core
+ per-set CSS extension
Loading skeleton
ui.system.skeleton
Hints/tooltips
ui.hint
Lottie animations
ui.lottie
Keyboard focus, focus trap, screen-reader live region
ui.a11y
使用场景扩展组件
完整的现代对话框(标题、内容、自定义布局)
ui.system.dialog
Dialog
)—— 新UI首选
简单确认/警告/消息框
ui.dialogs.messagebox
MessageBox
上下文/下拉菜单(现代版)
ui.system.menu
支持自定义定位的弹出层(旧版)
main.popup
滑入式面板(CRM风格)
main.sidepanel
提示通知框
ui.notification
BX.UI.Notification.Center
警告/横幅(内联UI提示)
ui.alerts
表单输入组件(现代版)
ui.system.input
ui.system.label
ui.system.chip
选择用户/部门/自定义实体
ui.entity-selector
Dialog
TagSelector
数据表格:列、排序、分页、行操作PHP组件
bitrix:main.ui.grid
列表上方的搜索+筛选字段(含预设)PHP组件
bitrix:main.ui.filter
图标
ui.icon-set.api.core
+ 对应图标集的CSS扩展
加载骨架屏
ui.system.skeleton
提示/工具提示
ui.hint
Lottie动画
ui.lottie
键盘焦点、焦点陷阱、屏幕阅读器实时区域
ui.a11y

ui.system.dialog
vs
ui.dialogs.messagebox

ui.system.dialog
vs
ui.dialogs.messagebox

  • ui.system.dialog
    — modern system
    Dialog
    component (structured dialog UI for new admin screens).
  • ui.dialogs.messagebox
    — classic
    MessageBox
    helpers (
    confirm
    ,
    alert
    ,
    show
    ) for quick confirmations. Use MessageBox for simple prompts, Dialog for richer UI.
There is no extension
ui.system.alert
— use
ui.alerts
.
  • ui.system.dialog
    —— 现代系统
    Dialog
    组件(为新后台页面设计的结构化对话框UI)。
  • ui.dialogs.messagebox
    —— 经典
    MessageBox
    辅助工具(
    confirm
    alert
    show
    ),用于快速确认操作。简单提示用MessageBox,复杂UI用Dialog。
不存在**
ui.system.alert
扩展,请使用
ui.alerts
**。

Loading Pattern

加载方式

php
\Bitrix\Main\UI\Extension::load(['ui.system.dialog', 'ui.alerts', 'ui.notification']);
javascript
import { Dialog } from 'ui.system.dialog';
import { MessageBox } from 'ui.dialogs.messagebox';
import { Alert, AlertColor } from 'ui.alerts';
// ui.notification is non-modular — use the global BX.UI.Notification.Center
Lazy-load in JS when needed:
Runtime.loadExtension('ui.entity-selector').then((exports) => { ... })
.
php
\Bitrix\Main\UI\Extension::load(['ui.system.dialog', 'ui.alerts', 'ui.notification']);
javascript
import { Dialog } from 'ui.system.dialog';
import { MessageBox } from 'ui.dialogs.messagebox';
import { Alert, AlertColor } from 'ui.alerts';
// ui.notification为非模块化组件 —— 使用全局对象BX.UI.Notification.Center
按需延迟加载JS扩展:
Runtime.loadExtension('ui.entity-selector').then((exports) => { ... })

System Dialog / Message Box / Alerts

系统对话框/消息框/警告组件

javascript
import { Dialog } from 'ui.system.dialog';
new Dialog({ title: 'Settings', content: contentNode /* HTMLElement */, rightButtons: [...] }).show();
// other options: subtitle, hasCloseButton, hasOverlay, closeByEsc, closeByClickOutside, width, background

import { MessageBox } from 'ui.dialogs.messagebox';
MessageBox.confirm('Delete item?', () => { /* on confirm */ });
MessageBox.alert('Done');

import { Alert, AlertColor } from 'ui.alerts';
const alert = new Alert({ text: 'Saved', color: AlertColor.SUCCESS });
javascript
import { Dialog } from 'ui.system.dialog';
new Dialog({ title: '设置', content: contentNode /* HTMLElement */, rightButtons: [...] }).show();
// 其他配置项:subtitle、hasCloseButton、hasOverlay、closeByEsc、closeByClickOutside、width、background

import { MessageBox } from 'ui.dialogs.messagebox';
MessageBox.confirm('确定删除该项目?', () => { /* 确认后的操作 */ });
MessageBox.alert('操作完成');

import { Alert, AlertColor } from 'ui.alerts';
const alert = new Alert({ text: '已保存', color: AlertColor.SUCCESS });

Popup (legacy/base) and Side Panel

弹出层(旧版/基础版)和侧边面板

javascript
import { Popup } from 'main.popup';
new Popup({ id: 'my-popup', content: 'Saved', closeIcon: true }).show();

// main.sidepanel:
BX.SidePanel.Instance.open('/local/admin/custom-page.php', { width: 800, cacheable: false });
javascript
import { Popup } from 'main.popup';
new Popup({ id: 'my-popup', content: '已保存', closeIcon: true }).show();

// main.sidepanel用法:
BX.SidePanel.Instance.open('/local/admin/custom-page.php', { width: 800, cacheable: false });

Notifications (toasts)

提示通知(Toast)

Extension
ui.notification
(global API, no ES exports):
javascript
BX.UI.Notification.Center.notify({ content: 'Saved', autoHide: true, autoHideDelay: 8000, position: 'top-right' });
Do not confuse with
ui.notification-manager
— a separate extension (
Notification
,
Notifier
in
BX.UI.NotificationManager
) for cross-tab/desktop notifications with categories and buttons, not for simple toasts.
扩展组件
ui.notification
(全局API,无ES导出):
javascript
BX.UI.Notification.Center.notify({ content: '已保存', autoHide: true, autoHideDelay: 8000, position: 'top-right' });
请勿与
ui.notification-manager
混淆——这是一个独立扩展(
BX.UI.NotificationManager
中的
Notification
Notifier
),用于跨标签页/桌面通知,支持分类和按钮,不适用于简单Toast提示。

Entity Selector (
ui.entity-selector
)

实体选择器(
ui.entity-selector

Two widgets:
Dialog
(popup picker) and
TagSelector
(field showing selected items as tags). Items are identified by the pair
entityId
+
id
; minimal local item:
{ id, entityId, title }
.
javascript
import { Dialog, TagSelector } from 'ui.entity-selector';

const dialog = new Dialog({
    targetNode: button,              // must be an existing DOM node
    context: 'MY_MODULE_RESPONSIBLE', // separate context per form — recent items don't mix
    multiple: false,
    enableSearch: true,
    entities: [{ id: 'user' }, { id: 'department' }], // server-side load via PHP providers
    events: { 'Item:onSelect': (e) => { const { item } = e.getData(); } },
});
button.addEventListener('click', () => dialog.show());
TagSelector
with a linked dialog: pass
dialogOptions
(same options as
Dialog
);
preselectedItems: [['user', 1]]
loads selected items from the server; render with
selector.renderTo(container)
.
Provider entity ids come from installed modules — each registers them in its
.settings.php
under the
ui.entity-selector
key (e.g.
iblock-element
from iblock,
product
/
store
from catalog). Bitrix24 modules (intranet/socialnetwork/im) add
user
,
department
,
project
,
meta-user
,
im-chat
etc. Check the target module's
.settings.php
for the exact id before using it.
Custom provider — PHP class extending
Bitrix\UI\EntitySelector\BaseProvider
(implement
isAvailable()
— must check rights,
getItems()
; optionally
fillDialog()
,
doSearch()
), registered in module
.settings.php
:
php
'ui.entity-selector' => [
    'value' => [
        'entities' => [[
            'entityId' => 'project',
            'provider' => ['moduleId' => 'my.module', 'className' => ProjectProvider::class],
        ]],
    ],
    'readonly' => true,
],
Rules:
entities[].id
in JS must equal the registered
entityId
;
dynamicLoad
/
dynamicSearch
only work when a PHP provider is registered and available.
包含两个组件:
Dialog
(弹出选择器)和
TagSelector
(以标签形式展示已选项目的字段)。项目通过
entityId
+
id
的组合标识;最简本地项目格式:
{ id, entityId, title }
javascript
import { Dialog, TagSelector } from 'ui.entity-selector';

const dialog = new Dialog({
    targetNode: button,              // 必须是已存在的DOM节点
    context: 'MY_MODULE_RESPONSIBLE', // 每个表单使用独立上下文——避免最近选择项混淆
    multiple: false,
    enableSearch: true,
    entities: [{ id: 'user' }, { id: 'department' }], // 通过PHP提供者从服务端加载
    events: { 'Item:onSelect': (e) => { const { item } = e.getData(); } },
});
button.addEventListener('click', () => dialog.show());
关联对话框的
TagSelector
:传入
dialogOptions
(与
Dialog
相同的配置项);
preselectedItems: [['user', 1]]
从服务端加载已选项目;通过
selector.renderTo(container)
渲染。
提供者实体ID来自已安装的模块——每个模块会在其
.settings.php
ui.entity-selector
键下注册实体ID(例如iblock模块的
iblock-element
,catalog模块的
product
/
store
)。Bitrix24模块(intranet/socialnetwork/im)会添加
user
department
project
meta-user
im-chat
等。使用前请查看目标模块的
.settings.php
获取准确ID。
自定义提供者——继承
Bitrix\UI\EntitySelector\BaseProvider
的PHP类(实现
isAvailable()
——必须检查权限,
getItems()
;可选实现
fillDialog()
doSearch()
),在模块
.settings.php
中注册:
php
'ui.entity-selector' => [
    'value' => [
        'entities' => [[
            'entityId' => 'project',
            'provider' => ['moduleId' => 'my.module', 'className' => ProjectProvider::class],
        ]],
    ],
    'readonly' => true,
],
规则:JS中的
entities[].id
必须与注册的
entityId
一致;仅当PHP提供者已注册且可用时,
dynamicLoad
/
dynamicSearch
才能生效。

Grid and Filter (
main.ui.grid
/
main.ui.filter
)

表格与筛选器(
main.ui.grid
/
main.ui.filter

PHP components for admin-style lists. They render UI and store user settings only — your server code fetches, filters, sorts and limits the data before
IncludeComponent()
. To link filter with grid, pass the same id to
FILTER_ID
and
GRID_ID
.
php
use Bitrix\Main\UI\Filter\Options as FilterOptions;
use Bitrix\Main\Grid\Options as GridOptions;

$gridId = 'orders_grid';
$filterFields = [
    ['id' => 'FIND', 'name' => 'Search'],
    ['id' => 'STATUS', 'name' => 'Status', 'type' => 'list', 'items' => ['' => 'Any', 'new' => 'New']],
];
$filter = (new FilterOptions($gridId))->getFilter($filterFields); // user values
$sorting = (new GridOptions($gridId))->getSorting(['sort' => ['ID' => 'desc']]);
// build $ormFilter from $filter, run query with $sorting['sort'], build $rows

$APPLICATION->IncludeComponent('bitrix:main.ui.filter', '', [
    'FILTER_ID' => $gridId, 'GRID_ID' => $gridId, 'FILTER' => $filterFields, 'ENABLE_LABEL' => true,
]);
$APPLICATION->IncludeComponent('bitrix:main.ui.grid', '', [
    'GRID_ID' => $gridId,
    'COLUMNS' => [['id' => 'ID', 'name' => 'ID', 'sort' => 'ID', 'default' => true]],
    'ROWS' => $rows,        // each: ['id' => 42, 'data' => [...], 'actions' => [...]]
    'SORT' => $sorting['sort'], 'ALLOW_SORT' => true,
    'AJAX_MODE' => 'Y', 'AJAX_OPTION_JUMP' => 'N', 'AJAX_OPTION_HISTORY' => 'N',
]);
  • Filter field types:
    string
    ,
    textarea
    ,
    list
    (multiple via
    params.multiple = 'Y'
    ),
    number
    ,
    date
    (
    time => true
    for datetime; hide subtypes via
    exclude
    +
    Bitrix\Main\UI\Filter\DateType::*
    ),
    custom_date
    ,
    entity_selector
    (dialog options in
    params.dialogOptions
    ;
    params.addEntityIdToResult = 'Y'
    when several entity types share one field). Prefer
    entity_selector
    over legacy
    dest_selector
    /
    custom_entity
    in new UI. Ranges return suffixed keys:
    _from
    ,
    _to
    ,
    _datesel
    ,
    _numsel
    .
  • Presets:
    FILTER_PRESETS => ['key' => ['name' => ..., 'fields' => [...], 'default' => true]]
    . Settings are stored by
    FILTER_ID
    /
    GRID_ID
    — changing the id loses saved user presets/columns.
  • Pagination:
    Bitrix\Main\UI\PageNavigation
    in
    NAV_OBJECT
    +
    TOTAL_ROWS_COUNT
    ; apply
    $nav->getLimit()/getOffset()
    to the query yourself. Pass
    PAGE_SIZES
    /
    SHOW_PAGESIZE
    /
    SHOW_PAGINATION
    when the list is paged.
  • Columns: use
    COLUMNS
    in new code (
    HEADERS
    is compatibility-only).
    ROW_LAYOUT
    disables column/row sorting. Row HTML goes into
    ROWS[]['columns']
    — escape user data with
    HtmlFilter::encode()
    .
  • Group actions:
    ACTION_PANEL
    +
    SHOW_ROW_CHECKBOXES
    /
    SHOW_ACTION_PANEL
    /
    SHOW_SELECTED_COUNTER
    . Re-check rights server-side.
  • For module-level grids with a
    Bitrix\Main\Grid\Grid
    subclass, pass
    ComponentParams::get($grid)
    (from
    Bitrix\Main\Grid\Component\ComponentParams
    ) as component params. A dedicated
    Bitrix\Main\Filter\Filter
    + provider is optional;
    FilterOptions::getFilter()
    is enough for a plain component page.
用于后台风格列表的PHP组件。它们仅负责渲染UI和存储用户设置——服务端代码需在
IncludeComponent()
之前完成数据的获取、筛选、排序和分页限制
。要关联筛选器和表格,需为
FILTER_ID
GRID_ID
传入相同的ID
php
use Bitrix\Main\UI\Filter\Options as FilterOptions;
use Bitrix\Main\Grid\Options as GridOptions;

$gridId = 'orders_grid';
$filterFields = [
    ['id' => 'FIND', 'name' => '搜索'],
    ['id' => 'STATUS', 'name' => '状态', 'type' => 'list', 'items' => ['' => '全部', 'new' => '新建']],
];
$filter = (new FilterOptions($gridId))->getFilter($filterFields); // 用户输入的筛选值
$sorting = (new GridOptions($gridId))->getSorting(['sort' => ['ID' => 'desc']]);
// 根据$filter构建$ormFilter,结合$sorting['sort']执行查询,构建$rows

$APPLICATION->IncludeComponent('bitrix:main.ui.filter', '', [
    'FILTER_ID' => $gridId, 'GRID_ID' => $gridId, 'FILTER' => $filterFields, 'ENABLE_LABEL' => true,
]);
$APPLICATION->IncludeComponent('bitrix:main.ui.grid', '', [
    'GRID_ID' => $gridId,
    'COLUMNS' => [['id' => 'ID', 'name' => 'ID', 'sort' => 'ID', 'default' => true]],
    'ROWS' => $rows,        // 每条数据格式:['id' => 42, 'data' => [...], 'actions' => [...]]
    'SORT' => $sorting['sort'], 'ALLOW_SORT' => true,
    'AJAX_MODE' => 'Y', 'AJAX_OPTION_JUMP' => 'N', 'AJAX_OPTION_HISTORY' => 'N',
]);
  • 筛选器字段类型:
    string
    textarea
    list
    (通过
    params.multiple = 'Y'
    支持多选)、
    number
    date
    time => true
    支持日期时间;通过
    exclude
    +
    Bitrix\Main\UI\Filter\DateType::*
    隐藏子类型)、
    custom_date
    entity_selector
    (对话框配置项在
    params.dialogOptions
    中;当多个实体类型共享一个字段时,设置
    params.addEntityIdToResult = 'Y'
    )。新UI中优先使用
    entity_selector
    ,而非旧版的
    dest_selector
    /
    custom_entity
    。范围筛选会返回带后缀的键:
    _from
    _to
    _datesel
    _numsel
  • 预设:
    FILTER_PRESETS => ['key' => ['name' => ..., 'fields' => [...], 'default' => true]]
    。设置信息通过
    FILTER_ID
    /
    GRID_ID
    存储——修改ID会导致用户保存的预设/列配置丢失。
  • 分页:在
    NAV_OBJECT
    中使用
    Bitrix\Main\UI\PageNavigation
    +
    TOTAL_ROWS_COUNT
    ;需自行将
    $nav->getLimit()/getOffset()
    应用到查询中。当列表支持分页时,传入
    PAGE_SIZES
    /
    SHOW_PAGESIZE
    /
    SHOW_PAGINATION
  • 列:新代码中使用
    COLUMNS
    HEADERS
    仅用于兼容)。
    ROW_LAYOUT
    会禁用列/行排序。行HTML需放入
    ROWS[]['columns']
    中——使用
    HtmlFilter::encode()
    转义用户数据。
  • 批量操作:
    ACTION_PANEL
    +
    SHOW_ROW_CHECKBOXES
    /
    SHOW_ACTION_PANEL
    /
    SHOW_SELECTED_COUNTER
    。服务端需重新检查权限。
  • 对于使用
    Bitrix\Main\Grid\Grid
    子类的模块级表格,传入
    ComponentParams::get($grid)
    (来自
    Bitrix\Main\Grid\Component\ComponentParams
    )作为组件参数。专用的
    Bitrix\Main\Filter\Filter
    + 提供者为可选;普通组件页面使用
    FilterOptions::getFilter()
    即可。

Lottie (
ui.lottie
)

Lottie动画(
ui.lottie

Based on Lottie 5.13 (
import { Lottie } from 'ui.lottie'
or global
BX.UI.Lottie
):
javascript
const animation = BX.UI.Lottie.loadAnimation({
    container: node,                 // must exist in DOM
    path: '/local/assets/loader.json', // or animationData: {...} — pass one source
    renderer: 'svg', loop: true, autoplay: true,
});
Returns an
AnimationItem
:
play()
,
stop()
,
pause()
,
togglePause()
,
setSpeed()
,
setDirection()
,
goToAndStop()
,
goToAndPlay()
,
destroy()
(call on teardown). Optional
name
lets you call
BX.UI.Lottie.play(name)
later. Events via
animation.addEventListener('complete' | 'loopComplete' | 'data_ready' | 'data_failed' | 'DOMLoaded' | 'destroy', ...)
.
基于Lottie 5.13版本(可通过
import { Lottie } from 'ui.lottie'
导入,或使用全局对象
BX.UI.Lottie
):
javascript
const animation = BX.UI.Lottie.loadAnimation({
    container: node,                 // 必须已存在于DOM中
    path: '/local/assets/loader.json', // 或传入animationData: {...} —— 二选一
    renderer: 'svg', loop: true, autoplay: true,
});
返回
AnimationItem
对象,支持方法:
play()
stop()
pause()
togglePause()
setSpeed()
setDirection()
goToAndStop()
goToAndPlay()
destroy()
(组件销毁时需调用)。可选的
name
参数可用于后续调用
BX.UI.Lottie.play(name)
。通过
animation.addEventListener('complete' | 'loopComplete' | 'data_ready' | 'data_failed' | 'DOMLoaded' | 'destroy', ...)
监听事件。

Accessibility (
ui.a11y
)

无障碍访问(
ui.a11y

Use when a dialog, menu, or live UI must keep keyboard focus or announce changes to a screen reader. Load
ui.a11y
(
FocusMonitor.initialize()
runs on import).
NeedClass
Restore focus after close / DOM redraw
FocusMonitor
Move focus to the next/previous focusable node
FocusNavigator
Trap Tab inside a modal/dialog
FocusTrap
Arrow / Home / End keys inside a widget
FocusZone
Keyboard vs mouse vs touch vs stylus
InputModalityTracker
Is the node visible / enabled / focusable
InteractivityChecker
Speak a message without moving focus
LiveAnnouncer
Visually hide, keep for AT
VisuallyHidden
javascript
import { FocusTrap, LiveAnnouncer } from 'ui.a11y';

const trap = new FocusTrap(dialogNode);
trap.activate();
// on close:
trap.deactivate();

LiveAnnouncer.announce('Saved', 'polite'); // or 'assertive'
Optional kernel config (
Configuration::getValue('ui')['a11y']
in the extension
config.php
):
php
'ui' => [
    'value' => [
        'a11y' => [
            'restoreLostFocus' => true,
            'useFocusTrapInDialogs' => true,
        ],
    ],
    'readonly' => false,
],
On a regular product install both flags default to
false
(they default to
true
only when
\Dev\Main\Migrator\ModuleUpdater
exists). Do not assume traps are on globally — activate
FocusTrap
in your dialog.
当对话框、菜单或动态UI需要保持键盘焦点,或需向屏幕阅读器播报变更时使用。加载
ui.a11y
(导入时会自动执行
FocusMonitor.initialize()
)。
需求
关闭/重绘DOM后恢复焦点
FocusMonitor
将焦点移动到下一个/上一个可聚焦节点
FocusNavigator
在模态框/对话框中捕获Tab键
FocusTrap
组件内支持方向键/Home/End键
FocusZone
区分输入方式:键盘/鼠标/触摸/手写笔
InputModalityTracker
判断节点是否可见/启用/可聚焦
InteractivityChecker
播报消息但不移动焦点
LiveAnnouncer
视觉隐藏但保留给辅助技术
VisuallyHidden
javascript
import { FocusTrap, LiveAnnouncer } from 'ui.a11y';

const trap = new FocusTrap(dialogNode);
trap.activate();
// 关闭时:
trap.deactivate();

LiveAnnouncer.announce('已保存', 'polite'); // 或使用'assertive'
可选内核配置(扩展
config.php
中的
Configuration::getValue('ui')['a11y']
):
php
'ui' => [
    'value' => [
        'a11y' => [
            'restoreLostFocus' => true,
            'useFocusTrapInDialogs' => true,
        ],
    ],
    'readonly' => false,
],
常规产品安装时,两个标志默认均为
false
(仅当
\Dev\Main\Migrator\ModuleUpdater
存在时默认设为
true
)。请勿假设全局
ui.a11y
标志已开启——需在你的对话框中主动激活
FocusTrap

Icons (
ui.icon-set
)

图标(
ui.icon-set

JS API is
ui.icon-set.api.core
(class
Icon
+ name sets); each set also needs its CSS extension loaded, or the icon won't render. Sets (exported from
ui.icon-set.api.core
):
Actions
,
Main
,
Outline
,
Solid
,
Social
,
CRM
,
Editor
,
ContactCenter
,
Animated
,
Special
,
Disk
/
DiskCompact
(fixed colors,
color
ignored),
SmallOutline
— CSS extensions
ui.icon-set.actions
,
ui.icon-set.main
,
ui.icon-set.outline
, etc.
javascript
import { Icon, Outline, IconHoverMode } from 'ui.icon-set.api.core';
import 'ui.icon-set.outline';

new Icon({ icon: Outline.CHECK_L, size: 24, color: 'var(--ui-color-base-70)' }).renderTo(container);
  • Vue:
    BIcon
    from
    ui.icon-set.api.vue
    (props
    name
    ,
    size
    ,
    color
    ,
    hoverable
    ,
    responsive
    ).
  • Static HTML (no JS control):
    <div class="ui-icon-set --check-l"></div>
    ; size/color via CSS vars
    --ui-icon-set__icon-size
    ,
    --ui-icon-set__icon-color
    .
  • Use named icons from the sets, not inline SVG copies. Load
    ui.design-tokens
    / typography extensions for consistent styling.
JS API为
ui.icon-set.api.core
(包含
Icon
类和图标集);每个图标集还需加载对应的CSS扩展,否则图标无法渲染。可用图标集(从
ui.icon-set.api.core
导出):
Actions
Main
Outline
Solid
Social
CRM
Editor
ContactCenter
Animated
Special
Disk
/
DiskCompact
(固定颜色,
color
参数无效)、
SmallOutline
——对应的CSS扩展为
ui.icon-set.actions
ui.icon-set.main
ui.icon-set.outline
等。
javascript
import { Icon, Outline, IconHoverMode } from 'ui.icon-set.api.core';
import 'ui.icon-set.outline';

new Icon({ icon: Outline.CHECK_L, size: 24, color: 'var(--ui-color-base-70)' }).renderTo(container);
  • Vue框架:使用
    ui.icon-set.api.vue
    中的
    BIcon
    (属性包括
    name
    size
    color
    hoverable
    responsive
    )。
  • 静态HTML(无需JS控制):
    <div class="ui-icon-set --check-l"></div>
    ;通过CSS变量
    --ui-icon-set__icon-size
    --ui-icon-set__icon-color
    设置尺寸/颜色。
  • 使用图标集中的命名图标,而非内联SVG副本。加载
    ui.design-tokens
    / 排版扩展以保持样式一致性。

Checklist

检查清单

  • Prefer
    ui.system.dialog
    /
    ui.system.*
    over legacy
    main.popup
    for new admin UI;
    ui.dialogs.messagebox
    for simple confirms.
  • Alerts via
    ui.alerts
    , not a non-existent
    ui.system.alert
    .
  • Extensions loaded in PHP before inline scripts; modular JS uses
    import
    , not global
    BX
    where avoidable.
  • Entity selector:
    entities[].id
    matches the registered provider
    entityId
    ; provider
    isAvailable()
    checks rights; distinct
    context
    per form.
  • Grid/filter share one
    GRID_ID
    ; server code applies filter, sort and nav limits itself; row HTML escaped via
    HtmlFilter::encode()
    .
  • Icons:
    ui.icon-set.api.core
    plus the set's CSS extension (e.g.
    ui.icon-set.outline
    ) — both loaded.
  • Lottie instances
    destroy()
    ed on teardown; side panel URLs are real routes with proper auth.
  • Dialogs/menus that steal focus use
    ui.a11y
    (
    FocusTrap
    /
    LiveAnnouncer
    ); do not assume global
    ui.a11y
    flags are on.
  • Notifications for transient feedback, dialogs/message boxes for confirmations.
  • 新后台UI优先使用
    ui.system.dialog
    /
    ui.system.*
    ,而非旧版
    main.popup
    ;简单确认操作使用
    ui.dialogs.messagebox
  • 使用
    ui.alerts
    实现警告功能,而非不存在的
    ui.system.alert
  • 内联脚本执行前在PHP中加载扩展;模块化JS优先使用
    import
    ,避免全局
    BX
    对象(除非必要)。
  • 实体选择器:
    entities[].id
    需与注册的提供者
    entityId
    匹配;提供者
    isAvailable()
    需检查权限;每个表单使用独立的
    context
  • 表格/筛选器使用相同的
    GRID_ID
    ;服务端代码自行应用筛选、排序和分页限制;行HTML通过
    HtmlFilter::encode()
    转义。
  • 图标:同时加载
    ui.icon-set.api.core
    和对应图标集的CSS扩展(例如
    ui.icon-set.outline
    )。
  • Lottie实例在组件销毁时调用
    destroy()
    ;侧边面板URL为带正确权限校验的真实路由。
  • 抢占焦点的对话框/菜单使用
    ui.a11y
    FocusTrap
    /
    LiveAnnouncer
    );请勿假设全局
    ui.a11y
    标志已开启。
  • 临时反馈使用通知组件,确认操作使用对话框/消息框。