Acme Harmony UI Design System
Components / Data Entry

表单与选择器组件 (Forms & Selectors)

规范了输入框规格、表单排版,以及核心高级选择器组件(人员选择器 selUser、人员树 userTree、字典选择器 selSysDic)和 DataBinder 自动绑定的调用规范与 API 协议。

组件源文件: Views/Components/Common/selUser.cshtml 最后更新: 2026-05-28
01 / Specification

基本表单控件与色彩规范

所有输入控件继承自 Bootstrap 4.5 样式系统并经过美化。基本规格参数强制如下:


1. 输入控件规格 (Inputs & Controls)

控件类型 高度 / 字号 / 圆角 默认与交互状态 工程标准与设计红线
文本与数字
input[type="text"]
高度: 42px (弹窗)
高度: 34px (工具栏)
字号: 13px
圆角: 4px
边框: #d7e1db
底色: #ffffff
Focus 时必须展示 border-color: #8ec6a7; box-shadow: 0 0 0 3px rgba(63,143,104,0.12);。禁止在弹窗内不做高度区分。
多行文本域
textarea
高度: 自适应 (rows)
字号: 13px
圆角: 4px
与文本框一致 Focus 时聚焦样式与文本框保持一致。大篇幅录入时强制使用该组件。
普通选择器
select
高度: 42px / 34px
字号: 13px
圆角: 4px
与文本框一致 原生或美化的 select 组件。注意在禁用状态下箭头样式应正确置灰。
单选与复选框
checkbox / radio
尺寸: 16px * 16px
字号: 13px
激活: #41b584 (主色)
焦点: 翡翠绿光圈
选中态背景色必须为 Acme 翡翠绿。禁止使用浏览器默认深蓝色样式。
只读与禁用
[readonly] [disabled]
- 只读: #f4f7f5 底色
禁用: #eef2f0 底色/置灰
只读字段必须允许用户双击复制;禁用字段必须从 tab 键焦距中剔除并带 not-allowed 指针。两者必须从视觉上清晰区分。
错误状态
.is-invalid
- 边框: #ef4444 (危险红)
底色: #fef2f2
错误状态下必须在控件正下方直接输出 .invalid-feedback 提示文字。禁止使用全局 alert 框打断流程。

2. 标签与辅助信息规范 (Labels & Descriptions)

