n-card 卡片
内容容器原语：头 / 体 / 底三段结构。头部排开 缩略图 + 标题 / 副标题 + 右侧额外区，主体放默认插槽（内容自带布局），底部放 foot 插槽（操作区 / 补充说明）。适合信息聚合卡、商品卡、资讯卡、设置分组表面、分组面板（卡头 + 单元格行组合）等场景。
- 默认扁平形态：表面色取主题面底色，与页面画布色差分界，无线无影；需要描边开
border、需要浮起感开shadow——独立 prop 可叠加，发丝线 + 浅影是常见组合，是否同开自选- 任意业务内容放默认插槽；媒体列表传
panel-data，单项对象和带list的对象均可，fields映射业务字段。默认插槽可追加列表后的操作或说明。full为通栏形态：圆角归零且水平外边距失效（custom-style写入的水平外距一并归零，上下外距保留），贴边铺满所在容器；所在容器自身的内边距越不过去（无外距的卡片开full后唯一可见变化是直角，需配外距对照观感）；非通栏卡片的外边距由页面布局负责（custom-style="margin:0 15px 14px"或外层节点）- 头部整段替换用
head插槽（文字与缩略图属性不再显示）；标题 / 右侧额外区单独替换用title/extra插槽，头部容器样式和分隔线仍生效。
平台兼容性
| App | H5 | 微信小程序 | 支付宝小程序 | 百度小程序 | 头条小程序 | QQ小程序 |
|---|---|---|---|---|---|---|
| √ | √ | √ | × | × | × | × |
API
属性
| 参数 | 说明 | 类型 | 默认值 | 可选值 |
|---|---|---|---|---|
| title | 头部标题（长标题单行省略；内容复杂时改用 title 插槽，整头替换用 head 插槽） | string | "" | - |
| sub-title | 标题下方的副标题（次要色小字，如说明、时间） | string | "" | - |
| extra | 头部右侧的额外文字（如"更多"、"23小时前"；内容复杂时改用 extra 插槽） | string | "" | - |
| thumb | 头部缩略图地址（网络 / 本地路径；标题左侧，正方形裁剪） | string | "" | - |
| thumb-width | 缩略图宽度（px） | number | 36 | - |
| thumb-height | 缩略图高度（px），0 = 跟随 thumbWidth（正方形） | number | 0 | - |
| thumb-circle | 缩略图圆形裁剪（头像 / 圆标；开启时 thumbRadius 失效） | boolean | false | - |
| thumb-radius | 缩略图圆角（px），-1 使用主题令牌（默认 8px）；thumbCircle 开启时失效 | number | -1 | - |
| header-border-bottom | 头部与主体之间的分隔线（默认开启，两段都有内容时分界可辨） | boolean | true | - |
| footer-border-top | 主体与底部之间的分隔线；需配 foot 插槽（无底部内容时底部段不渲染，线无处可画） | boolean | false | - |
| border | 描边（0.5px 发丝线，同色背景勾边界；与投影独立可叠加） | boolean | false | - |
| shadow | 投影（浮起卡片的分界；与描边独立可叠加，发丝线 + 浅影是常见组合） | boolean | false | - |
| full | 通栏形态：圆角归零且水平外边距失效（custom-style 写入的水平外距一并归零，上下外距保留），贴边铺满所在容器 | boolean | false | - |
| name | 业务标识：click / headClick / bodyClick / footClick 四个事件原样回传，列表代理处理点击时区分来源（下标可作字符串传入） | string | "" | - |
| title-style | 微调标题的行内样式，如 "font-weight:600"（页面 class 打不进组件内部，见文件头说明） | string | "" | - |
| sub-title-style | 微调副标题的行内样式，如 "color:#ef4444" | string | "" | - |
| extra-style | 微调头部右侧额外文字的行内样式 | string | "" | - |
| header-style | 头部容器行内样式（如换底色 "background-color:#fafafa"、调内边距） | string | "" | - |
| body-style | 主体容器行内样式（主体默认零内边距，纯文字内容用 "padding:12px 16px" 撑开） | string | "" | - |
| foot-style | 底部容器行内样式 | string | "" | - |
| panel-data | 媒体数据：单项对象，或包含 head 和 list 的对象；null 不渲染媒体行，默认插槽可同时提供补充内容 | UTSJSONObject | null | null | - |
| fields | 映射 head / list / src / title / desc / source / time / extra，未指定或空串使用同名字段 | NCardFields | {} | - |
| highlight | 媒体行按压反馈，不拦截插槽中控件的触摸 | boolean | true | - |
| flex-start | 媒体图片和文字顶部对齐；false 垂直居中 | boolean | false | - |
| row-reverse | 媒体图片显示在文字右侧 | boolean | false | - |
| media-width | 媒体图片宽度，数值按 px，字符串支持 rpx 等长度 | string | number | 60 | - |
| media-height | 媒体图片画布高度，数值按 px，字符串支持 rpx 等长度 | string | number | 60 | - |
| media-radius | 媒体图片圆角，数值按 px，字符串支持百分比 | string | number | 0 | - |
| media-mode | 媒体图片缩放：aspectFill 铺满裁剪、aspectFit 完整显示、widthFix 按宽度保持原图比例；画布尺寸由 mediaWidth / mediaHeight 决定 | NCardMediaMode | aspectFill | aspectFill / aspectFit / widthFix |
| item-border | 媒体行之间的分隔线，末行不显示 | boolean | true | - |
| item-style | 媒体行容器样式，可调整内边距与底色 | string | "" | - |
| media-title-style | 媒体标题文字样式，默认单行省略，可调整字号、颜色与字重 | string | "" | - |
| media-description-style | 媒体描述文字样式，默认最多两行 | string | "" | - |
| media-source-style | 来源文字样式，如字号与颜色 | string | "" | - |
| media-time-style | 时间文字样式，如字号与颜色 | string | "" | - |
| media-extra-style | 附加信息文字样式，可调整左侧分界线 | string | "" | - |
| header-line-style | 头部分隔线样式，可设置 left / right / background-color | string | "" | - |
| footer-line-style | 底部分隔线样式，可设置 left / right / background-color | string | "" | - |
| item-line-style | 媒体行分隔线样式，可设置 left / right / background-color | string | "" | - |
| custom-class | 挂到根节点的额外 class（类需定义在组件样式表内） | string | "" | - |
| custom-style | 根节点行内样式，如 "margin:0 15px 14px" 用于与相邻元素排间距 | string | "" | - |
事件
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| click | 点击卡片任意位置时触发，参数 name | name: string |
| headClick | 点击头部区域时触发，参数 name；整卡 click 同步触发 | name: string |
| bodyClick | 点击主体区域时触发，参数 name；整卡 click 同步触发 | name: string |
| footClick | 点击底部区域时触发，参数 name；整卡 click 同步触发 | name: string |
| itemClick | 点击媒体行时触发，参数 { name, index, item }；主体与整卡事件同步触发 | NCardItemClickDetail |
| error | 媒体数据格式错误时触发，参数 { field, index }；index=-1 表示面板级错误 | NCardDataError |
插槽
| 插槽名 | 说明 |
|---|---|
| head | 替换整个头部内容（头部文字与缩略图属性不再显示；容器样式与分隔线保留） |
| title | 替换标题文字（自由组合图标、徽标等） |
| extra | 替换头部右侧区（可放任意组件：n-button 行内操作、n-tag 状态标签等） |
| default | 主体内容（自带布局；纯文字建议配 body-style 撑开内边距） |
| foot | 底部内容（操作区 / 补充说明），无内容不占位 |
实现说明
| 机制 | 参考做法 | 本库做法与理由 |
|---|---|---|
| 内容结构与事件 | 头部、主体、底部与区域点击 | 保留三段、五个插槽及四个区域事件；业务标识统一回传 name |
| 头部内容 | 缩略图、标题、副标题、右侧文字 | 保留全部内容；head 替换整头，title / extra 分别替换对应区域；标题和右侧区以 2:1 分配可用宽度，长文字省略，插槽限制在各自区域 |
| 状态与更新 | 原地更新内容与节点显隐 | 根节点与插槽宿主保持稳定，空内容用 v-show 隐藏；避免丢失输入与内部组件状态 |
| 描边与阴影 | 存在互斥和独立两种设计 | 独立开关，允许同时开启；外层承载阴影，内层裁剪贴边内容，兼顾圆角和投影 |
| 外边距与通栏 | 外边距可设，通栏将圆角与水平外距归零 | custom-style 设置外距；full 的归零声明最后应用，上下外距保留，父容器内边距由页面管理 |
| 尺寸、颜色和内边距 | 各段字号、颜色、底色、内边距均可配置 | 全局走主题令牌，单卡走根节点及各段 xxx-style，不重复提供同义颜色属性 |
| 缩略图圆角 | 自定义圆角与圆形 | thumb-radius=-1 跟随主题；非负值显式覆盖，thumb-circle 优先 |
| 媒体数据 | 单项对象，或包含列表和标题的对象；八个字段可映射 | panel-data 接收同样的两种结构，fields 映射 head / list / src / title / desc / source / time / extra；数据与映射变化即时生效，空列表保持为空 |
| 媒体布局 | 图片左右排列、顶部或居中对齐、图片尺寸和圆角、标题单行和描述双行 | row-reverse / flex-start / media-width / media-height / media-radius / media-mode 配置图片，画布宽高保持固定，mode 只控制画布内缩放；文字样式分别直达标题、描述、来源、时间与附加信息 |
| 媒体交互 | 逐项点击回传下标与完整原始数据，按压变色 | itemClick 回传 { name, index, item }，完整原始对象保存在 item，避免业务字段覆盖事件下标；highlight 控制原生按压反馈 |
| 分隔线 | 外边框、头部线、底部线、行间线可分别调整颜色与左右内缩 | border 或根 custom-style 配外框；header-line-style / footer-line-style / item-line-style 配分隔线，末行不画行间线 |
| 数据错误 | 空数据按空内容处理，异常结构未显式报告 | 空数据不占媒体行；错误数据通过 error 事件和随语言切换的错误说明显式反馈，不吞错也不显示伪造条目 |
| 示例与固定底栏 | 数据与配置可交互修改 | 单一预览保留在 n-page footer；高度相关配置变化后调用 resize 重测预留空间 |
阴影的祖先容器需设置 overflow:visible。圆角通过 --n-card-radius、uni.scss 或根节点 custom-style 定制；裁剪层与根节点使用相同圆角声明。插槽存在性在挂载时确定，需要切换插槽来源时使用完整组件变体。