ListView

ListView es un componente para renderizar un conjunto de elementos apilados verticalmente. Estos elementos pueden recibir foco, seleccionarse, tener una acción principal y una o más acciones secundarias, y admitir navegación por teclado y características de accesibilidad.

Uso

<script>
	import { ListView, ListViewItem } from 'fluentui-svelte';
	let list = ['A', 'B', 'C'];
	let selected = ['A'];
</script>

<ListView selectedItems={selected}>
	{#each list as item (item)}
		<ListViewItem value={item}>{item}</ListViewItem>
	{/each}
</ListView>

Navigation Mode

Usa items para mantener cada elemento en el orden de tabulación. Usa composite para que la lista tenga una sola parada y accede a los controles secundarios con Derecha. La selección usa roles listbox y option en modo items, o grid, row y gridcell en modo composite. Para una navegación seleccionable con sublistas, establece role="list" en cada ListView y usa aria-current en los enlaces: cada lista gestiona sus propios selectedItems, sin seleccionar elementos de otros niveles.

Mejores prácticas

• Mantén las listas que solo muestran texto fuera de la secuencia de Tab. Configura navigationMode en el ListView exterior: usa items para navegar con enlaces nativos y composite para tarjetas seleccionables con controles secundarios. Deja que el componente gestione el tabindex de los elementos y sus controles, salvo que desactives esa gestión con disableTabspot.
• Con los roles de grid predeterminados en listas compuestas seleccionables, el componente coloca el contenido de cada fila en un único gridcell y gestiona la navegación hacia sus controles. No necesitas añadir contenedores gridcell manualmente.
• Usa onAction para la acción principal del elemento y botones o enlaces nativos con onclick para acciones secundarias. Enter y Espacio activan los elementos interactivos no nativos; los enlaces conservan su comportamiento de teclado nativo. En filas compuestas seleccionables, la casilla cambia la selección de forma independiente y los botones y enlaces secundarios no ejecutan la acción ni seleccionan la fila.
• Conserva los roles predeterminados para listas planas con selección; dependen de selectionMode y navigationMode. Usa etiquetas HTML compatibles: ul/ol con elementos li, o as="div" tanto en la lista de tarjetas como en sus elementos.
• Usa ListViewItemBranch para sublistas expandibles. Las ramas nunca son seleccionables y gestionan sus atributos de expansión y el foco. Cada lista anidada controla su propia selección. Establece role="list" en cada lista seleccionable que contenga ramas para conservar la semántica nativa de listas.
• Asigna un nombre accesible al ListView seleccionable con aria-label o aria-labelledby. Asigna un nombre al nav y marca el enlace actual con aria-current="page". Usa texto visible significativo o aria-label en los controles, un label descriptivo para cada rama y valores value estables al usar selección.

Navegación por teclado

Arriba y Abajo recorren los elementos del mismo nivel; Inicio y Fin llevan a sus extremos. Derecha abre una rama cerrada; en una rama abierta, entra en su sublista. Izquierda cierra una rama abierta; desde una rama cerrada o un hijo, vuelve a su padre. Escape cierra la rama más cercana y devuelve el foco a su botón. Derecha también entra en los controles de un elemento compuesto: Izquierda y Derecha los recorren, e Izquierda desde el primer control vuelve a la fila. Enter activa los enlaces; Enter y Espacio activan los botones y los elementos seleccionables. En modo items, Tab recorre los elementos y sus controles; en modo composite, toda la lista tiene una sola parada de tabulación. disableTabspot desactiva la gestión del foco con las flechas.

Navegación simple

Envuelve la lista en una región nav con nombre y usa as="a" con href para los enlaces de navegación. ListView envuelve los enlaces en elementos de lista nativos cuando la lista es ul u ol. Usa aria-current="page" en el enlace actual; la navegación conserva la semántica nativa de listas y enlaces.

<nav aria-label="Main navigation">
  <ListView>
    <ListViewItem as="a" href="/">Home</ListViewItem>
    <ListViewItem as="a" href="/docs">Documentation</ListViewItem>
    <ListViewItem as="a" href="/docs/components/list-view" aria-current="page">ListView</ListViewItem>
  </ListView>
</nav>

Navegación con sublistas

Anida un ListView dentro de ListViewItemBranch. Las ramas son botones de expansión que reciben foco y nunca son seleccionables. El estado de expansión, aria-expanded, aria-controls, el contenido oculto y la restauración del foco se gestionan automáticamente. Cada lista anidada conserva su selección al cerrarse. Usa semántica nativa de listas; establece role="list" al habilitar la selección en una lista que contiene ramas.

<script lang="ts">
  import { ListView, ListViewItem, ListViewItemBranch } from 'fluentui-svelte';
</script>

<nav aria-label="Component navigation">
  <ListView>
    <ListViewItem as="a" href="/">Home</ListViewItem>
    <ListViewItemBranch label="Components" expanded>
      <ListView>
        <ListViewItem as="a" href="/docs/components/button">Button</ListViewItem>
        <ListViewItemBranch label="Inputs" expanded>
          <ListView>
            <ListViewItem as="a" href="/docs/components/checkbox">Checkbox</ListViewItem>
            <ListViewItem as="a" href="/docs/components/radio-button">RadioButton</ListViewItem>
          </ListView>
        </ListViewItemBranch>
      </ListView>
    </ListViewItemBranch>
    <ListViewItem as="a" href="/docs">Documentation</ListViewItem>
  </ListView>
</nav>

Selection Mode

Use selectionMode (single, multiselect, or extended) to control how items are selected.

<ListView aria-label="Fruits" selectionMode="multiselect" selectedItems={['Apple']}>
  {#each ['Apple', 'Banana', 'Cherry'] as item (item)}
    <ListViewItem value={item}>{item}</ListViewItem>
  {/each}
</ListView>

Alternar al hacer clic

En una lista multiselect, un clic normal selecciona solo ese elemento y Ctrl/Cmd + clic lo alterna. Activa toggleOnClick para que un clic normal alterne el elemento directamente.

<ListView aria-label="Fruits" selectionMode="multiselect" toggleOnClick>
  {#each ['Apple', 'Banana', 'Cherry'] as item (item)}
    <ListViewItem value={item}>{item}</ListViewItem>
  {/each}
</ListView>

Checkmark

Agrega y configura una casilla de verificación para el elemento. Puedes usar las mismas propiedades para el componente Checkbox .

La casilla alterna la selección de su elemento sin disparar onAction. Enlaza selectedItems para leer o controlar la selección.

<script lang="ts">
  let selected = $state<string[]>(['Apple']);
</script>

<ListView aria-label="Fruits" selectionMode="multiselect" bind:selectedItems={selected}>
  {#each ['Apple', 'Banana', 'Cherry'] as item (item)}
    <ListViewItem value={item} checkmark={{}}>{item}</ListViewItem>
  {/each}
</ListView>

<p>Selected: {selected.join(', ')}</p>

Tarjetas con una acción principal

Con navigationMode en composite y un selectionMode, cada elemento es una fila. Establece as="div" en la lista y en sus tarjetas para mantener una estructura HTML válida. Al hacer clic en una fila se ejecuta su acción principal (onAction), la casilla alterna su selección y cualquier botón interno es una acción secundaria. Usa checkmark.wrapperAttributes.style para ubicar la casilla donde la necesites, como la esquina superior derecha de la tarjeta.

<script lang="ts">
  const cards = [
    { name: 'Fluent', description: 'Design system' },
    { name: 'Svelte', description: 'UI framework' },
    { name: 'Vite', description: 'Build tool' }
  ];

  let selected = $state<string[]>([]);
  let lastAction = $state('');
</script>

<ListView as="div" navigationMode="composite" selectionMode="multiselect" bind:selectedItems={selected}>
  {#each cards as card (card.name)}
    {#snippet install()}
      <Button
        onclick={() => {
          lastAction = 'Installed ' + card.name;
        }}>Install</Button
      >
    {/snippet}
    <ListViewItem
      as="div"
      value={card.name}
      checkmark={{ wrapperAttributes: { style: 'position: absolute; top: 0.5rem; right: 0.5rem; z-index: 2;' } }}
      style="padding: 0"
      onAction={() => (lastAction = 'Opened ' + card.name)}
    >
      <Card orientation="vertical" style="width: 100%;">
        <CardHeader title={card.name} description={card.description} />
        <CardFooter action={install} />
      </Card>
    </ListViewItem>
  {/each}
</ListView>

<p>Selected: {selected.join(', ')}</p>
<p>Last action: {lastAction}</p>

Los controles secundarios ejecutan sus propias acciones sin seleccionar el elemento ni disparar su acción principal. La casilla solo alterna la selección.

Propiedades de ListView

Propiedades de ListViewItem

Propiedades de ListViewItemBranch