TreeSelect | Tuff Docs

Usage

Basic

Loading demo...

Permission Orchestration

TxTreeSelect picks the owner team and forms an authorization flow with TxTransfer and TxTimeline.

Loading demo...

Best Practices

Use TxTreeSelect for compact owner, namespace, category, and org-unit picks; use TxTree when users need persistent context, bulk operations, or custom row controls.
Give nodes stable key and label fields instead of a legacy value field, with keys independent of localized text.
Match the value's shape to multiple before render; switching at runtime doesn't convert between a scalar and an array.
Keep default expansion shallow, such as root departments or product areas.
Use the node slot only for badges or subtitles, never for click targets that compete with row selection.

API Reference

Props

Prop	Type	Default	Description
`modelValue`	`string \| number \| Array<string \| number> \| undefined`	-	Selected key in single mode; an array of keys with `multiple`.
`nodes`	`TreeSelectNode[]`	`[]`	Tree nodes for the dropdown, also used to resolve the trigger text.
`multiple`	`boolean`	`false`	Checkbox multi-select, shown as tags in the trigger.
`disabled`	`boolean`	`false`	Disables the trigger, dropdown interaction, keyboard toggling, and clearing.
`placeholder`	`string`	`'请选择'`	Placeholder when no selected key resolves to a label.
`searchable`	`boolean`	`true`	Shows a search field whose text goes to the inner `TxTree` as `filterText`.
`clearable`	`boolean`	`true`	Shows a clear button when something is selected and the component is enabled.
`placement`	`PopoverPlacement`	`'bottom-start'`	Placement of the dropdown.
`dropdownOffset`	`number`	`6`	Distance between the dropdown and the trigger.
`dropdownWidth`	`number`	`0`	Dropdown width; `0` leaves it to `TxPopover`.
`dropdownMaxWidth`	`number`	`480`	Maximum dropdown width.
`dropdownMaxHeight`	`number`	`320`	Maximum tree height; taller content scrolls.
`defaultExpandedKeys`	`Array<string \| number>`	`[]`	Keys the inner `TxTree` starts expanded.

Events

Event	Params	Description
`update:modelValue`	`value: TreeSelectValue`	Fires after a selection, a clear, or `setValue()`.
`change`	`value: TreeSelectValue`	Fires right after `update:modelValue` with the same value.
`open`	-	Fires when the dropdown opens.
`close`	-	Fires when the dropdown closes.

Slots

Slot	Props	Description
`node`	`{ node, level, expanded, selected }`	Replaces the node label area of a row; caret, checkbox, indent, and click handling stay with the component.

Exposed Methods

Name	Type	Description
`open()`	`() => void`	Opens the dropdown.
`close()`	`() => void`	Closes the dropdown.
`toggle()`	`() => void`	Toggles the dropdown.
`focus()`	`() => void`	Focuses the combobox trigger.
`blur()`	`() => void`	Blurs the combobox trigger.
`clear()`	`() => void`	Unless disabled, emits `undefined` in single mode or `[]` in multiple mode.
`setValue(value)`	`(value: TreeSelectValue) => void`	Emits the given value through `update:modelValue` and `change`, without checking it against `nodes`.
`getValue()`	`() => TreeSelectValue`	Returns the current `modelValue`.
`getCheckedKeys()`	`() => Array<string \| number>`	Returns the selected keys as an array, in single mode too.

Types

type TreeSelectValue = string | number | Array<string | number> | undefined

interface TreeSelectNode {
  key: string | number // stable and unique; the selected value
  label: string // node text, default search target, and trigger text
  disabled?: boolean // blocks selecting this node
  children?: TreeSelectNode[]
}

Overview

The trigger is a focusable role="combobox" (aria-haspopup="tree", aria-controls pointing at the popup) whose popup holds a role="tree" TxTree; Enter and Space toggle the dropdown, Escape closes it.
Single selection closes the dropdown and clears to undefined; multiple selection stays open and clears to [].
Disabled nodes can't be selected but still expand when they have children.
Search uses TxTree's default label filter, with no custom filterMethod or controlled expandedKeys; for domain search, compose an external search or use TxTree directly.
Trigger text is resolved from the current nodes; unknown selected keys stay selected but show no text.
setValue() only emits; the parent still owns modelValue through v-model, which ordinary code should prefer.

Technologies

The dropdown is a TxPopover that receives the placement and width props; the tree reuses TxTree, passing only defaultExpandedKeys, filterText, and multiple.
Source: packages/tuffex/packages/components/src/tree-select/.

查看源码

packages/tuffex/packages/components/src/tree-select/index.ts