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 是否展示自定义用户标签(如“财务审计员”、“运维技术骨干”)。
departmentOnly Boolean false 仅允许单选部门;启用后自动关闭人员与标签数据,并改用纯部门树接口。
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/department-tree/1departmentOnly=true 时使用)。
  • 标签接口/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 },
    { "allowMultiple", true },
    { "callback", "onReportTreeSelected" }
})
实时运行与配置演示 (Interactive Playground)
Real Component

实例控制 API

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

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

参数 API 详解 (Parameters)

参数名 类型 必填 详细功能与规范说明
inputId String 组件实例 ID,作为 jsTree 生成的唯一节点前缀。
placeholder String 输入框占位符文本。
height Number 树容器最大限制高度,默认 300px
allowMultiple Boolean 是否允许多选人员,默认 false。无论单选或多选,部门节点都不可选。
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', 'tree'。多级字典使用 'tree'
multiple Boolean 是否允许同时选择多项,适用于 select2checkboxtree,默认 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 - 占位符提示信息。
代码复制成功!已写入剪贴板