懒猫文件选择器

一个用于快速实现网盘文件选择和保存功能的Vue组件。

功能特性

• 🚀 快速集成，开箱即用
• 📁 支持文件、目录和另存为
• 🎯 多种文件类型过滤
• 📋 多选和单选模式
• 🎨 弹窗和嵌入两种显示模式
• 🔍 支持多种文件来源（收藏、网络目录、外接硬盘等）
• 📝 完整的TypeScript类型支持

安装

npm install --save @lazycatcloud/lzc-file-pickers

快速开始

1. 注册组件

在 main.ts 或 main.js 中导入组件：

import "@lazycatcloud/lzc-file-pickers"

2. 在Vue组件中使用

<template>
  <lzc-file-picker
    type="file"
    base-url="/_lzc/files/home"
    accept="video/*"
    :source="['新文件名']"
    :filter-select-visible="true"
    :multiple="true"
    :is-modal="true"
    :choice-file-only="true"
    title="选择视频文件"
    confirm-button-title="确认选择"
    @close="handleClose"
    @submit="handleSubmit"
  />
</template>

<script>
export default {
  methods: {
    handleClose() {
      console.log('文件选择器已关闭')
    },
    handleSubmit(files, source) {
      console.log('选中的文件:', files)
      console.log('业务字段 source:', source)
    }
  }
}
</script>

3. TypeScript 支持

组件提供完整的TypeScript类型支持：

import type { 
  filePickerPropsType, 
  filePickerType, 
  tableListType 
} from '@lazycatcloud/lzc-file-pickers'

// 使用类型
const props: filePickerPropsType = {
  type: filePickerType.file,
  title: '选择文件',
  multiple: true
}

API 参考

组件属性

| 属性名 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | type | filePickerType | - | 选择类型：file、directory 或 saveAs | | title | string | - | 选择器标题 | | rootpath | string | - | 根路径，如 /home/pictures | | rootname | string | - | 根路径显示名称 | | source | string[] | - | 底部“名称”业务字段值；根据长度控制展示/编辑态，并在 submit 时回传 | | accept | string | - | 文件类型过滤（MIME类型） | | confirmButtonTitle | string | - | 确认按钮文本 | | tableList | tableListType[] | - | 显示的标签页类型 | | multiple | boolean | false | 是否支持多选 | | isModal | boolean | false | 是否以弹窗形式显示 | | choiceFileOnly | boolean | false | 是否只允许选择文件 | | choiceDirOnly | boolean | false | 是否只允许选择目录 | | boxId | string | - | 懒猫微服名称 | | extname | string | - | 文件后缀过滤（使用,分隔） | | filterSelectVisible | boolean | false | 是否显示扩展名筛选下拉（自定义扩展名/全部文件） | | ignorePath | string[] | - | 文件路径过滤 |

类型定义

// 选择器类型
export enum filePickerType {
  file = "file",           // 文件选择
  directory = "directory", // 目录选择
  saveAs = "saveAs"        // 另存为
}

// 标签页类型
export enum tableListType {
  collect = "collect",           // 收藏
  networkDir = "networkDir",     // 全部文件
  externalHardDrive = "externalHardDrive", // 外接硬盘
  appData = "appData",           // 应用数据
  fileMount = "fileMount"        // 远程挂载
}

// 组件属性接口
export interface filePickerPropsType {
  boxId?: string;
  type: filePickerType;
  title?: string;
  rootpath?: string;
  rootname?: string;
  source?: string[];
  accept?: string;
  extname?: string;
  filterSelectVisible?: boolean;
  confirmButtonTitle?: string;
  tableList?: tableListType[];
  multiple?: boolean;
  isModal?: boolean;
  choiceFileOnly?: boolean;
  choiceDirOnly?: boolean;
  ignorePath?: string[];
}

事件

| 事件名 | 参数 | 说明 | |--------|------|------| | @close | - | 选择器点击取消时触发 | | @submit | files: File[], source?: string[] | 确认选择时触发，返回选中的文件列表和业务字段 source（可选） |

参数行为说明

• source

  • 类型：string[] | undefined。
  • undefined：不显示“名称”输入，不参与提交校验。
  • 长度为 1：显示可编辑输入框，用户修改后会更新并在 submit(files, source?) 回传。
  • 长度大于 1：只读展示，提交原值。
  • 长度为 0：确认按钮禁用。
  • 对接建议：不要传 []，要么不传，要么传 ["默认名"]。

• filterSelectVisible

  • 类型：boolean，默认 false。
  • true：底部显示扩展名筛选下拉。
  • 与 extname 联动：
    • false 时始终按 props.extname 过滤。
    • true 时可在“自定义扩展名/全部文件”间切换；切到“全部文件”会把扩展名过滤置空。
  • 切换筛选策略后会重新加载列表。

使用示例

基础文件选择

<lzc-file-picker
  type="file"
  title="选择文件"
  @submit="handleFileSelect"
/>

多选视频文件

<lzc-file-picker
  type="file"
  accept="video/*"
  :multiple="true"
  title="选择视频文件"
  confirm-button-title="确认选择"
  @submit="handleVideoSelect"
/>

目录选择

<lzc-file-picker
  type="directory"
  :choice-dir-only="true"
  title="选择目录"
  @submit="handleDirSelect"
/>

另存为

<lzc-file-picker
  type="saveAs"
  title="保存文件"
  confirm-button-title="确认保存"
  @submit="handleSaveAs"
/>

saveAs 模式下，弹出框内部会提供文件名输入框，由用户自行填写。

弹窗模式

<lzc-file-picker
  type="file"
  :is-modal="true"
  title="选择文件"
  @close="handleClose"
  @submit="handleSubmit"
/>

TypeScript 完整示例

<template>
  <lzc-file-picker
    :type="pickerType"
    :title="pickerTitle"
    :multiple="isMultiple"
    :accept="fileTypes"
    @submit="onFileSelect"
    @close="onClose"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import type { filePickerType, filePickerPropsType } from '@lazycatcloud/lzc-file-pickers'

const pickerType = ref<filePickerType>(filePickerType.file)
const pickerTitle = ref('选择文件')
const isMultiple = ref(true)
const fileTypes = ref('image/*,video/*')

const onFileSelect = (files: File[], source?: string[]) => {
  console.log('选中的文件:', files)
  console.log('业务字段 source:', source)
}

const onClose = () => {
  console.log('选择器已关闭')
}
</script>

许可证

MIT License