企业官网建设流程全解析

• 前端
• UI组件

导读

本文聚焦 rsuite 组件库中 Uploader（文件上传组件）的三种非交互展示状态：disabled（禁用）、readOnly（只读）与plaintext（纯文本），内容以官方文档 disabled.md 示例为骨架，结合 Uploader.tsx、UploadFileItem.tsx、UploadTrigger.tsx 等源码逐一拆解各属性的生效层级与底层实现。读完你将掌握：如何区分并正确组合disabled、disabledFileItem、readOnly、plaintext四个属性，理解它们在"上传触发器（按钮）"与"文件列表项"两个层级上的不同作用范围，并能在实际业务中按场景（权限受限、详情展示、打印导出）选用正确的形态。

一、三种状态一览：官方示例原貌

官方文档通过三段Uploader演示了禁用、只读、纯文本三种形态，完整代码如下：

import { Uploader, Button, Divider, VStack } from 'rsuite'; const fileList = [ { name: 'A puppy sleeping on its belly', fileKey: 1, url: 'https://images.unsplash.com/photo-1583512603805-3cc6b41f3edb?w=265' }, { name: 'A puppy looking at me with big eyes', fileKey: 2, url: 'https://images.unsplash.com/photo-1561037404-61cd46aa615b?w=300' } ]; const App = () => ( <VStack gap={20}> <Divider label="Disabled" labelPlacement="start" /> <Uploader disabled disabledFileItem defaultFileList={fileList} action="//jsonplaceholder.typicode.com/posts/" /> <Divider label="Read only" labelPlacement="start" /> <Uploader readOnly disabledFileItem defaultFileList={fileList} action="//jsonplaceholder.typicode.com/posts/" /> <Divider label="Plaintext" labelPlacement="start" /> <Uploader plaintext disabledFileItem defaultFileList={fileList} action="//jsonplaceholder.typicode.com/posts/" /> </VStack> ); ReactDOM.render(<App />, document.getElementById('root'));

三个示例均通过defaultFileList预置了两条文件记录（由fileKey唯一标识、url提供缩略图预览地址），并同时开启disabledFileItem以锁定文件列表本身。action指向一个模拟接口，仅用于满足action为必填项的要求（详见下方 Props 说明）。

二、四属性职责划分：触发器层 vs 列表项层

要准确理解这三种状态，必须先分清 Uploader 内部的两个渲染层级：

1. 上传触发器（UploadTrigger）：渲染为默认的Button，负责唤起文件选择框、支持拖拽交互；
2. 文件列表项（UploadFileItem）：渲染每个已选文件的名称、缩略图、进度条与删除按钮。

在 Uploader.tsx 的renderList中可以看到，disabled与readOnly被透传给UploadTrigger，而disabledFileItem则作为disabled传入每个FileItem；removable与allowReupload会在readOnly或plaintext时被强制关闭。四个属性的职责对比如下：

1. disabled：彻底切断上传入口

disabled作用于触发器层。在 UploadTrigger.tsx 中，当disabled为true时，按钮不再绑定onClick、onDragEnter等任何事件处理器，隐藏的<input type="file">也被加上disabled属性（UploadTrigger.tsx），因此文件选择框完全无法唤起。

源码中的事件绑定逻辑如下：

