组件：文件选择框

文件选择框组件用于让用户从本地设备中选择一个或多个文件，支持多种文件类型过滤、多选、从摄像头/麦克风等媒体设备捕获（移动端），并提供了文件选择完毕的回调事件。它基于 HTML <input type="file"> 元素封装，适用于文件上传、图片选择、文档导入等需要用户选取文件的场景。

典型使用场景：

  • 用户头像上传（选择图片）
  • 文件上传（选择文档、压缩包等）
  • 批量导入（选择 CSV、Excel 数据文件）
  • 拍照/录像上传（移动端调用摄像头直接拍摄）
  • 附件上传（邮件、工单、消息中的附件）

📌 继承自视图的成员速查

本组件继承自 视图 类，可直接使用以下属性和方法：

属性： ID、左边、顶边、右边、底边、宽度、高度、背景、背景颜色、背景图像、文本、文本颜色、字体、字体大小、字体粗细、行高、边框、边框圆角、边框宽度、光标样式、显示模式、透明度、外边距、外边距底、外边距左、外边距右、外边距顶、最大高度、最大宽度、最小高度、最小宽度、内边距、内边距底、内边距左、内边距右、内边距顶、定位、CLASS、InnerHTML、OuterHTML、内容水平对齐方式、首行缩进、可视、显示层级、内联样式、禁用

方法： 追加内联样式(样式文本)、置内联样式(名称,值)、取内联样式值(名称)、取Style对象()、添加事件(事件名称, 回调函数)、删除事件(事件名称, 回调函数)、获取焦点()、清除焦点()、添加样式类(类名称)、移除样式类(类名称)、取样式类列表()、取样式类()、执行单击()、取属性值(属性名)、取属性节点(属性名)、取布局参数()、取渲染宽度()、取渲染高度()、取渲染顶边()、取渲染左边()、左侧对齐到(目标组件,偏移量)、右侧对齐到(目标组件,偏移量)、顶边对齐到(目标组件,偏移量)、底边对齐到(目标组件,偏移量)、右侧对齐到左(目标组件, 偏移量)、左侧对齐到右(目标组件, 偏移量)、底边对齐到顶(目标组件, 偏移量)、顶边对齐到底(目标组件, 偏移量)、有指定属性(属性名)、有属性()、内容可编辑()、包含CSS类(类名)、取命名空间()、取下个节点()、取下个元素()、取节点名称()、取节点类型()、取父节点()、取父元素()、取上个节点()、取上个元素()、销毁()、删除属性(属性名)、删除属性节点(属性名)、置属性值(属性名, 属性值)、置属性节点(属性节点)、取标签名()、移动(左边 顶边, 宽度, 高度)、取原生对象()、置被单击回调(回调函数)、置被双击回调(回调函数)、置鼠标被进入回调(回调函数)、置鼠标被移出回调(回调函数)、置鼠标被移动回调(回调函数)、置鼠标被按下回调(回调函数)、置鼠标被抬起回调(回调函数)、置鼠标滚轮被滚动回调(回调函数)、置键盘被按下回调(回调函数)、置按键被抬起回调(回调函数)、置按键被压下回调(回调函数)、置被失去焦点回调(回调函数)、置被获得焦点回调(回调函数)

事件： 被单击(源对象,事件源)、被双击(源对象,事件源)、鼠标被进入(源对象,事件源)、鼠标被移出(源对象,事件源)、鼠标被移动(源对象,事件源)、鼠标被按下(源对象,事件源)、鼠标被抬起(源对象,事件源)、鼠标滚轮被滚动(源对象,事件源)、键盘被按下(源对象,事件源)、按键被抬起(源对象,事件源)、按键被压下(源对象,事件源)、被失去焦点(源对象,事件源)、被获得焦点(源对象,事件源)

💡 完整成员列表及详细说明请参考：视图 类

常用操作速查

操作属性/方法示例
启用/禁多选多选文件选择框1.多选 = 真
限制文件类型接受类型文件选择框1.接受类型 = "image/*"
设置按钮文本按钮文本文件选择框1.按钮文本 = "选择图片"
禁用/启用组件禁用文件选择框1.禁用 = 真
获取所有已选文件取文件列表()变量 文件列表 = 文件选择框1.取文件列表()
获取指定索引的文件取文件(索引)变量 文件对象 = 文件选择框1.取文件(0)
清空已选文件清空()文件选择框1.清空()
设置选择完成回调置文件选择完毕回调(回调函数)文件选择框1.置文件选择完毕回调((源对象, 文件列表) => { ... })

