Folder 文件夹

文件树组件，用于展示层级文件结构。对齐 React @ant-design/x Folder（2.4+，含 2.8 右键菜单）。

何时使用

展示文件/文件夹层级结构
需要文件选择、展开收起、预览与右键菜单
需要在目录树与预览区之间拖拽调整宽度

代码演示

基础用法

Project Files

App.vue

<script setup lang="ts">
const msg = 'Hello Folder';
</script>

<template>
  <div>{{ msg }}</div>
</template>

基础用法

展示文件树与内联内容预览。目录树与预览区之间可拖拽分隔条调整宽度。

自定义文件服务

通过 fileContentService 动态加载文件内容。

受控文件选择

guide.md

# Guide
Controlled selection.

受控文件选择

使用 selectedFile / onSelectedFileChange 受控选中文件。

自定义图标

readme.md

# Pages

自定义图标

通过 directoryIcons 自定义目录与扩展名图标；设为 false 可隐藏图标。

右键菜单

Right-click any file or folder

App.vue

<template><div>Hello</div></template>

右键菜单

支持全局 contextMenu 与节点级覆盖（含 false 禁用）。可配合 ref 的 updateNode / deleteNode / addNode 做不可变更新。

<script setup lang="tsx">
defineOptions({ name: 'AXFolderContextMenuV2' });

import {
  CopyOutlined,
  DeleteOutlined,
  EditOutlined,
  FileAddOutlined,
} from '@ant-design/icons-vue';
import { message, Space, Tag } from 'ant-design-vue';
import {
  Folder,
  type FolderProps,
  type FolderRef,
  type FolderTreeData,
} from 'ant-design-x-vue';
import { ref } from 'vue';

const initialTreeData: FolderProps['treeData'] = [
  {
    title: 'my-project',
    path: 'my-project',
    children: [
      {
        title: 'src',
        path: 'src',
        children: [
          {
            title: 'App.vue',
            path: 'App.vue',
            content: '<template><div>Hello</div></template>',
          },
        ],
      },
      {
        title: 'README.md',
        path: 'README.md',
        content: '# My Project',
        contextMenu: [
          { key: 'edit', label: 'Edit README', icon: <EditOutlined /> },
          { key: 'copy', label: 'Copy Path', icon: <CopyOutlined /> },
        ],
      },
    ],
  },
];

const folderRef = ref<FolderRef>();
const data = ref<FolderTreeData[]>(initialTreeData);
const lastAction = ref('');
let counter = 1;

const parseKey = (key: string) => key.split('/').filter(Boolean);

const baseMenu: FolderProps['contextMenu'] = (node) => {
  const isFolder = !!node.children && node.children.length > 0;
  if (isFolder) {
    return [
      { key: 'newFile', label: 'New File', icon: <FileAddOutlined /> },
      { key: 'copyPath', label: 'Copy Path', icon: <CopyOutlined /> },
      { type: 'divider' },
      { key: 'delete', label: 'Delete', icon: <DeleteOutlined />, danger: true },
    ];
  }
  return [
    { key: 'copyPath', label: 'Copy Path', icon: <CopyOutlined /> },
    { key: 'rename', label: 'Rename', icon: <EditOutlined /> },
    { type: 'divider' },
    { key: 'delete', label: 'Delete', icon: <DeleteOutlined />, danger: true },
  ];
};

const handleMenuAction = (actionKey: string, fullPathKey: string) => {
  const pathSegments = parseKey(fullPathKey);
  const api = folderRef.value;
  switch (actionKey) {
    case 'rename': {
      const newName = `renamed_${counter++}`;
      data.value = api?.updateNode(pathSegments, { title: newName, path: newName }) ?? data.value;
      message.success(`Renamed to ${newName}`);
      lastAction.value = `Rename: ${fullPathKey} → ${newName}`;
      break;
    }
    case 'delete': {
      data.value = api?.deleteNode(pathSegments) ?? data.value;
      message.success(`Deleted ${fullPathKey}`);
      lastAction.value = `Delete: ${fullPathKey}`;
      break;
    }
    case 'newFile': {
      const fileName = `new_file_${counter++}.ts`;
      data.value =
        api?.addNode(pathSegments, {
          title: fileName,
          path: fileName,
          content: `// ${fileName}`,
        }) ?? data.value;
      message.success(`Created ${fileName}`);
      lastAction.value = `New File: ${fileName}`;
      break;
    }
    case 'copyPath':
    case 'copy':
      navigator.clipboard?.writeText(fullPathKey);
      message.success(`Copied: ${fullPathKey}`);
      lastAction.value = `Copy Path: ${fullPathKey}`;
      break;
    case 'edit':
      message.info(`Edit: ${fullPathKey}`);
      lastAction.value = `Edit: ${fullPathKey}`;
      break;
    default:
      break;
  }
};

