Skip to Content
文档

TreeView

用于以可扩展树状结构显示分层数据结构。

SourceStorybookRecipeArk

Tree

panda.config.ts
package.json
renovate.json
README.md

用法

¥Usage

import { TreeView } from "@chakra-ui/react"
<TreeView.Root>
  <TreeView.Label />
  <TreeView.Tree>
    <TreeView.Branch>
      <TreeView.BranchControl>
        <TreeView.BranchIndicator />
        <TreeView.BranchText />
      </TreeView.BranchControl>
      <TreeView.BranchContent>
        <TreeView.BranchIndentGuide />
        <TreeView.Item />
      </TreeView.BranchContent>
    </TreeView.Branch>
    <TreeView.Item />
  </TreeView.Tree>
</TreeView.Root>

快捷键

¥Shortcuts

TreeView.Node

此组件用于管理分支和叶节点的递归渲染。

¥This component is a helper to manage the recursive rendering of the branch and leaf nodes.

<TreeView.Node
  showIndentGuide
  render={({ node, nodeState }) =>
    nodeState.isBranch ? (
      <TreeView.BranchControl>
        <TreeView.BranchText>{node.name}</TreeView.BranchText>
      </TreeView.BranchControl>
    ) : (
      <TreeView.Item>
        <TreeView.ItemText>{node.name}</TreeView.ItemText>
      </TreeView.Item>
    )
  }
/>

等同于:

¥is equivalent to:

const TreeNode = (props: TreeView.NodeProviderProps<Node>) => {
  const { node, indexPath } = props
  return (
    <TreeView.NodeProvider key={node.id} node={node} indexPath={indexPath}>
      {node.children ? (
        <TreeView.Branch>
          <TreeView.BranchControl>
            <TreeView.BranchText>{node.name}</TreeView.BranchText>
          </TreeView.BranchControl>
          <TreeView.BranchContent>
            <TreeView.BranchIndentGuide />
            {node.children.map((child, index) => (
              <TreeNode
                key={child.id}
                node={child}
                indexPath={[...indexPath, index]}
              />
            ))}
          </TreeView.BranchContent>
        </TreeView.Branch>
      ) : (
        <TreeView.Item>
          <TreeView.ItemText>{node.name}</TreeView.ItemText>
        </TreeView.Item>
      )}
    </TreeView.NodeProvider>
  )
}

示例

¥Examples

尺寸

¥Sizes

使用 size 属性更改树形视图的大小。

¥Use the size prop to change the size of the tree view.

Tree (size=xs)

panda.config.ts
package.json
renovate.json
README.md

Tree (size=sm)

panda.config.ts
package.json
renovate.json
README.md

Tree (size=md)

panda.config.ts
package.json
renovate.json
README.md

变量

¥Variants

使用 variant 属性更改树形视图的变体。

¥Use the variant prop to change the variant of the tree view.

Tree (variant=subtle)

panda.config.ts
package.json
renovate.json
README.md

Tree (variant=solid)

panda.config.ts
package.json
renovate.json
README.md

颜色

¥Colors

使用 colorPalette 属性更改树形视图的调色板。

¥Use the colorPalette prop to change the color palette of the tree view.

Tree (colorPalette=gray)

panda.config.ts
package.json
renovate.json
README.md

Tree (colorPalette=red)

panda.config.ts
package.json
renovate.json
README.md

Tree (colorPalette=green)

panda.config.ts
package.json
renovate.json
README.md

Tree (colorPalette=blue)

panda.config.ts
package.json
renovate.json
README.md

Tree (colorPalette=teal)

panda.config.ts
package.json
renovate.json
README.md

Tree (colorPalette=pink)

panda.config.ts
package.json
renovate.json
README.md

Tree (colorPalette=purple)

panda.config.ts
package.json
renovate.json
README.md

Tree (colorPalette=cyan)

panda.config.ts
package.json
renovate.json
README.md

Tree (colorPalette=orange)

panda.config.ts
package.json
renovate.json
README.md

