@lazycatcloud/lzc-file-pickers

懒猫文件选择器

一个用于快速实现网盘文件选择和保存功能的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 参考

组件属性

类型定义

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

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

export type filePickerThemeMode = "system" | "light" | "dark";

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

事件

参数行为说明

• 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