基本表单控件与色彩规范
所有输入控件继承自 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 (提示蓝) |
系统说明、指南 | 表单填写小助手指南、操作提示弹窗内的详细解读文本。 |
状态控制面板
文字/状态颜色效果实时预览 (Color Tester):
Harmony UI 系统预设文本颜色。点击左侧下拉框切换不同颜色样式,在这里实时观察渲染对比度和视觉美感。
当前控件参数详情 (Inspect):
核心人员选择器 (selUser)
企业级核心组件。支持多选/单选人员、所属部门、关联标签的高级树表弹窗选择器。适用于一切“分配人员”、“设定负责人”、“选择抄送”场景。
1. 组件定位与引入
引入语法 (Razor):必须通过 ViewDataDictionary 传递组件的属性,否则在局部页面中将无法正确绑定上下文参数:
@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" }
})
参数调整
注:切换模式时,页面会即时动态切换已预渲染的具有对应配置的组件实例。
选择结果输出:
参数 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 函数结构
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 + "人已指定");
}
}
极简人员选择树 (userTree)
轻量级人员选择组件。适用于“单选单个人员”、“无需标签过滤”、“空间高度受限”的快速流程派发场景。
1. 组件定位与引入
引入语法 (Razor):必须通过 ViewDataDictionary 传递组件的属性,否则在局部页面中将无法正确绑定上下文参数:
@await Html.PartialAsync("~/Views/Components/Common/userTree.cshtml", new ViewDataDictionary(ViewData)
{
{ "inputId", "myDirectReportTree" },
{ "placeholder", "请指派直接下属" },
{ "height", 300 },
{ "callback", "onReportTreeSelected" }
})
实例控制 API
利用暴露在 window 上的全局方法,可通过外部 JS 代码动态操纵选择器的行为:
选择结果输出:
参数 API 详解 (Parameters)
| 参数名 | 类型 | 必填 | 详细功能与规范说明 |
|---|---|---|---|
inputId |
String | 是 | 组件实例 ID,作为 jsTree 生成的唯一节点前缀。 |
placeholder |
String | 否 | 输入框占位符文本。 |
height |
Number | 否 | 树容器最大限制高度,默认 300px。 |
callback |
String | 是 | 点击人员节点触发的回调函数名称(参数为选中的人员 ID 及名称)。 |
系统字典与数据源选择器 (selSysDic)
统一配置映射组件。适用于为 Select/Select2/Checkbox/Radio 绑定字典配置数据、系统运行枚举或基础数据(如省市区、币种),杜绝手写硬编码。
1. 组件定位与引入
引入语法 (Razor):必须通过 ViewDataDictionary 传递参数,以对齐组件的视图模型接口约束:
@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 }
})
实例控制 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 节点):
// 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();
选择器选用判定红线 (Decision Boundaries)
在面临多个人员、组织、配置项录入需求时,严禁开发人员“凭直觉”任意手写或拼凑。必须遵循以下唯一判定路线:
强制优先推荐路线
- 需要多选人员、看所属部门、按自定义标签搜索:必须强绑定
selUser。 - 仅单选单个人员,且希望在窄小的折叠面板或工具栏极简呈现:优先使用
userTree。 - 仅绑定系统基础数据、固定系统配置项、数据状态枚举:必须强绑定
selSysDic。 - 在 ag-Grid 表格的 Filter 区域:一律强制使用 ag-Grid 自带表头 Filter,禁止挂载复杂选择组件。
绝对禁止行为 (Red Lines)
- 绝对禁止在已有
selUser资产的前提下,自己在页面手写 Bootstrap Modal 并自己写 AJAX 请求去拼接人员复选框! - 绝对禁止绕开
selSysDic字典选择器,在 HTML 页面中将状态枚举(如<option value="1">待审核</option>)进行写死硬编码! - 绝对禁止由于多选人员数据量大,直接用普通的 input 输入框让用户拼写英文逗号分割的姓名(如 "张三,李四"),这会导致脏数据大面积产生!
数据绑定与富文本 (DataBinder & AcmeEditor)
1. DataBinder 下拉绑定器
用于为 Select/Select2/Checkbox/Radio 从服务端 API 统一异步拉取数据并自动填充,杜绝手写 AJAX 拼接 option。
控制台输出 / 事件侦听 (Console)
参数 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。
Harmony UI 设计系统为企业级后台管理页面而生。
在这里你可以模拟编辑文字、更改排版,或者点击 图片按钮 触发文件上传模拟动作。
富文本特色规范
- 图片直传 OSS,禁止保存大 Base64 数据到 SQL。
- 统一拦截粘贴板,自动清理 Word/Wps 冗余样式。
- 最大支持 20MB 的大图片附件。
参数 API 详解 (Parameters)
| 参数名 (Option) | 类型 | 默认值 | 详细功能与红线规范 |
|---|---|---|---|
height |
Number | 300 |
编辑器可视高度,单位 px。 |
uploadPath |
String | - | 核心红线参数。图片直传 OSS 的相对目录。禁止空置此参数保存 base64 到数据库! |
placeholder |
String | - | 占位符提示信息。 |