Resumen
Los primitivos son los controles fundamentales de Twenty UI. Incluyen entradas, elementos de visualización, navegación y controles compuestos como Select, Popover y AlertDialog. Cada primitivo recibe datos y funciones de devolución de llamada de tu aplicación. Importa primitivos desde un punto de entrada de familia, comotwenty-ui/primitives/input. La entrada agregada twenty-ui/primitives también exporta todas las familias de primitivas. Consulta Primeros pasos para obtener información sobre la instalación y la configuración del tema.
Los componentes combinan estas primitivas en preajustes de diseño compartidos y bloques de creación de aplicaciones reutilizables.
Propiedad del estado
Usa el estado no controlado cuando un componente pueda gestionar sus propias interacciones. Una prop predeterminada proporciona el estado inicial. Usa el estado controlado cuando la aplicación necesite coordinar ese estado con otros controles, la navegación o los datos de la aplicación.
En el modo controlado, pasa el estado actual y actualízalo en el callback de cambio. En el modo no controlado, aún puedes escuchar los cambios sin asumir la propiedad del estado. Agregar solo un callback no hace que un componente sea controlado.
Elige un modo para cada estado y mantenlo durante toda la vida útil del componente. Las props predeterminadas inicializan el estado; cambiarlas más adelante no reemplaza el estado actual. Evita pasar tanto la prop predeterminada como la controlada para el mismo estado.
Algunos componentes tienen más de un estado independiente. Por ejemplo, Select puede tener un valor controlado y una visibilidad de ventana emergente no controlada.
El estado pertenece a la parte que gestiona la interacción. Configura la selección de botones de opción en RadioGroup, no en cada Radio. Los componentes de visualización, como Text, no tienen un modo controlado ni no controlado. Toast delega su visibilidad y eliminación a la aplicación.
Composición
Los componentes primitivos compuestos exponen partes comoSelect.Root, Select.Trigger y Select.Popup. Mantenga las partes relacionadas bajo la misma raíz en el árbol de componentes para que compartan el estado y las relaciones de accesibilidad. La sección de anatomía de cada componente identifica las partes obligatorias y el contenido opcional.
Los slots como InputGroup.startElement y ListItem.actions aceptan nodos de React como props. Añaden contenido dentro del diseño de un componente. Las partes y los slots son API diferentes; use los nombres indicados en la guía del componente.
Composición de ventanas emergentes
Select, Popover y Autocomplete exponen partes independientes dePortal, Positioner y Popup:
Anida Popup dentro de Positioner y Positioner dentro de Portal. Coloca el contenido dentro de Popup y añade Arrow explícitamente cuando sea necesario. El portal puede mover el DOM renderizado a otro contenedor mientras conserva la jerarquía y el contexto de los componentes. Consulte la tematización para los contenedores de portal con ámbito.
Cada parte renderizada conserva sus propios atributos nativos, destino de ref y composición de renderizado. Autocomplete también conserva las partes de colección, agrupación, cuadrícula, filtrado y estado ascendentes instaladas.
Dialog y AlertDialog exponen partes independientes de
Portal, Backdrop, Viewport y Popup. Configure el montaje y el destino en Portal, la apariencia de la superposición en Backdrop y Viewport, y el tamaño y el foco del contenido en Popup. Cada parte conserva sus propios atributos nativos, destino de ref y composición de renderizado. Estas API de diálogo son para la interfaz de usuario independiente y el host de Twenty. Los componentes Front usan la API de diálogo del host de SDK.
Componentes personalizados
Para las partes que admitenrender, pase un elemento o componente compatible para reemplazar el elemento predeterminado. Por ejemplo, Popover.Trigger puede usar un Button de Twenty UI y conservar su comportamiento de activador.
Un contenedor personalizado debe pasar los props y la ref proporcionados al elemento interactivo. Esto conserva los controladores de eventos, los atributos de accesibilidad, el posicionamiento y la restauración del foco. Este ejemplo los reenvía mediante Button, que los adjunta a su botón nativo.
render y mantenga cada acción como un único control interactivo. Conserve los controladores y la ref proporcionados a su contenedor al añadir su propio comportamiento. La ref debe llegar al elemento que recibe el foco.
Use un botón nativo para las partes similares a botones. En las partes que exponen nativeButton, establezca nativeButton={false} solo cuando el elemento renderizado no sea un botón nativo. Un componente personalizado que finalmente renderiza un botón, como HelpButton, conserva el comportamiento predeterminado del botón.