const buttonProps: Partial<ButtonProps> = { ...rest, disabled, className: prefix('btn'), // Only add event handlers if component is interactive ...(!disabled && !readOnly && { onClick: handleClick, onDragEnter: handleDragEnter, onDragLeave: handleDragLeave, onDragOver: handleDragOver, onDrop: handleDrop }) };

仓库测试 Uploader.spec.tsx 对该行为做了断言：

it('Should be disabled', () => { render(<Uploader action="" disabled />); expect(screen.getByRole('button')).to.have.attr('disabled'); });

注意：disabled只影响"上传按钮"，并不影响已存在文件列表项的展示；示例中额外叠加disabledFileItem，正是为了把列表项也一并锁定，形成完整的"禁止任何操作"形态。

2. readOnly：可视但不可交互

readOnly同样作用于触发器层，但它与disabled的视觉表现不同：按钮保持可用外观，却同样不绑定任何事件（见上方案例中!disabled && !readOnly的条件），文件选择框也不会打开。

与disabled的差异主要体现在列表层。查看 Uploader.tsx 中列表项属性的计算逻辑：

removable={removable && !readOnly && !plaintext} allowReupload={!readOnly && !plaintext}

即在readOnly下：

• removable强制为false，文件项的删除按钮不再渲染；
• allowReupload强制为false，上传失败文件的"重试"入口被隐藏。

因此readOnly的语义是：既不允许新增文件，也不允许删除或重传已有文件，适合"仅允许查看已上传内容"的场景。示例中readOnly与disabledFileItem组合，进一步禁用了缩略图点击预览（handlePreview在disabled时直接return，见 UploadFileItem.tsx），实现完全只读。

3. plaintext：纯文本展示形态

plaintext是三种状态中唯一的"整体性"形态。在 Uploader.tsx 中，当plaintext为true时，组件不再渲染上传触发器，而是将文件列表包裹进Plaintext容器：

if (plaintext) { return ( <Plaintext localeKey="notUploaded" className={classes} {...dataAttributes}> {fileList.current.length ? renderList[1] : null} </Plaintext> ); }

关键点：

• 触发器被完全移除，页面只展示文件列表内容，适合详情页、打印或表单提交后回显等"不提供上传入口"的场景；
• 若fileList为空，则展示localeKey="notUploaded"对应的本地化文案（如"未上传"），文案可通过locale配置；
• 同样地，removable与allowReupload会被强制关闭（Uploader.tsx），列表只读。

4. disabledFileItem：锁定文件列表交互

disabledFileItem贯穿全部三个示例，它在列表项层生效。在 UploadFileItem.tsx 中，disabled为true时，预览点击（handlePreview）、删除（handleRemove）与重传（handleReupload）三个回调都会提前返回，同时渲染出的根节点带有data-disabled="true"属性（UploadFileItem.tsx），供样式层做视觉降级；上传中的进度条也会因!disabled条件而隐藏（UploadFileItem.tsx）。

样式层面，index.scss 中&-file-item[data-disabled='true']与.rs-uploader-trigger[data-disabled='true']等选择器分别对列表项与触发器应用禁用态样式，这意味着即便在disabled之外单独使用disabledFileItem，组件也能获得一致的禁用视觉反馈。

三、defaultFileList 与 FileType：只读列表的数据来源

三个示例都通过defaultFileList预置文件，其类型定义在 file-type.md 中：

interface FileType { /** File Name */ name?: string; /** File unique identifier */ fileKey?: number | string; /** File upload status */ status?: 'inited' | 'uploading' | 'error' | 'finished'; /** File upload progress */ progress?: number; /** The url of the file can be previewed. */ url?: string; }

fileKey是文件在队列中的唯一标识，Uploader 内部通过createFile为未提供fileKey的文件自动生成唯一 ID（Uploader.tsx）。在只读/纯文本场景下，列表项的展示逻辑与正常上传时一致：url存在时直接作为缩略图源，否则在listType为picture/picture-text且文件大小不超过maxPreviewFileSize（默认 5MB，见 UploadFileItem.tsx）时，通过previewFile生成本地预览图（UploadFileItem.tsx）。

需要说明的是，defaultFileList属于非受控用法，若需要由外部状态完全控制文件列表，应改用受控属性fileList（Uploader 会在其变化时通过init动作重置内部队列，见 Uploader.tsx）。

四、状态组合速查与选型建议

综合源码行为，可将四种属性组合后的可用交互归纳如下：

说明：readOnly/plaintext下删除与重传被强制关闭的结论，来源于 Uploader.tsx 中removable、allowReupload的表达式；预览是否可用则取决于是否叠加disabledFileItem。表内交互结论均可在 Uploader.spec.tsx、UploadFileItem.spec.tsx 对应用例中进一步验证。

实际选型建议：

• 权限受限、完全不可操作：使用disabled+disabledFileItem，禁用态视觉提示最明确，适合"当前用户无上传权限"；
• 详情查看、需保留可点击预览：使用readOnly，按钮可见但不可用，文件列表保留预览能力；
• 表单回显、打印、导出：使用plaintext，直接以纯文本呈现已上传文件清单，不渲染任何操作控件，视觉最干净。

五、小结

rsuite Uploader 通过disabled、readOnly、plaintext与disabledFileItem四个属性，在"上传触发器"与"文件列表项"两个层级上提供了可自由组合的交互控制能力。官方 disabled.md 示例展示了三者的标准组合，而源码进一步揭示了其实现细节：disabled/readOnly通过条件挂载事件处理器切断触发入口，plaintext通过替换为Plaintext容器移除整个触发器，disabledFileItem则在列表项内部拦截预览、删除、重传回调并输出data-disabled供样式降级。理解这四者的作用域边界，即可在业务中精准构建"禁用上传、只读查看、纯文本回显"三类典型场景。

• 前端
• UI组件