Tree Item 自定义

了解如何自定义 Tree Item 组件。

解剖

每个 Tree Item 组件都由一系列可组合的插槽构成。将鼠标悬停在下面的演示上以查看每个插槽。

内容

使用 content 插槽来自定义 Tree Item 的内容或将其替换为自定义组件。

插槽 props

slotProps prop 允许您将 props 传递给 content 组件。下面的演示展示了如何将 sx 处理程序传递给 Tree Item 的内容

数据表格
日期和时间选择器
图表
树状视图

<RichTreeView
  defaultExpandedItems={['pickers']}
  items={MUI_X_PRODUCTS}
  slots={{ item: CustomTreeItem }}
/>

<RichTreeView
  defaultExpandedItems={['pickers']}
  items={MUI_X_PRODUCTS}
  slots={{ item: CustomTreeItem }}
/>

按下 Enter 键开始编辑

插槽

下面的演示展示了如何使用自定义组件替换 content 插槽。

数据表格
日期和时间选择器
图表
树状视图

<RichTreeView
  defaultExpandedItems={['pickers']}
  defaultSelectedItems={'grid'}
  items={MUI_X_PRODUCTS}
  slots={{ item: CustomTreeItem }}
  isItemDisabled={(item) => Boolean(item?.disabled)}
/>

<RichTreeView
  defaultExpandedItems={['pickers']}
  defaultSelectedItems={'grid'}
  items={MUI_X_PRODUCTS}
  slots={{ item: CustomTreeItem }}
  isItemDisabled={(item) => Boolean(item?.disabled)}
/>

按下 Enter 键开始编辑

复选框

当在 Tree View 上启用 checkboxSelection 时，复选框会出现在项目上。

插槽 props

您可以使用 Tree Item 2 组件上的 slotProps 将 props 传递给 checkbox 插槽。

<RichTreeView
  defaultExpandedItems={['grid', 'pickers']}
  checkboxSelection
  items={MUI_X_PRODUCTS}
  slots={{ item: CustomTreeItem }}
/>

<RichTreeView
  defaultExpandedItems={['grid', 'pickers']}
  checkboxSelection
  items={MUI_X_PRODUCTS}
  slots={{ item: CustomTreeItem }}
/>

按下 Enter 键开始编辑

插槽

下面的演示展示了如何使用自定义组件替换 checkbox 插槽。

<RichTreeView
  defaultExpandedItems={['grid', 'pickers']}
  checkboxSelection
  items={MUI_X_PRODUCTS}
  slots={{ item: CustomTreeItem }}
/>

<RichTreeView
  defaultExpandedItems={['grid', 'pickers']}
  checkboxSelection
  items={MUI_X_PRODUCTS}
  slots={{ item: CustomTreeItem }}
/>

按下 Enter 键开始编辑

基础知识

更改嵌套项目的缩进

使用 itemChildrenIndentation prop 来更改嵌套项目的缩进。默认情况下，嵌套项目从其父项目缩进 12px。

数据表格
日期和时间选择器
图表
树状视图

<RichTreeView
  items={MUI_X_PRODUCTS}
  itemChildrenIndentation={24}
  defaultExpandedItems={['grid']}
/>

<RichTreeView
  items={MUI_X_PRODUCTS}
  itemChildrenIndentation={24}
  defaultExpandedItems={['grid']}
/>

按下 Enter 键开始编辑

此功能与 <TreeItem /> 和 <TreeItem2 /> 组件都兼容。如果您正在使用自定义 Tree Item 组件，并且想要覆盖 padding，请将以下 padding 应用于您的 groupTransition 元素