元素与样式类 字号 / 字重 / 间距 颜色规范 工程标准与设计红线
表单标签
label
字号: 13px
字重: 600
下边距: 6px
--acme-color-text-main
(#1e293b)
主文本深色。标签必须直接在输入框上方对齐,禁止在非窄小场景使用左右分栏且不设对齐。
必填标签
.required-field
在文本后自动添加 *
字重: bold
星号: #ef4444 红星标记必须由样式自动生成。禁止开发人员手工在 HTML 中拼写 <span style="color:red">*</span>
辅助说明文字
small.form-text
字号: 12px / 11px
上边距: 4px
--acme-color-text-sub
(#475569)
用于输入规范说明。说明文字必须简明扼要,控制在单行,超长时须考虑浮动 Tooltip 解决。
校验错误提示
.invalid-feedback
字号: 12px
上边距: 4px
颜色: #ef4444 在输入框下方展现。该文本只有在输入框含有 is-invalid 状态时才会被激活显示。

3. 文本与状态颜色规范 (Text & State Colors)

色彩类别 / 类名 HSL/Hex 变量值 设计语义 主要适用范围
一级文本
.text-main
#1e293b 高对比正文、主标题 主要标题、正文叙述、表单标签、输入框填入文字、重要数字指标。
二级文本
.text-sub
#475569 次要文本、卡片描述 输入框 Helper 辅助文本、卡片说明段落、次级字段标签。
弱辅助文本
.text-muted
#94a3b8 占位符、置灰禁用 输入框 placeholder、禁用控件文本、底部超轻 Meta 版权说明。
品牌主色
.text-primary
#41b584 (翡翠绿) 品牌标志、关键文字 高亮超链接、正向标签分类字、状态栏激活标记。
成功状态色
.text-success
#10b981 (正绿) 校验成功、完成 数据提交成功提示、审批通过状态、表单验证成功的绿色提示。
警告状态色
.text-warning
#f59e0b (橙黄) 注意、挂起、提醒 操作风险提示、流程中止或审批挂起说明、非常规输入边界警告。
错误状态色
.text-danger
#ef4444 (危险红) 校验失败、核心风险 必填校验未通过提示、后台接口请求失败提示、强制阻断提示。
信息提示色
.text-info
#3b82f6 (提示蓝) 系统说明、指南 表单填写小助手指南、操作提示弹窗内的详细解读文本。
实时控件与样式调试 (Basic Controls Playground)
Live Preview

状态控制面板

这是一个常规辅助提示信息 (Helper text)
文字/状态颜色效果实时预览 (Color Tester):

Harmony UI 系统预设文本颜色。点击左侧下拉框切换不同颜色样式,在这里实时观察渲染对比度和视觉美感。

当前控件参数详情 (Inspect):
当前控件类型 (type): text
高度 (height): 42px
字号 (font-size): 13px
圆角 (border-radius): 4px
边框颜色 (border-color): #d7e1db
背景底色 (background-color): #ffffff
文字颜色 (color): #1e293b
02 / Selector: selUser

核心人员选择器 (selUser)

企业级核心组件。支持多选/单选人员、所属部门、关联标签的高级树表弹窗选择器。适用于一切“分配人员”、“设定负责人”、“选择抄送”场景。


1. 组件定位与引入

源码视图: Views/Components/Common/selUser.cshtml 专用样式: wwwroot/css/components/selUser.css 调试范例: Views/Components/Common/selUserExample.cshtml

引入语法 (Razor):必须通过 ViewDataDictionary 传递组件的属性,否则在局部页面中将无法正确绑定上下文参数:

index.cshtml Razor
@await Html.PartialAsync("~/Views/Components/Common/selUser.cshtml", new ViewDataDictionary(ViewData)
{
    { "inputId", "myAuditorSelect" },
    { "allowMultiple", true },
    { "showDepartment", true },
    { "showTag", true },
    { "placeholder", "请选择审计人员" },
    { "callback", "onAuditorSelected" },
    { "displayMode", "modal" },
    { "personIdSource", "userId" }
})
实时运行与配置演示 (Interactive Playground)
Real Component

参数调整

注:切换模式时,页面会即时动态切换已预渲染的具有对应配置的组件实例。

选择结果输出:
// 确认选择后,回调 JSON 结果将在此处解析展示

参数 API 详解 (Parameters)

参数名 类型 必填 默认值 详细功能与规范说明
inputId String - 组件实例 ID,在 DOM 中生成隐藏字段及相关搜索组件的 ID 前缀。
allowMultiple Boolean true 是否允许多选人员。设为 false 则变为单选穿梭。
showDepartment Boolean true 是否在左侧面板展示部门组织树。
showTag Boolean true 是否展示自定义用户标签(如“财务审计员”、“运维技术骨干”)。
placeholder String '请选择' 选择输入框的提示文案。
callback String - **核心参数**。点击确定后触发的全局 JS 回调函数名称(字符串)。
displayMode String 'modal' 展现模式。可选 'modal' (弹窗穿梭) 或 'embedded' (页面内嵌折叠)。
personIdSource String 'userId' 数据源的主键映射。可选 'userId' (用户表 ID) 或 'empId' (员工档案 ID)。

内部 DOM 约定与后端 API

组件会在运行时渲染出以下 DOM 节点,在进行表单校验或数据重置时需要直接操作它们:

  • 数据隐藏字段#myAuditorSelect_json。存放所有选中人员完整 JSON 数组的隐藏文本域。表单提交时,后台直接解析此文本域!
  • 搜索输入框#myAuditorSelect_userSearchInput
  • 组织树容器#myAuditorSelect_deptTreeContainer
  • 组织人员接口/api/personnel/department-with-user-tree/1 (获取部门组织及下属用户树)。
  • 标签接口/api/personnel/tag-list (获取人员标签)。

确认回调参数与输出数据结构

callback.js JavaScript
// 绑定在 callback 参数中的 JS 函数结构
function onAuditorSelected(selectedItems) {
    console.log("选中的数据集:", selectedItems);
    /* 
    selectedItems 数据结构为数组,每个成员如下:
    [
        {
            type: "person",          // 支持类型: person (人员), department (部门), tag (标签组)
            id: "U10024",            // 根据 personIdSource 决定的 ID 值
            name: "陈彪",            // 人员姓名或部门名
            departmentName: "IT部",   // 所属部门
            avatar: "..."            // 头像相对路径
        }
    ]
    */
    // 典型业务:更新 UI
    if(selectedItems.length > 0) {
        $("#auditorCountLabel").text(selectedItems.length + "人已指定");
    }
}
03 / Selector: userTree

极简人员选择树 (userTree)

轻量级人员选择组件。适用于“单选单个人员”、“无需标签过滤”、“空间高度受限”的快速流程派发场景。


1. 组件定位与引入

源码视图: Views/Components/Common/userTree.cshtml

引入语法 (Razor):必须通过 ViewDataDictionary 传递组件的属性,否则在局部页面中将无法正确绑定上下文参数:

index.cshtml Razor
@await Html.PartialAsync("~/Views/Components/Common/userTree.cshtml", new ViewDataDictionary(ViewData)
{
    { "inputId", "myDirectReportTree" },
    { "placeholder", "请指派直接下属" },
    { "height", 300 },
    { "callback", "onReportTreeSelected" }
})
实时运行与配置演示 (Interactive Playground)
Real Component

实例控制 API

利用暴露在 window 上的全局方法,可通过外部 JS 代码动态操纵选择器的行为:

思考中...
选择结果输出:
// 选中人员节点后,回调参数将在此处即时呈现

参数 API 详解 (Parameters)

参数名 类型 必填 详细功能与规范说明
inputId String 组件实例 ID,作为 jsTree 生成的唯一节点前缀。
placeholder String 输入框占位符文本。
height Number 树容器最大限制高度,默认 300px
callback String 点击人员节点触发的回调函数名称(参数为选中的人员 ID 及名称)。
04 / Selector: selSysDic

系统字典与数据源选择器 (selSysDic)

统一配置映射组件。适用于为 Select/Select2/Checkbox/Radio 绑定字典配置数据、系统运行枚举或基础数据(如省市区、币种),杜绝手写硬编码。


1. 组件定位与引入

源码视图: Views/Components/Common/selSysDic.cshtml

引入语法 (Razor):必须通过 ViewDataDictionary 传递参数,以对齐组件的视图模型接口约束:

index.cshtml Razor
@await Html.PartialAsync("~/Views/Components/Common/selSysDic.cshtml", new ViewDataDictionary(ViewData)
{
    { "inputId", "currencySelect" },
    { "dataKey", "SYS_CURRENCY_TYPE" },
    { "dataType", "SysDict" },
    { "mode", "select2" },
    { "multiple", false },
    { "placeholder", "请选择币种" },
    { "required", true }
})
实时运行与配置演示 (Interactive Playground)
Real Component

实例控制 API

操作日志:
// 选择变更或点击 API 按钮时,操作日志将在此处显示

参数 API 详解 (Parameters)

参数名 类型 必填 详细功能与规范说明
inputId String 生成 DOM 节点的 ID。
dataKey String 后端配置主键名。若是 SysDict 则对应字典编码;若是 Enum 则对应 C# 全类名(如 `Acme.IBP.Enums.DocStatus`);若是 BasicData 则对应通用主数据表名。
dataType String 数据类型。可选 'SysDict', 'Enum', 'BasicData'
mode String 渲染模式。可选 'select', 'select2', 'checkbox', 'radio'。需要模糊搜索时推荐使用 'select2'
multiple Boolean 在 mode='select2' 时,是否允许同时勾选多项,默认 false
defaultValue String 初始默认选中的值。
onChange String 值改变时触发的全局 JS 回调函数名称(签名:function(value){},仅传递当前选中的值,不传递原始 JSON item 对象)。

2. JS 公开实例操作方法

组件渲染后,会在全局 window 上注册名为 SelSysDic_#{inputId} 的实体操作句柄。通过该句柄可执行如下状态与值操作(严禁直接操作 select DOM 节点):

client.js JavaScript
// 1. 获取当前选中的值 (多选时返回以逗号分隔的字符串或数组)
var curVal = window.SelSysDic_currencySelect.getValue();

// 2. 动态设置选中值并触发联动
window.SelSysDic_currencySelect.setValue('USD');

// 3. 清空选择并重置状态
window.SelSysDic_currencySelect.reset();

// 4. 动态禁用/启用字典交互
window.SelSysDic_currencySelect.disable();
window.SelSysDic_currencySelect.enable();

// 5. 动态重新加载字典数据源
window.SelSysDic_currencySelect.reload();
05 / Selector Boundaries

选择器选用判定红线 (Decision Boundaries)

在面临多个人员、组织、配置项录入需求时,严禁开发人员“凭直觉”任意手写或拼凑。必须遵循以下唯一判定路线:


强制优先推荐路线

  • 需要多选人员、看所属部门、按自定义标签搜索:必须强绑定 selUser
  • 仅单选单个人员,且希望在窄小的折叠面板或工具栏极简呈现:优先使用 userTree
  • 仅绑定系统基础数据、固定系统配置项、数据状态枚举:必须强绑定 selSysDic
  • 在 ag-Grid 表格的 Filter 区域:一律强制使用 ag-Grid 自带表头 Filter,禁止挂载复杂选择组件

绝对禁止行为 (Red Lines)

  • 绝对禁止在已有 selUser 资产的前提下,自己在页面手写 Bootstrap Modal 并自己写 AJAX 请求去拼接人员复选框!
  • 绝对禁止绕开 selSysDic 字典选择器,在 HTML 页面中将状态枚举(如 <option value="1">待审核</option>)进行写死硬编码!
  • 绝对禁止由于多选人员数据量大,直接用普通的 input 输入框让用户拼写英文逗号分割的姓名(如 "张三,李四"),这会导致脏数据大面积产生!
06 / DataBinder & AcmeEditor

数据绑定与富文本 (DataBinder & AcmeEditor)


1. DataBinder 下拉绑定器

用于为 Select/Select2/Checkbox/Radio 从服务端 API 统一异步拉取数据并自动填充,杜绝手写 AJAX 拼接 option。

源文件路径: wwwroot/js/components/acme.controlBind.js 标准入口: DataBinder.bind(options)
交互演示 (Live Playground)
Asynchronous Bind
请选择岗位 (点击模拟 API 绑定)

控制台输出 / 事件侦听 (Console)

// 准备就绪,点击左侧组件触发 API 加载

参数 API 详解 (Parameters)

参数名 (Option) 类型 必填 默认值 详细功能与规范说明
target String - 绑定目标选择器,例如 '#jobSelect'
api String - 请求数据的 API 接口地址,如 '/api/personnel/jobs'
method String 'POST' HTTP 请求方法类型。核心约定: 默认使用 POST 发起提报,若接口仅支持只读,需显式声明为 GET。
component String 'select' 生成的组件类型。可选 'select', 'select2', 'checkbox', 'radio'。需要搜索过滤或多选时必须显式配置为 'select2'
placeholder String '请选择' 未选择状态下的占位符文本。
defaultValue String / Array - 初始默认选中的值,多选 select2 可传递数组。

回调生命周期

回调名 触发时机与参数 典型用途与注意事项
onChange 值改变时触发。
参数: function(value)
用于级联选择。如选择省份后,在回调中调用 DataBinder.bind 重新绑定城市 Select。注意:onChange 仅回调传递当前所选的单体 value 值,不传递 data 行对象。
onLoad 服务端数据成功拉取并渲染完毕时。
参数: function(data)
用于在渲染完成后进行默认值判定或表单状态解锁。

2. AcmeEditor 富文本编辑器

基于 Quill 2.0.3 驱动的工程级富文本输入,支持直传 OSS。

源文件路径: wwwroot/js/components/acme.editor.js 标准入口: AcmeEditor.create(selector, options)
交互演示 (Live Playground)
Quill 2.0.3 OSS

Harmony UI 设计系统为企业级后台管理页面而生。

在这里你可以模拟编辑文字、更改排版,或者点击 图片按钮 触发文件上传模拟动作。

状态: 已就绪 (OSS 传输已配置) 字数: 68

富文本特色规范

  • 图片直传 OSS,禁止保存大 Base64 数据到 SQL。
  • 统一拦截粘贴板,自动清理 Word/Wps 冗余样式。
  • 最大支持 20MB 的大图片附件。

参数 API 详解 (Parameters)

参数名 (Option) 类型 默认值 详细功能与红线规范
height Number 300 编辑器可视高度,单位 px。
uploadPath String - 核心红线参数。图片直传 OSS 的相对目录。禁止空置此参数保存 base64 到数据库!
placeholder String - 占位符提示信息。
代码复制成功!已写入剪贴板