樹狀目錄項目自訂

了解如何自訂樹狀目錄項目元件。

結構

每個樹狀目錄項目元件都由一系列可組合的插槽組成。將滑鼠懸停在下方示範中的插槽上，即可查看每個插槽。

內容

使用 content 插槽自訂樹狀目錄項目的內容，或將其替換為自訂元件。

插槽 props

`slotProps` prop 可讓您將 props 傳遞至 content 元件。下方的示範展示如何將 `sx` handler 傳遞至樹狀目錄項目的 content

資料網格
日期和時間選擇器
圖表
樹狀檢視

<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 開始編輯

核取方塊

當樹狀檢視啟用 `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 /> 元件都相容。如果您使用的是自訂樹狀目錄項目元件，並且想要覆寫 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` 實驗性功能。在下一個主要版本的樹狀檢視元件中，它將成為預設行為。

資料網格
日期和時間選擇器
圖表
樹狀檢視

<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 相容。如果您使用的是自訂樹狀目錄項目元件，並且想要覆寫 padding，則將以下 padding 套用至您的 content 元素

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

Hook

useTreeItem2

`useTreeItem2` Hook 可讓您管理和自訂個別的樹狀目錄項目。您可以使用它來取得所有插槽所需的屬性、任何給定項目的狀態，或存取樹狀檢視的互動式 API。

插槽屬性

`useTreeItem2` Hook 透過提供解析器來取得每個插槽的適當 props，讓您能夠精細地控制項目的版面配置。這使得為您的樹狀目錄項目建構完全自訂的版面配置成為可能。

下方的示範展示如何取得每個插槽所需的 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` 物件，其中包含樹狀目錄項目每個可能狀態的布林值。

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

您可以使用這些狀態將自訂樣式套用至項目，或有條件地呈現子元件。

資料網格
日期和時間選擇器
圖表
樹狀檢視

圖例

已聚焦

已選取

可展開

已展開

已停用

可編輯

編輯中

<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` 物件提供許多方法以程式設計方式與樹狀檢視互動。您可以使用 `useTreeItem2` Hook 從樹狀目錄項目內存取 `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** 區段，以深入了解樹狀檢視上可用的 public API 方法。

`useTreeItem2Utils`

`useTreeItem2Utils` Hook 提供一組互動方法，用於為樹狀檢視實作自訂行為。它也會傳回項目的狀態。

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

若要覆寫樹狀目錄項目的預設互動，請在事件處理常式中將 `event.defaultMuiPrevented` 設定為 `true`，然後實作您自己的行為。

選取

您可以在樹狀檢視中透過點擊其 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 開始編輯

核取方塊選取

預設情況下，如果項目已停用，或如果樹狀檢視上的 `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 的更多詳細資訊。

展開

預設情況下，當使用者點擊樹狀目錄項目的內容時，它會展開。您可以使用 `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 和類別的完整參考。