const CustomTreeItem2GroupTransition = styled(TreeItem2GroupTransition)(({ theme }) => ({
  // ...other styles
  paddingLeft: `var(--TreeView-itemChildrenIndentation)`,
}

如果您正在使用 indentationAtItemLevel prop，则改为将以下 padding 应用于您的 content 元素

const CustomTreeItem2Content = styled(TreeItem2Content)(({ theme }) => ({
  // ...other styles
  paddingLeft:
      `calc(${theme.spacing(1)} + var(--TreeView-itemChildrenIndentation) * var(--TreeView-itemDepth))`,
}

在项目级别应用嵌套项目的缩进

默认情况下，嵌套项目的缩进由其父级的 groupTransition 插槽应用（即：包装给定项目的所有子项的 DOM 元素）。此方法与即将推出的功能（例如使用拖放重新排序项目）不兼容。

要在项目级别应用缩进（即：让每个项目负责使用其 content 插槽上的 padding-left CSS 属性设置自己的缩进），您可以使用 indentationAtItemLevel 实验性功能。它将成为 Tree View 组件的下一个主要版本中的默认行为。

数据表格
日期和时间选择器
图表
树状视图

<RichTreeView
  items={MUI_X_PRODUCTS}
  experimentalFeatures={{ indentationAtItemLevel: true }}
  defaultExpandedItems={['grid']}
/>

<RichTreeView
  items={MUI_X_PRODUCTS}
  experimentalFeatures={{ indentationAtItemLevel: true }}
  defaultExpandedItems={['grid']}
/>

按下 Enter 键开始编辑

此功能与 <TreeItem /> 和 <TreeItem2 /> 组件以及 itemChildrenIndentation prop 兼容。如果您正在使用自定义 Tree Item 组件，并且想要覆盖 padding，请将以下 padding 应用于您的 content 元素

const CustomTreeItem2Content = styled(TreeItem2Content)(({ theme }) => ({
  // ...other styles
  paddingLeft:
      `calc(${theme.spacing(1)} + var(--TreeView-itemChildrenIndentation) * var(--TreeView-itemDepth))`,
}

Hooks

useTreeItem2

useTreeItem2 hook 允许您管理和自定义单个 Tree Item。您可以使用它来获取所有插槽所需的属性、任何给定项目的状态，或利用 Tree View 的交互式 API。

插槽属性

useTreeItem2 hook 通过提供解析器来获取每个插槽的适当 props，从而让您可以精细地控制项目的布局。这使得为您的 Tree Item 构建完全自定义的布局成为可能。

下面的演示展示了如何获取每个插槽所需的 props，以及如何正确传递它们。

<RichTreeView
  items={MUI_X_PRODUCTS}
  defaultExpandedItems={['grid']}
  slots={{ item: CustomTreeItem }}
  checkboxSelection
  isItemEditable
  experimentalFeatures={{
    labelEditing: true,
  }}
/>

<RichTreeView
  items={MUI_X_PRODUCTS}
  defaultExpandedItems={['grid']}
  slots={{ item: CustomTreeItem }}
  checkboxSelection
  isItemEditable
  experimentalFeatures={{
    labelEditing: true,
  }}
/>

按下 Enter 键开始编辑

您可以通过将对象参数传递给插槽的 props 解析器，将其他 props 传递给插槽—或覆盖现有插槽，如下所示

<CustomTreeItemContent
  {...getContentProps({
    className: 'overridingClassName',
    newProp: 'I am passing this to the content slot'
  })}
>

项目状态

useTreeItem2 hook 还返回一个 status 对象，该对象保存 Tree Item 的每个可能状态的布尔值。

const {
  status: { expanded, expandable, focused, selected, disabled, editable, editing },
} = useTreeItem2(props);

您可以使用这些状态来将自定义样式应用于项目或有条件地渲染子组件。

数据表格
日期和时间选择器
图表
树状视图

图例

focused（聚焦）

selected（已选择）

expandable（可展开）

expanded（已展开）

disabled（已禁用）

editable（可编辑）

editing（正在编辑）

<Box sx={{ minHeight: 200, minWidth: 350 }}>
  <RichTreeView
    items={MUI_X_PRODUCTS}
    defaultExpandedItems={['pickers']}
    defaultSelectedItems={'pickers'}
    slots={{ item: CustomTreeItem }}
    isItemDisabled={(item) => Boolean(item?.disabled)}
    isItemEditable={(item) => Boolean(item?.editable)}
    experimentalFeatures={{
      labelEditing: true,
    }}
  />
</Box>
<StatusLegend />

<Box sx={{ minHeight: 200, minWidth: 350 }}>
  <RichTreeView
    items={MUI_X_PRODUCTS}
    defaultExpandedItems={['pickers']}
    defaultSelectedItems={'pickers'}
    slots={{ item: CustomTreeItem }}
    isItemDisabled={(item) => Boolean(item?.disabled)}
    isItemEditable={(item) => Boolean(item?.editable)}
    experimentalFeatures={{
      labelEditing: true,
    }}
  />
</Box>
<StatusLegend />

按下 Enter 键开始编辑

命令式 API

publicAPI 对象提供了许多以编程方式与 Tree View 交互的方法。您可以使用 useTreeItem2 hook 从 Tree Item 内部访问 publicAPI 对象。

数据表格
3
日期和时间选择器
2
图表
1
树状视图
1

<RichTreeView
  defaultExpandedItems={['pickers']}
  items={MUI_X_PRODUCTS}
  slots={{ item: CustomTreeItem }}
/>

<RichTreeView
  defaultExpandedItems={['pickers']}
  items={MUI_X_PRODUCTS}
  slots={{ item: CustomTreeItem }}
/>

按下 Enter 键开始编辑

请参阅每个功能页面上的命令式 API部分，以了解有关 Tree View 上可用的公共 API 方法的更多信息。

`useTreeItem2Utils`

useTreeItem2Utils hook 提供了一组交互方法，用于为 Tree View 实现自定义行为。它还返回项目的状态。

const { interactions, status } = useTreeItem2Utils({
  itemId: props.itemId,
  children: props.children,
});

要覆盖 Tree Item 的默认交互，请在事件处理程序中将 event.defaultMuiPrevented 设置为 true，然后实现您自己的行为。

选择

您可以通过单击 Tree View 中的项目的 content 插槽来选择它。下面的演示展示了当用户单击图标时如何处理选择。

数据表格
日期和时间选择器
图表
树状视图

<RichTreeView
  defaultExpandedItems={['grid', 'pickers']}
  items={MUI_X_PRODUCTS}
  slots={{ item: CustomTreeItem }}
  expansionTrigger="iconContainer"
/>

<RichTreeView
  defaultExpandedItems={['grid', 'pickers']}
  items={MUI_X_PRODUCTS}
  slots={{ item: CustomTreeItem }}
  expansionTrigger="iconContainer"
/>

按下 Enter 键开始编辑

复选框选择

默认情况下，如果项目被禁用或 Tree View 上的 disableSelection 为 true，则跳过复选框选择。您可以为 checkbox 插槽上的 onChange 事件创建自定义处理程序，以绕过这些条件。下面的演示展示了如何实现自定义复选框选择行为。

<RichTreeView
  defaultExpandedItems={['grid', 'pickers']}
  checkboxSelection
  items={MUI_X_PRODUCTS}
  slots={{ item: CustomTreeItem }}
/>

<RichTreeView
  defaultExpandedItems={['grid', 'pickers']}
  checkboxSelection
  items={MUI_X_PRODUCTS}
  slots={{ item: CustomTreeItem }}
/>

按下 Enter 键开始编辑

请访问富树状视图或简易树状视图文档，分别了解有关选择 API 的更多详细信息。

展开

默认情况下，当用户单击其内容时，Tree Item 会展开。您可以使用 iconContainer 上的 expansionTrigger prop 更改展开触发器。有关更多详细信息，请参阅展开—将展开限制为图标容器。

使用 handleExpansion 交互方法可以更深入地自定义项目的展开行为。

下面的演示展示了如何引入一个新元素来展开和折叠项目。

数据表格
日期和时间选择器
图表
树状视图

<RichTreeView
  items={MUI_X_PRODUCTS}
  defaultExpandedItems={['grid']}
  slots={{ item: CustomTreeItem }}
/>

<RichTreeView
  items={MUI_X_PRODUCTS}
  defaultExpandedItems={['grid']}
  slots={{ item: CustomTreeItem }}
/>

按下 Enter 键开始编辑

标签编辑

useTreeItem2Utils hook 提供了以下与标签编辑行为相关的交互方法

const {
  interactions: {
    toggleItemEditing,
    handleCancelItemLabelEditing,
    handleSaveItemLabel,
  },
} = useTreeItem2Utils({
  itemId: props.itemId,
  children: props.children,
});

有关自定义此行为的更多详细信息，请参阅编辑—仅使用图标启用编辑。

API

请参阅下面的文档，以获取此处提及的组件的所有可用 props 和类的完整参考。