样式美化参考

文件选择框的外观主要通过继承的视图属性和 CSS 类进行美化：

  • 整体容器：通过 宽度、高度、背景颜色、边框（如 "1px solid #d9d9d9"）、边框圆角（建议 "6px"）等属性美化。
  • 按钮文本：按钮文本 设置显示在按钮上的文字，默认 "选择文件"。按钮样式由组件内部控制，但可通过 CSS 类覆盖背景色、文字颜色等。
  • 文件列表显示：组件本身不显示已选文件列表，需通过回调自行处理显示逻辑。
  • 禁用状态：禁用 = 真 时，按钮变灰且不可点击。

CSS 美化示例（在项目 CSS 文件中定义）：

.my-file-input {
    border: 1px solid #d9d9d9;
    border-radius: 6px;
    padding: 4px 8px;
    font-size: 14px;
    background-color: #ffffff;
    transition: border-color 0.3s;
}
.my-file-input:hover {
    border-color: #1890ff;
}
.my-file-input:disabled {
    background-color: #f5f5f5;
    cursor: not-allowed;
}

在代码中应用样式类：文件选择框1.添加样式类("my-file-input")

基础示例

创建一个文件选择框，仅接受图片类型，支持多选，选择后输出文件信息。

变量 文件选择框1 = 创建 文件选择框()
文件选择框1.左边 = 50
文件选择框1.顶边 = 50
文件选择框1.宽度 = 160
文件选择框1.高度 = 36
文件选择框1.按钮文本 = "选择图片"
文件选择框1.接受类型 = "image/*"
文件选择框1.多选 = 真
文件选择框1.边框 = "1px solid #d9d9d9"
文件选择框1.边框圆角 = "6px"
文件选择框1.背景颜色 = "#ffffff"

文件选择框1.置文件选择完毕回调((源对象, 文件列表) => {
    变量 数量 = 取数组成员数(文件列表)
    调试输出("选择了 " + 数量 + " 个文件")
    变量循环(i = 0, 数量, 1)
        变量 文件 = 文件列表[i]
        调试输出("文件 " + (i+1) + "：" + 文件.name + "，大小：" + 文件.size + " 字节")
    结束循环
})

添加组件(文件选择框1)

综合示例：头像上传与预览

本示例构建一个头像上传功能，用户选择图片后立即显示预览，并展示文件信息，同时提供“上传”和“清除”按钮。

' ========== 创建布局 ==========
变量 主容器 = 创建 弹性布局()
主容器.方向 = "column"
主容器.宽度 = 400
主容器.左边 = 50
主容器.顶边 = 30
主容器.间距 = 12
添加组件(主容器)

' 标题
变量 标题 = 创建 标签()
标题.文本 = "👤 头像上传"
标题.字体大小 = "20px"
标题.字体粗细 = "bold"
主容器.添加组件(标题)

' 头像预览区域
变量 预览容器 = 创建 弹性布局()
预览容器.方向 = "row"
预览容器.侧轴对齐 = "center"
预览容器.主轴对齐 = "center"
预览容器.宽度 = 120
预览容器.高度 = 120
预览容器.背景颜色 = "#f0f0f0"
预览容器.边框 = "1px dashed #d9d9d9"
预览容器.边框圆角 = "60px"  ' 圆形
预览容器.溢出隐藏 = "hidden"
主容器.添加组件(预览容器)

变量 预览图片 = 创建 图片框()
预览图片.图片宽度 = 120
预览图片.图片高度 = 120
预览图片.图片显示模式 = "cover"
预览图片.替代文本 = "头像预览"
预览容器.添加组件(预览图片)

' 文件选择框
变量 文件选择框1 = 创建 文件选择框()
文件选择框1.宽度 = 160
文件选择框1.高度 = 36
文件选择框1.按钮文本 = "选择图片"
文件选择框1.接受类型 = "image/*"
文件选择框1.多选 = 假
文件选择框1.边框 = "1px solid #1890ff"
文件选择框1.边框圆角 = "6px"
主容器.添加组件(文件选择框1)