Tree (colorPalette=yellow)

panda.config.ts
package.json
renovate.json
README.md

已禁用节点

¥Disabled Node

disabled 属性添加到节点的属性将禁用该节点并阻止交互。

¥Adding the disabled prop to a node's property will disable the node and prevent interaction.

Tree

panda.config.ts
package.json
renovate.json
README.md

受控扩展

¥Controlled Expansion

使用 expandedValueonExpandedChange 属性以编程方式控制节点扩展行为。

¥Use the expandedValue and onExpandedChange props to programmatically control node expansion behavior.

Tree

node_modules
zag-js
panda
panda.config.ts
package.json
renovate.json
README.md

显式展开

¥Explicit Expand

渲染 TreeView.BranchTrigger 以手动控制节点扩展行为。

¥Render the TreeView.BranchTrigger to manually control node expansion behavior.

你可能需要在 TreeView.BranchControl 上设置 role="none" 以避免出现可访问性问题。

Tree

panda.config.ts
package.json
renovate.json
README.md

展开图标

¥Expand Icon

使用 nodeState.expanded 属性在分支展开或折叠时切换渲染图标。

¥Use the nodeState.expanded prop to swap the rendered icon on the branch when it's expanded or collapsed.

Tree

panda.config.ts
package.json
renovate.json
README.md

移除缩进

¥Remove Indentation

将 CSS 变量 --tree-indentation 设置为 0px,以移除树形视图的缩进。

¥Set the css variable --tree-indentation to 0px to remove the indentation of the tree view.

Tree

panda.config.ts
package.json
renovate.json
README.md

异步加载

¥Async Loading

延迟加载是一项功能,允许树视图按需(或异步)加载节点的子节点。这有助于缩短初始加载时间并减少内存使用。

¥Lazy loading is a feature that allows the tree view to load children of a node on demand (or async). This helps to improve the initial load time and memory usage.

要使用此功能,你需要提供以下内容:

¥To use this, you need to provide the following:

  • loadChildren — 用于加载节点子节点的函数。

  • onLoadChildrenComplete — 节点子节点加载完成后调用的回调函数。用于更新树形集合。

  • childrenCount — 表示分支节点子节点数量的数字。

Tree

panda.config.ts
package.json
renovate.json
README.md

过滤

¥Filtering

当你拥有一棵大型树并且想要过滤节点以仅显示与搜索查询匹配的节点时,过滤功能非常有用。

¥Filtering is useful when you have a large tree and you want to filter the nodes to only show the ones that match the search query.

以下是组合 TreeCollectionuseFilter 钩子中的 filter 方法来过滤节点的示例。

¥Here's an example that composes the filter method from the TreeCollection and useFilter hook to filter the nodes.

Tree

panda.config.ts
package.json
renovate.json
README.md

折叠动画

¥Collapse Animation

使用 animateContent 属性可对树形视图内容的展开/折叠状态进行动画处理。

¥Use the animateContent prop to animate the tree view content expand/collapse state.

Tree

panda.config.ts
package.json
renovate.json
README.md

展开/折叠全部

¥Expand/Collapse All

提供用于一次性展开或折叠所有节点的控件。

¥Provide controls to expand or collapse all nodes at once.

Tree

panda.config.ts
package.json
renovate.json
README.md

商店

¥Store

使用 useTreeView 钩子创建树形视图存储并将其传递给 TreeView.RootProvider 组件。这允许你以编程方式最大程度地控制树形视图。

¥Use the useTreeView hook to create the tree view store and pass it to the TreeView.RootProvider component. This allows you to have maximum control over the tree view programmatically.

Tree

[]
panda.config.ts
package.json
renovate.json
README.md

链接

¥Links

利用 TreeView.Item 组件上的 asChild 属性,将树状项渲染为链接。

¥Render the tree items as links by leveraging the asChild prop on the TreeView.Item component.

多选

¥Multi Select

selectionMode="multiple" 属性添加到 TreeView.Root 组件以启用多选功能。

