Preview 表单预览

键值信息卡（订单详情、个人信息、账单汇总等只读详情页的卡片形态）：头部「标签 + 强调值」、中部键值列表、底部操作按钮行，全部由 panelData 一个数据对象驱动；数据变化整卡响应式更新。常与卡片容器或列表页配合，也可放进弹层做确认页。

平台兼容性

App	Web	微信小程序
✓	✓	✓

三段（头部 / 列表 / 按钮行）按数据有无自动装配：某段数据为空就不渲染该段；全部为空时只剩插槽内容。

基础用法（订单详情卡）

<n-preview :panel-data="order" @click="onButtonClick" />

const order = {
	label: "订单金额",
	value: "￥29.90",
	list: [
		{ label: "订单号", value: "NP20260131001", valueColor: "#ef4444" },
		{ label: "物流单号", value: "SF34409992021080911" },
		{ label: "创建时间", value: "2026-01-31 09:20" },
		{ label: "订单备注", value: "路上注意安全，超时可提前联系。" }
	],
	buttons: [{ text: "联系客服" }]
};
// click 回传 { index, item }，item 是按钮原始对象（可携带 id 等业务字段）
function onButtonClick(detail: NPreviewClickDetail) {
	uni.showToast({ title: `点击了第 ${detail.index} 个按钮`, icon: "none" });
}

列表项 valueColor / labelColor 覆盖该行文字色；按钮项 color 覆盖按钮文字色（默认品牌色）。

两端对齐标签（表单风）

标签逐字两端分布是表单详情的经典排法，需配合固定标签宽：

<n-preview
	:panel-data="profile"
	label-align="justify"
	:label-width="72"
>
	<text class="extra">补充说明（默认插槽，渲染在列表与按钮行之间）</text>
</n-preview>

const profile = {
	label: "个人信息",
	list: [
		{ label: "姓名", value: "张三" },
		{ label: "手机号码", value: "189****0020" },
		{ label: "家庭住址", value: "广东省深圳市龙华区" }
	],
	buttons: [
		{ id: 1, text: "修改", color: "#262626" },
		{ id: 2, text: "删除", color: "#ef4444" }
	]
};

labelWidth = 0（自适应宽）时 justify 降级为左对齐；逐字分布适合 2~6 字中文标签，长句与英文词不建议用 justify。

更新某行值

const preview = ref<NPreviewComponentPublicInstance | null>(null);
// 更新的是组件内部显示副本，panelData 原始对象不被改写
if (preview.value != null) preview.value.setValue(0, "已发货");

业务字段映射

后端字段名与约定不一致时用 fields 映射（未指定的键用同名字段）：

<n-preview :panel-data="dto" :fields="mapping" />

const dto = {
	title: "账单金额",
	amount: "￥128.00",
	items: [
		{ title: "套餐费", amount: "￥88.00" },
		{ title: "增值服务", amount: "￥40.00" }
	],
	actions: [{ label: "去支付" }]
};
const mapping = {
	label: "title",
	value: "amount",
	list: "items",
	buttons: "actions",
	text: "label"
};

label / value 键同时用于头部与列表行（头部与行共用同一套键名），未指定的 labelColor / valueColor / color / disabled 仍用同名字段。

实现说明（参考做法 → 本库做法）

机制	参考做法	本库做法与理由
数据入口	previewData 对象直传	panelData（UTSJSONObject 类型化，与数据驱动组件族同口径）+ fields 9 键映射全集
点击回传	{ index, ...按钮项 } 展开进事件参数	{ index, item } 保留原始对象——展开语义由 item 承载，业务自定义字段不被约定字段遮蔽
数据错误	静默（类型不符渲染异常或空白）	error 事件显式上抛 { field, index }（index=-1 面板级），数据驱动族一致
setValue	深拷贝 previewData 后改写触发重渲染	更新组件内部显示副本，原始数据对象不改写
头部值/列表值颜色	hdValColor / bdColor 两个 prop 分立	收敛为一个 valueColor；需要不同色的场景用逐项 valueColor 覆盖
字号定制	hdLabelSize / hdValSize / bdSize / btnSize 四个字号 prop	主题令牌（--n-preview-head-label-size 等 4 个）+ 逐项颜色；全卡字号属主题定制，不进单实例 API
左右留白	padding prop	令牌 --n-preview-padding-x
标签与值间距	labelRight prop	令牌 --n-preview-label-gap
上下外边距	marginTop / marginBottom prop	custom-style（全库统一的相邻元素排间距通道）
头部线缩进	hdLeft / hdRight prop	固定左缩进对齐文字、右到边（表单卡惯例）
线色	borderColor prop	令牌 --n-preview-line-color（深浅自动）
按钮默认色	固定 #465CFF	品牌色令牌，随库主题一致
标签 justify	CSS text-align-last: justify（uni-app x 不支持）	标签逐字渲染进 space-between 容器实现两端分布；需 labelWidth 固定宽，否则降级左对齐
外框线	上下 0.5px 伪元素线	绝对定位 1px view，非 App 端 scaleY(0.5) 半高渲染（无伪元素依赖）

API

Props

属性	类型	说明
panel-data	UTSJSONObject|null	面板数据 { label?, value?, list?, buttons? }，null 只渲染插槽，默认 null
fields	NPreviewFields	映射 label/value/list/labelColor/valueColor/buttons/text/color/disabled，未指定或空串使用同名字段，默认 {}
background	string	卡片背景色，空 = 主题背景色（深浅自动），默认 ""
label-width	number	标签固定宽度（px），0 = 按文字自适应；justify 需固定宽，默认 0
label-align	NPreviewLabelAlign	标签对齐：left / right / justify（两端逐字分布），默认 "left"
label-color	string	标签文字色，空 = 次要色，默认 ""
value-color	string	值文字色（头部值与列表值统一），空 = 主文字色，默认 ""
value-align	NPreviewValueAlign	值对齐：right / left，默认 "right"
highlight	boolean	底部按钮按压反馈，默认 true
border	boolean	上下外边框线，默认 true
custom-class	string	根节点额外类（类需定义在组件样式表内），默认 ""
custom-style	string	根节点行内样式，默认 ""

Events

事件	参数	说明
click		点击底部按钮时触发（禁用按钮不触发）
valueClick		点击列表值时触发
error		面板数据字段类型非法时触发；index=-1 表示面板级字段

Slots

插槽	说明
default	补充内容区，渲染在键值列表与按钮行之间

Methods

方法	参数	说明
setValue	(index: number, value: string)	更新列表第 index 行的显示值；越界忽略