' 文件信息标签
变量 信息标签 = 创建 标签()
信息标签.文本 = "未选择文件"
信息标签.字体大小 = "14px"
信息标签.文本颜色 = "#999"
主容器.添加组件(信息标签)

' 操作按钮组
变量 按钮组 = 创建 弹性布局()
按钮组.方向 = "row"
按钮组.间距 = 12
主容器.添加组件(按钮组)

变量 上传按钮 = 创建 按钮()
上传按钮.文本 = "上传"
上传按钮.宽度 = 80
上传按钮.高度 = 32
上传按钮.背景颜色 = "#52c41a"
上传按钮.文本颜色 = "#ffffff"
上传按钮.边框圆角 = "6px"
上传按钮.禁用 = 真
按钮组.添加组件(上传按钮)

变量 清除按钮 = 创建 按钮()
清除按钮.文本 = "清除"
清除按钮.宽度 = 80
清除按钮.高度 = 32
清除按钮.背景颜色 = "#d9d9d9"
清除按钮.文本颜色 = "#333"
清除按钮.边框圆角 = "6px"
清除按钮.禁用 = 真
按钮组.添加组件(清除按钮)

' ========== 事件绑定 ==========
' 选择文件回调
文件选择框1.置文件选择完毕回调((源对象, 文件列表) => {
    如果(取数组成员数(文件列表) > 0)
        变量 文件 = 文件列表[0]
        ' 显示文件信息
        信息标签.文本 = "已选：" + 文件.name + "（" + 文件.size + " 字节）"
        ' 预览图片（通过创建临时URL）
        变量 图片URL = URL.createObjectURL(文件)
        预览图片.图片 = 图片URL
        预览图片.替代文本 = 文件.name
        ' 启用按钮
        上传按钮.禁用 = 假
        清除按钮.禁用 = 假
    否则
        信息标签.文本 = "未选择文件"
        预览图片.图片 = ""
        上传按钮.禁用 = 真
        清除按钮.禁用 = 真
    结束 如果
})

' 上传按钮
上传按钮.置被单击回调((源对象) => {
    变量 文件列表 = 文件选择框1.取文件列表()
    如果(取数组成员数(文件列表) == 0)
        弹出提示("请先选择图片")
        返回
    结束 如果
    变量 文件 = 文件列表[0]
    ' 模拟上传
    上传按钮.禁用 = 真
    上传按钮.文本 = "上传中..."
    延时执行(() => {
        上传按钮.禁用 = 假
        上传按钮.文本 = "上传"
        弹出提示("上传成功：" + 文件.name)
    }, 1500)
})

' 清除按钮
清除按钮.置被单击回调((源对象) => {
    文件选择框1.清空()  ' 清空已选文件
    预览图片.图片 = ""
    信息标签.文本 = "未选择文件"
    上传按钮.禁用 = 真
    清除按钮.禁用 = 真
    弹出提示("已清除")
})

属性详解

多选

  • 类型： 逻辑型
  • 说明： 设置或获取是否允许用户一次选择多个文件。当为 真 时，文件选择对话框中可按住 Ctrl 或 Shift 键选择多个文件。默认 假。

接受类型

  • 类型： 文本型
  • 说明： 设置或获取允许选择的文件类型，用于过滤文件对话框中的可选文件。支持以下格式：
    • MIME 类型：如 "image/png"、"application/pdf"
    • 通配符：如 "image/*"（所有图片）、"audio/*"（所有音频）
    • 文件扩展名：如 ".doc"、".xlsx"
    • 多个值用逗号分隔：如 "image/*,.pdf,.doc" 默认为空（允许所有文件类型）。

调用源

  • 类型： 文本型
  • 说明： 设置或获取媒体捕获源，主要用于移动端设备，可让用户直接从摄像头或麦克风捕获媒体。可选值：
    • "user"：使用前置摄像头（自拍）
    • "environment"：使用后置摄像头 通常与 接受类型 配合使用，如 接受类型 = "image/*" 且 调用源 = "environment" 时，会弹出拍照选项。 默认为空（使用系统默认文件选择器）。

