97 lines
5.5 KiB
JSON
97 lines
5.5 KiB
JSON
{
|
||
"slug": "employeecard",
|
||
"end": "react",
|
||
"curated": true,
|
||
"summary": "React 端的 EmployeeCard：employee 对象驱动头像、状态、标签与联系方式，三个操作回调各自回传整个 employee。",
|
||
"usage": [
|
||
"所有渲染数据来自 employee 一个对象：name / empId / dept / position / status / avatar / tags / phone / email（frameworks/EmployeeCard.jsx:9-50）。",
|
||
"三个操作按钮固定排在卡片顶部 .kole-emp-actions 里，分别绑 onMessage / onView / onEdit，且都回传 employee 本身（`onMessage(employee)`）（frameworks/EmployeeCard.jsx:13-17）。",
|
||
"状态文案用三元推导：`employee.status === 'left' ? '离职' : '在职'`，并把原值拼进类名 ``kole-emp-status ${employee.status}``（frameworks/EmployeeCard.jsx:10,28）。",
|
||
"头像走条件渲染：有 avatar 渲染 <img alt={employee.name}>，否则取姓名首字母 `(employee.name || '?').charAt(0)` 兜底（frameworks/EmployeeCard.jsx:21-23）。",
|
||
"两条 && 短路控制可选区块：tags 非空才渲染标签行，showContact 且 phone / email 有值才渲染联系方式（frameworks/EmployeeCard.jsx:38,44）。",
|
||
"标签行用 `employee.tags.map((t) => ...)` 并以标签文本为 key（frameworks/EmployeeCard.jsx:40）。"
|
||
],
|
||
"bestPractices": [
|
||
"employee 是必填：组件直接读 `employee.status`，不传会抛错，使用前要保证对象存在（frameworks/EmployeeCard.jsx:9,10）。",
|
||
"三个回调都以 employee 为载荷，父组件不用再自己回查是哪个员工（frameworks/EmployeeCard.jsx:14-16）。",
|
||
"联系方式要同时满足 showContact 与 phone / email 之一，只传 showContact 不显示（frameworks/EmployeeCard.jsx:44）。",
|
||
"status 只认 left 为离职，其它值一律显示在职，同时原值会拼进类名用于样式区分（frameworks/EmployeeCard.jsx:10,28）。",
|
||
"标签 key 用标签文本，同卡片内标签不能重名，否则 React 会报 key 重复（frameworks/EmployeeCard.jsx:40）。"
|
||
],
|
||
"a11y": [
|
||
"有头像时 <img alt={employee.name}> 给出员工姓名，图片失败也不会丢失名字（frameworks/EmployeeCard.jsx:22）。",
|
||
"无头像时是首字母 span，读屏器只读到一个字母，缺少可访问名（frameworks/EmployeeCard.jsx:23）。",
|
||
"三个操作按钮是原生 <button> 带中文可见文案（发消息 / 详情 / 编辑），键盘可达且读屏器可读（frameworks/EmployeeCard.jsx:14-16）。",
|
||
"「在职 / 离职」是可见文本，读屏器能读到；但状态没有额外的 aria 描述，色觉用户依赖文字（frameworks/EmployeeCard.jsx:28）。"
|
||
],
|
||
"apiCarrier": {
|
||
"kind": "props",
|
||
"note": "React 端的 API 载体是 employee 数据 prop 加三个 onXxx 回调（onMessage / onView / onEdit，载荷均为 employee），showContact 控制联系方式区；没有 v-model，组件无内部状态。",
|
||
"table": [
|
||
{
|
||
"name": "employee",
|
||
"type": "Object",
|
||
"desc": "必填数据对象，驱动姓名 / 工号 / 部门 / 职位 / 状态 / 头像 / 标签 / 联系方式（frameworks/EmployeeCard.jsx:9,19-50）"
|
||
},
|
||
{
|
||
"name": "onEdit",
|
||
"type": "属性",
|
||
"desc": "「编辑」按钮回调，载荷是 employee（frameworks/EmployeeCard.jsx:16）"
|
||
},
|
||
{
|
||
"name": "onMessage",
|
||
"type": "属性",
|
||
"desc": "「发消息」按钮回调，载荷是 employee（frameworks/EmployeeCard.jsx:14）"
|
||
},
|
||
{
|
||
"name": "onView",
|
||
"type": "属性",
|
||
"desc": "「详情」按钮回调，载荷是 employee（frameworks/EmployeeCard.jsx:15）"
|
||
},
|
||
{
|
||
"name": "showContact",
|
||
"type": "属性",
|
||
"desc": "为真且 phone / email 有值时才渲染联系方式区（frameworks/EmployeeCard.jsx:44）"
|
||
},
|
||
{
|
||
"name": "onClick",
|
||
"type": "事件",
|
||
"desc": "三个操作按钮上的原生点击名，分别接不同回调（frameworks/EmployeeCard.jsx:14-16）"
|
||
},
|
||
{
|
||
"name": "onEdit",
|
||
"type": "事件",
|
||
"desc": "React 里回调以 onXxx prop 传入，「编辑」按钮绑 onEdit（frameworks/EmployeeCard.jsx:16）"
|
||
},
|
||
{
|
||
"name": "onMessage",
|
||
"type": "事件",
|
||
"desc": "「发消息」按钮绑 onMessage（frameworks/EmployeeCard.jsx:14）"
|
||
}
|
||
]
|
||
},
|
||
"resources": [
|
||
{
|
||
"file": "frameworks/EmployeeCard.jsx",
|
||
"kind": "React",
|
||
"desc": "该端实现（本页 API 与用法的唯一权威来源）。"
|
||
},
|
||
{
|
||
"file": "frameworks/EmployeeCard.css",
|
||
"kind": "样式",
|
||
"desc": "该组件的样式文件，类名口径以它为准。"
|
||
}
|
||
],
|
||
"exampleIds": [
|
||
"employeecard-ex-1",
|
||
"employeecard-ex-2"
|
||
],
|
||
"notes": [
|
||
"props 解构见 frameworks/EmployeeCard.jsx:9，共 5 个（employee / showContact / onMessage / onView / onEdit）；数据结构注释见 4-8 行。",
|
||
"状态推导见第 10 行，头像三分支见 21-23 行，标签 && 与 map 见 38-42 行，联系方式 && 见 44-47 行。",
|
||
"a11y 依据：img 的 alt 见 frameworks/EmployeeCard.jsx:22，三个按钮的可见文案见 14-16 行；全文无 aria-* 补充。",
|
||
"实现缺口：无头像时无可访问名、status 未做 aria 描述（frameworks/EmployeeCard.jsx:23,28）；按实现写，未补 aria 属性。",
|
||
"apiCarrier.table 保留了自动生成时的「属性 + 事件」两套同名行（onEdit / onMessage 各两次），本次只改 desc 文案，未调整行结构。"
|
||
]
|
||
}
|