反馈与浮层有已知边界

NnFileImportModal 文件导入框

文件选择、拖放和校验流程外壳。

示例

API

NnFileImportModal 基于 NnModal 提供通用文件路径展示、拖放反馈、校验和确认界面。组件不读取文件、 不执行系统文件选择，也不调用 Electron、Node 或业务 API；应用通过事件接入自己的选择与导入流程。

Props

名称	类型	默认值	说明
open	boolean	false	受控可见状态，配合 v-model:open。
filePath	string	''	受控文件路径或文件标识，配合 v-model:file-path。
title	string | number | object | unknown[] | (() => unknown)	'导入文件'	对话框标题；title 插槽优先。
descriptionTitle	string | number	'导入说明'	说明提示的标题。
description	string | number	''	说明提示正文；同名插槽优先。
width	string | number	560	对话框宽度，规则同 NnModal.width。
height	string | number	—	对话框高度，规则同 NnModal.height。
loading	boolean	false	外部导入中状态；禁用选择、清除、拖放与重复提交，并显示状态反馈。
disabled	boolean	false	禁用选择、清除、拖放和提交。
showPicker	boolean	true	是否渲染内建文件选择区。关闭后可通过 source 或默认插槽提供业务来源界面。
clearable	boolean	true	已选择路径时是否显示清除按钮。
dropEnabled	boolean	true	是否响应选择区上的文件拖放。
selectText	string	'选择文件'	选择请求按钮文字。
emptyText	string	'尚未选择文件，请点击上方按钮选择。'	未选择文件时的提示。
dropHint	string	'也可以将文件拖放到此处'	拖放提示。
dropActiveText	string	'松开鼠标以选择文件'	文件悬停在选择区时的提示。
pickerLabel	string	'文件选择区'	选择区无障碍名称。
pathLabel	string	'已选文件'	路径之前的标签。
clearText	string	'清除'	清除按钮文字。
statusText	string	'正在导入…'	loading=true 时的状态文字。
okText	string	'开始导入'	确认按钮文字。
cancelText	string	'取消'	取消按钮文字。
validator	(filePath: string) => unknown | Promise<unknown>	null	确认前校验，返回规则同 NnTextareaDrawer.validator；传入后由该函数决定空值是否有效。
invalidMessage	string	'请先选择文件'	内建选择区为空或校验返回 false 时的错误文案。

验证期间组件以 busy 状态禁用文件交互，并对开始验证时的路径做快照。如果异步校验返回前弹窗已关闭或受控路径已变化， 本次结果会被丢弃，不会把未校验的新路径提交出去。

Events

事件	参数	说明
update:open	(open: boolean)	内部对话框请求关闭时触发。
update:filePath	(filePath: string)	清除时发送空字符串；Electron 等环境的拖放文件暴露字符串 path 时发送该路径。
request-select	(event: MouseEvent)	点击选择按钮时触发；调用方应打开自己的文件选择器并写回 filePath。
files-dropped	(files: File[], event: DragEvent)	放下至少一个文件时触发；组件不读取文件内容。
clear	(event: MouseEvent)	点击清除按钮时与 update:filePath('') 同次触发。
submit	(filePath: string, event: MouseEvent)	校验通过后触发；不会自动关闭，调用方完成异步业务后更新 open。
cancel	(event: MouseEvent | KeyboardEvent)	取消、关闭按钮或 Escape 请求关闭时触发。

Slots

名称	作用域参数	说明
title	—	替换标题。
description	—	替换说明正文。
source	—	内建选择区之前的业务文件来源控件。
default	—	说明/来源与内建选择区之间的附加内容。
select-icon	—	选择按钮图标。
options	—	文件选择区之后的业务导入选项。
footer-content	—	校验和加载反馈之后的附加正文；不会替换 NnModal 的确认操作区。

当前限制

• 浏览器标准 File 不公开本地绝对路径；拖放始终通过 files-dropped 返回 File[]，只有运行环境额外提供 File.path 时组件才会同步 filePath。调用方不得假定浏览器里能够获得系统路径。
• 组件只提供单路径展示，但 files-dropped 会保留一次放下的全部文件；是否允许多文件及其校验规则由调用方决定。
• 未提供 validator 且 showPicker=true 时，空路径会使用 invalidMessage 拦截；传入校验器或关闭内建 选择区后，来源插槽对应的有效性由调用方负责。