¥Add the selectionMode="multiple" prop to the TreeView.Root component to enable multi-select functionality.

info

此模式需要按下修饰键才能选择多个项目。

¥This mode requires a modifier key to be pressed to select multiple items.

  • 在 macOS 上按住 Ctrl 并点击项目。

  • 单击某个项目,然后按住 Shift 并单击另一个项目。

Tree

panda.config.ts
package.json
renovate.json
README.md

复选框树

¥Checkbox Tree

为树节点添加复选框以实现选择功能。

¥Add checkboxes to tree nodes for selection functionality.

Tree

panda.config.ts
package.json
renovate.json
README.md

突变

¥Mutation

以下示例展示了如何在树视图中设计添加/删除节点。

¥Here's an example of how to design add/remove nodes in the tree view.

Tree

panda.config.ts
package.json
renovate.json
README.md

自定义图标

¥Custom Icon

以下是如何根据树形视图的数据为其渲染自定义图标的示例。

¥Here's an example of how to render a custom icon for the tree view based on its data.

Tree

Footer

属性

¥Props

根元素

¥Root

PropDefaultType
collection *
TreeCollection<T>

The collection of tree nodes

expandOnClick true
boolean

Whether clicking on a branch should open it or not

lazyMount false
boolean

Whether to enable lazy mounting

selectionMode '\'single\''
'multiple' | 'single'

Whether the tree supports multiple selection - "single": only one node can be selected - "multiple": multiple nodes can be selected

typeahead true
boolean

Whether the tree supports typeahead search

unmountOnExit false
boolean

Whether to unmount on exit.

colorPalette 'gray'
'gray' | 'red' | 'orange' | 'yellow' | 'green' | 'teal' | 'blue' | 'cyan' | 'purple' | 'pink'

The color palette of the component

size 'md'
'md' | 'sm' | 'xs'

The size of the component

variant 'subtle'
'subtle' | 'solid'

The variant of the component

as
React.ElementType

The underlying element to render.

asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
unstyled
boolean

Whether to remove the component's style.

checkedValue
string[]

The controlled checked node value

defaultCheckedValue
string[]

The initial checked node value when rendered. Use when you don't need to control the checked node value.

defaultExpandedValue
string[]

The initial expanded node ids when rendered. Use when you don't need to control the expanded node value.

defaultFocusedValue
string

The initial focused node value when rendered. Use when you don't need to control the focused node value.

defaultSelectedValue
string[]

The initial selected node value when rendered. Use when you don't need to control the selected node value.

expandedValue
string[]

The controlled expanded node ids

focusedValue
string

The value of the focused node

ids
Partial<{ root: string; tree: string; label: string; node: (value: string) => string }>

The ids of the tree elements. Useful for composition.

loadChildren
(details: LoadChildrenDetails<T>) => Promise<T[]>

Function to load children for a node asynchronously. When provided, branches will wait for this promise to resolve before expanding.

onCheckedChange
(details: CheckedChangeDetails) => void

Called when the checked value changes

onExpandedChange
(details: ExpandedChangeDetails<T>) => void

Called when the tree is opened or closed

onFocusChange
(details: FocusChangeDetails<T>) => void

Called when the focused node changes

onLoadChildrenComplete
(details: LoadChildrenCompleteDetails<T>) => void

Called when a node finishes loading children

onLoadChildrenError
(details: LoadChildrenErrorDetails<T>) => void

Called when loading children fails for one or more nodes

onSelectionChange
(details: SelectionChangeDetails<T>) => void

Called when the selection changes

selectedValue
string[]

The controlled selected node value

animateContent
'true' | 'false'

The animateContent of the component

节点

¥Node

PropDefaultType
render *
(props

indentGuide
React.ReactElement

renderBranch
(props

branchProps
TreeViewBranchProps

branchContentProps
TreeViewBranchContentProps

as
React.ElementType

The underlying element to render.

asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.

Previous

选择

Next

操作栏