禁用

  • 类型： 逻辑型
  • 说明： 设置或获取是否禁用组件。禁用后，按钮不可点击，样式变灰。默认 假。

按钮文本

  • 类型： 文本型
  • 说明： 设置或获取选择按钮上显示的文本。默认 "选择文件"。可以自定义为更符合场景的文字，如 "选择图片"、"上传文档" 等。

函数详解

取文件列表()

  • 功能： 获取当前已选择的所有文件列表。
  • 返回值： 数组，包含 File 对象（每个文件包含 name、size、type、lastModified 等属性）。若未选择任何文件，返回空数组 []。
  • 示例： 
    变量 文件列表 = 文件选择框1.取文件列表()
变量循环(i = 0, 取数组成员数(文件列表), 1)
    变量 文件 = 文件列表[i]
    调试输出("文件名：" + 文件.name)
结束循环

取文件(索引)

  • 功能： 获取指定索引位置的文件对象。
  • 参数： 索引（数值型），从 0 开始。若省略索引，则默认取第一个文件（索引 0）。
  • 返回值： File 对象，如果索引无效则返回 空。
  • 示例： 变量 文件 = 文件选择框1.取文件(0)

清空()

  • 功能： 清空当前已选择的文件列表，重置组件状态。调用后，界面上的文件选择按钮会恢复为未选择状态，且触发回调（文件列表为空）。
  • 返回值： 无。
  • 示例： 文件选择框1.清空()

置文件选择完毕回调(回调函数)

  • 功能： 设置当用户完成文件选择（点击“确定”按钮）时的回调函数。无论选择了一个还是多个文件，都会触发。
  • 参数： 回调函数，格式为 (源对象, 文件列表) => { ... }。
    • 源对象：文件选择框组件本身。
    • 文件列表：包含已选文件的数组（File 对象列表）。
  • 返回值： 无。
  • 示例： 
    文件选择框1.置文件选择完毕回调((源对象, 文件列表) => {
    弹出提示("选择了 " + 取数组成员数(文件列表) + " 个文件")
})

事件说明

文件选择完毕(源对象, 文件列表)

  • 功能： 与 置文件选择完毕回调 等效，适用于设计文件（.spldg）中定义的组件。
  • 示例： 
    事件 文件选择框1.文件选择完毕(源对象, 文件列表)
    调试输出("已选文件数：" + 取数组成员数(文件列表))
结束 事件

⚠️ 注意事项

  1. 文件对象属性：File 对象包含 name（文件名）、size（字节大小）、type（MIME 类型）、lastModified（最后修改时间戳）等属性，可在回调中直接使用。
  2. 多选模式：设置 多选 = 真 后，用户可一次选择多个文件，取文件列表() 返回数组；若 多选 = 假，则只允许选择一个文件，但 取文件列表() 仍然返回数组（长度为 1）。
  3. 文件类型过滤：接受类型 只是前端提示，用户仍可切换为“所有文件”绕过限制，后端需再次校验。
  4. 调用源（capture）：在移动端且支持的情况下，设置 调用源 后，文件选择器会直接打开相机/麦克风，而不显示文件列表。建议搭配 接受类型 使用。
  5. 清空行为：调用 清空() 会重置文件选择框，但不会自动触发回调。如需在清空后执行逻辑，可手动调用回调处理。
  6. 预览图片：可使用 URL.createObjectURL(文件) 生成临时 URL 用于图片预览，但需注意内存释放（调用 URL.revokeObjectURL(url)）。
  7. 文件大小：文件.size 以字节为单位，可转换为 KB/MB 显示。
  8. 禁用状态：禁用 = 真 时，按钮不可用，但仍然可以通过代码调用 取文件列表() 等方法获取之前选择的结果（如果有）。
  9. 事件触发时机：置文件选择完毕回调 在用户点击“确定”后触发，若用户取消选择，则不会触发回调。

相关文档

  • 文档框架基础类_视图 —— 视图类提供的所有通用属性和方法
  • 文档图像类组件_图片框 —— 配合预览图片
  • 文档轻语言网站：轻语言语法速查 —— 拉姆达表达式、数组操作等
  • 文档综合演示：头像上传与预览 —— 实际应用示例