const contextMenuWithHandler: FolderProps['contextMenu'] = (node, key) => {
  const items = typeof baseMenu === 'function' ? baseMenu(node, key) : baseMenu;
  if (!items) return items;
  return items.map((item) => {
    if (item && 'key' in item) {
      return {
        ...item,
        onClick: () => handleMenuAction(String(item.key), key),
      };
    }
    return item;
  });
};

defineRender(() => (
  <div style={{ height: 420 }}>
    <Space style={{ marginBottom: 12, display: 'flex', flexWrap: 'wrap' }}>
      <Tag color="blue">Right-click any file or folder</Tag>
      {lastAction.value ? <Tag color="green">{lastAction.value}</Tag> : null}
    </Space>
    <Folder
      ref={folderRef as any}
      treeData={data.value}
      defaultSelectedFile={['my-project', 'src', 'App.vue']}
      contextMenu={contextMenuWithHandler}
      onRightClick={({ node }) => {
        lastAction.value = `Right-clicked: ${String(node?.title ?? node?.key)}`;
      }}
    />
  </div>
));
</script>

自定义预览

notes.txt

custom preview · lang=txt

line1
line2
line3

自定义预览

通过 previewRender 自定义预览区内容。

API

FolderProps

属性	说明	类型	默认值	版本
treeData	文件树数据	FolderTreeData[]	`[]`	-
selectable	是否开启选择功能	boolean	`true`	-
selectedFile	选中的文件路径（受控）	string[]	-	-
defaultSelectedFile	默认选中的文件路径	string[]	`[]`	-
onSelectedFileChange	文件选择变化时的回调	(file: { path: string[]; title?: FolderTreeData['title']; content?: string }) => void	-	-
directoryTreeWith	目录树初始宽度（可拖拽分隔条调整）	number \| string	`278`	-
emptyRender	空状态展示，设为 `false` 时不展示	false \| VNode \| string \| (() => VNode \| string \| null)	-	-
previewRender	自定义文件预览内容	VNode \| string \| ((file, info) => VNode \| string \| null)	-	-
expandedPaths	展开的节点路径（受控）	string[]	-	-
defaultExpandedPaths	默认展开的节点路径	string[]	-	-
defaultExpandAll	是否默认展开所有节点	boolean	`true`	-
onExpandedPathsChange	展开/收起变化回调	(paths: string[]) => void	-	-
fileContentService	文件内容服务	FileContentService	-	-
onFileClick	文件点击事件	(filePath: string, content?: string) => void	-	-
onFolderClick	文件夹点击事件	(folderPath: string) => void	-	-
directoryTitle	目录树标题，设为 `false` 时不展示	false \| VNode \| string \| (() => VNode \| string \| null)	-	-
previewTitle	文件预览标题	false \| VNode \| string \| (({ title, path, content }) => VNode \| string \| null)	-	-
directoryIcons	自定义图标，设为 `false` 时不展示	false \| Record<'directory' \| string, VNode \| string \| (() => ...)>	-	-
contextMenu	右键菜单（全局），可被节点 `contextMenu` 覆盖	MenuProps['items'] \| ((node, key) => MenuProps['items'])	-	-
onRightClick	右键点击节点回调	(info: { event, node }) => void	-	-
classNames	语义化 className	Record<SemanticType, string>	-	-
styles	语义化 style	Record<SemanticType, CSSProperties>	-	-

FolderTreeData

属性	说明	类型	默认值
title	显示名称	string \| VNode	-
path	路径段	string	-
content	文件内容（可选）	string	-
children	子项	FolderTreeData[]	-
contextMenu	节点右键菜单，`false` 禁用	MenuProps['items'] \| false \| ((key) => ...)	-

FileContentService

interface FileContentService {
  loadFileContent(filePath: string): Promise<string>;
}

Ref 方法

const folderRef = ref<FolderRef>();

folderRef.value?.getNode(['src', 'App.tsx']);
folderRef.value?.updateNode(['src', 'App.tsx'], { title: 'Main.tsx', path: 'Main.tsx' });
folderRef.value?.deleteNode(['src', 'unused.ts']);
folderRef.value?.addNode(['src'], { title: 'new.ts', path: 'new.ts', content: '' });

方法	说明	类型
getNode	根据路径获取节点	(path: string[]) => FolderTreeData \| undefined
updateNode	不可变更新节点，返回新 treeData	(path, data) => FolderTreeData[]
deleteNode	不可变删除节点，返回新 treeData	(path) => FolderTreeData[]
addNode	不可变新增子节点，返回新 treeData	(parentPath, node) => FolderTreeData[]

语义化结构

:::semantic

folder

:::

Folder 文件夹 ​

何时使用 ​

代码演示 ​

基础用法 ​

自定义文件服务 ​

受控文件选择 ​

自定义图标 ​

右键菜单 ​

自定义预览 ​

API ​

FolderProps ​

FolderTreeData ​

FileContentService ​

Ref 方法 ​

语义化结构 ​

Folder 文件夹

何时使用

代码演示

基础用法

自定义文件服务

受控文件选择

自定义图标

右键菜单

自定义预览

API

FolderProps

FolderTreeData

FileContentService

Ref 方法

语义化结构