Descripción general de la directiva de información sobre herramientas Angular

    Las directivas igxTooltip e igxTooltipTarget nos brindan la capacidad de crear una información sobre herramientas totalmente personalizable y adjuntarla a cualquier elemento de nuestra página. Si bien la mayoría de la información sobre herramientas tiene un número limitado de posiciones disponibles, con la directiva igxTooltipTarget podemos especificar cualquier posición que queramos en la página mientras la mantenemos en relación con el objetivo (ancla) y proporcionar otras configuraciones de superposición como estrategias de desplazamiento y animaciones personalizadas.

    Angular Tooltip Example

    Getting Started with Ignite UI for Angular Tooltip

    Para comenzar con la directiva Ignite UI for Angular Tooltip, primero debe instalar Ignite UI for Angular. En una aplicación Angular existente, escriba el siguiente comando:

    ng add igniteui-angular
    

    Para obtener una introducción completa a la Ignite UI for Angular, lea el tema de introducción.

    El siguiente paso es importar IgxTooltipModule en su archivo app.module.ts.

    // app.module.ts
    
    ...
    import { IgxTooltipModule } from 'igniteui-angular';
    // import { IgxTooltipModule } from '@infragistics/igniteui-angular'; for licensed package
    
    @NgModule({
        ...
        imports: [IgxTooltipModule],
    })
    export class AppModule {}
    

    Alternativamente, a partir de 16.0.0, puede importar IgxTooltipDirective como una dependencia independiente o usar el token IGX_TOOLTIP_DIRECTIVES para importar el componente y todos sus componentes y directivas de soporte.

    // home.component.ts
    
    import { IGX_TOOLTIP_DIRECTIVES, IgxAvatarComponent } from 'igniteui-angular';
    // import { IGX_TOOLTIP_DIRECTIVES, IgxAvatarComponent } from '@infragistics/igniteui-angular'; for licensed package
    
    @Component({
        selector: 'app-home',
        template: `
        <igx-avatar class="avatar" #target="tooltipTarget" [igxTooltipTarget]="tooltipRef"
                    src="assets/images/avatar/10.jpg" size="medium" shape="circle">
        </igx-avatar>
    
        <div #tooltipRef="tooltip" igxTooltip>
            Her name is Madelyn James
        </div>
        `,
        styleUrls: ['home.component.scss'],
        standalone: true,
        imports: [IGX_TOOLTIP_DIRECTIVES, IgxAvatarComponent]
        /* or imports: [IgxTooltipDirective, IgxTooltipTargetDirective, IgxAvatarComponent] */
    })
    export class HomeComponent {}
    

    Ahora que ha importado el módulo o las directivas Ignite UI for Angular Tooltip, puede comenzar a usar la directiva igxTooltip.

    Using the Angular Tooltip

    Digamos que queremos crear una información sobre herramientas de texto simple como la de arriba. En nuestro caso, estamos usando nuestro fantástico IgxAvatar como elemento, así que comenzamos importando el IgxAvatarModule primero.

    // app.module.ts
    
    import { IgxTooltipModule, IgxAvatarModule } from 'igniteui-angular';
    // import { IgxTooltipModule, IgxAvatarModule } from '@infragistics/igniteui-angular'; for licensed package
    
    @NgModule({
        ...
        imports: [IgxTooltipModule, IgxAvatarModule],
    })
    export class AppModule {}
    

    Tooltip target

    El avatar será nuestro objetivo y todo lo que tenemos que hacer es configurarle la directiva igxTooltipTarget, que básicamente marca nuestro elemento como uno que tiene información sobre herramientas.

    <!--simpleTooltip.component.html-->
    
    <igx-avatar class="avatar" #target="tooltipTarget" igxTooltipTarget
                src="assets/images/avatar/10.jpg" size="medium" shape="circle">
    </igx-avatar>
    

    Información sobre herramientas

    ¡Ahora creemos el elemento de información sobre herramientas! Como queremos una información sobre herramientas de texto simple, definiremos un elemento div ordinario con texto dentro y estableceremos la directiva igxTooltip en él, que lo marca como información sobre herramientas.

    <!--simpleTooltip.component.html-->
    
    <div #tooltipRef="tooltip" igxTooltip>
        Her name is Madelyn James
    </div>
    

    Attach tooltip to target

    Ahora que tenemos definido nuestro objetivo y la información sobre herramientas, todo lo que nos queda por hacer es asignar la referencia de la información sobre herramientas al selector igxTooltipTarget del objetivo.

    <!--simpleTooltip.component.html-->
    
    <igx-avatar class="avatar" #target="tooltipTarget" [igxTooltipTarget]="tooltipRef"
                src="assets/images/avatar/10.jpg" size="medium" shape="circle">
    </igx-avatar>
    
    <div #tooltipRef="tooltip" igxTooltip>
        Her name is Madelyn James
    </div>
    

    Si todo salió bien, debería ver el ejemplo que se muestra en la sección Demostración de información sobre herramientas.

    Show/Hide delay settings

    ¿Qué pasa si queremos controlar la cantidad de tiempo que debe pasar antes de mostrar y ocultar la información sobre herramientas? Para ello podemos utilizar las propiedades showDelay y hideDelay de la directiva igxTooltipTarget. Ambas propiedades son de tipo número y toman tiempo en milisegundos.

    Note

    El comportamiento de interacción de la interfaz de usuario integrado de IgxTooltipTargetDirective y sus respectivos métodos API funcionan teniendo en cuenta los valores de las propiedades showDelay y hideDelay. Mostrar y ocultar la información sobre herramientas a través de la API de IgxTooltipDirective no tiene en cuenta los valores de las propiedades showDelay y hideDelay. Si fuera necesario, dicha lógica tendría que implementarse manualmente según las especificaciones de la aplicación.

    Rich tooltip

    ¡Personalizar y diseñar el contenido de nuestra información sobre herramientas nunca ha sido tan fácil con la directiva igxTooltip! Dado que la información sobre herramientas en sí es un elemento común en nuestro marcado, básicamente podemos mejorar su contenido agregando cualquier elemento que necesitemos y tenemos la capacidad de diseñarlos en consecuencia.

    ¡Ampliemos el uso de igxTooltip y usémoslo para proporcionar más detalles para una ubicación específica en un mapa! Usaremos un div simple para representar nuestro mapa, IgxAvatar para un logotipo en nuestra información sobre herramientas y IgxIcon para el ícono de ubicación en nuestro mapa. Para ello, obtendremos sus respectivos módulos.

    // app.module.ts
    
    import { IgxTooltipModule, IgxAvatarModule, IgxIconModule } from 'igniteui-angular';
    // import { IgxTooltipModule, IgxAvatarModule, IgxIconModule } from '@infragistics/igniteui-angular'; for licensed package
    
    @NgModule({
        ...
        imports: [IgxTooltipModule, IgxAvatarModule, IgxIconModule],
    })
    export class AppModule {}
    

    También usaremos los siguientes estilos para nuestra aplicación:

    /* richTooltip.component.css */
    
    .location:hover {
        cursor: pointer;
    }
    
    .map {
        overflow: hidden;
        display: flex;
        align-items: center;
        justify-content: center;
        width: 200px;
        height: 252px;
        background-image: url(assets/images/card/media/infragisticsMap.png);
        border: 1px solid #D4D4D4;
    }
    
    .locationTooltip {
        width: 310px;
        background-color: var(--igx-grays-700);
        padding: 3px;
        font-size: 13px;
    }
    
    .locationTooltipContent {
        display: flex;
        justify-content: center;
        align-items: center;
    }
    
    .logo {
        margin-right: 10px;
        min-width: 25px;
        width: 45px;
        height: 45px;
    }
    

    Comencemos creando nuestro mapa. Necesitamos un div simple que tenga como fondo una imagen con un mapa. ¡Además, agregaremos un ícono que nos indicará la posición de nuestra ubicación! Dado que queremos proporcionar más detalles para esta ubicación, nuestro ícono obviamente será el objetivo de la información sobre herramientas.

    <!--richTooltip.component.html-->
    
    <div class="map">
        <igx-icon class="location" [style.color]="'blue'" fontSet="material"
        [igxTooltipTarget]="locationTooltip">location_on</igx-icon>
        ...
    </div>
    

    ¡Ahora la información sobre herramientas! Para su contenido, crearemos un contenedor que se llenará con algunos elementos de información de texto y un avatar. Luego, simplemente adjuntaremos la información sobre herramientas al objetivo e incluiremos un bonito estilo CSS.

    <!--richTooltip.component.html-->
    
    <div class="wrapper">
        <div class="map">
            <igx-icon class="location" [style.color]="'blue'" fontSet="material"
            [igxTooltipTarget]="locationTooltip">location_on</igx-icon>
    
            <div class="locationTooltip" #locationTooltip="tooltip" igxTooltip>
                <div class="locationTooltipContent">
                    <igx-avatar class="logo" src="assets/images/card/avatars/igLogo.png"
                        size="medium" shape="square"></igx-avatar>
                    <div>
                        <div>Infragistics Inc. HQ</div>
                        <div>2 Commerce Dr, Cranbury, NJ 08512, USA</div>
                    </div>
                </div>
            </div>
        </div>
    </div>
    
    

    Si todo ha ido bien, así es como debería verse nuestra ubicación y descripción emergente:

    Overlay configuration

    Tanto la directiva igxTooltip como la igxTooltipTarget utilizan IgxOverlayService para abrir y cerrar el elemento de información sobre herramientas respectivo.

    La directiva igxTooltipTarget expone una propiedad overlaySettings (heredada de igxToggleAction), que se puede usar para personalizar las animaciones de nuestra información sobre herramientas, su posición en la interfaz de usuario y mucho más. Si esta propiedad no está configurada, se utilizará la configuración de superposición predeterminada.

    Note

    Cualquier propiedad que se establezca a través de overlaySettings anulará la misma propiedad de la configuración de superposición predeterminada y tendrá un impacto directo en la información sobre herramientas.

    Estilismo

    Para comenzar a diseñar la información sobre herramientas, necesitamos importar el archivo index, donde se encuentran todas las funciones del tema y los mixins de componentes:

    @use "igniteui-angular/theming" as *;
    
    // IMPORTANT: Prior to Ignite UI for Angular version 13 use:
    // @import '~igniteui-angular/lib/core/styles/themes/index';
    

    Siguiendo el enfoque más simple, creamos un nuevo tema que extiende el tooltip-theme y acepta los parámetros $text-color, $background y $border-radius.

    $dark-tooltip: tooltip-theme(
        $text-color: #ECAA53,
        $background: #011627,
        $border-radius: 6px
    );
    
    Note

    Para aplicar estilo a cualquier componente adicional que se utilice como parte del contenido de la información sobre herramientas (como IgxButton, IgxSwitch, etc.), se debe crear un tema adicional que sea específico para el componente respectivo y colocarse bajo el alcance de la información sobre herramientas únicamente (para que no afecta al resto de la aplicación).

    Dado que la información sobre herramientas utiliza IgxOverlayService, para que nuestro tema personalizado alcance la información sobre herramientas que queremos diseñar, proporcionaremos una salida específica donde se colocará la información sobre herramientas en el DOM cuando esté visible.

    <igx-avatar #target="tooltipTarget" [igxTooltipTarget]="tooltipRef"
                [igxToggleOutlet]="outlet">
    </igx-avatar>
    
    <div #outlet="overlay-outlet" igxOverlayOutlet>
        <div #tooltipRef="tooltip" igxTooltip>
            Her name is Madelyn James
        </div>
    </div>
    
    Note

    Para obtener más información sobre las diversas opciones para proporcionar temas a los elementos que se muestran mediante IgxOverlayService, puede consultar el tema Estilo de superposición.

    Including Themes

    El último paso es incluir el tema del componente en nuestra aplicación.

    Si $legacy-support está configurado en true, incluya el tema del componente así:

     @include tooltip($dark-tooltip);
    
    Note

    Si el componente utiliza una ViewEncapsulation Emulated, es necesario penetrate esta encapsulación usando::ng-deep

    :host {
         ::ng-deep {
            @include tooltip($dark-tooltip);
        }
    }
    

    Si $legacy-support está configurado en false (predeterminado), incluya las variables CSS del componente así:

    @include css-vars($dark-tooltip);
    
    Note

    Si el componente utiliza una ViewEncapsulation Emulated, aún debe usar:host porque necesita un selector global para anular las variables.

    :host {
        @include css-vars($dark-tooltip);
    }
    

    Ahora nuestra información sobre herramientas con estilo debería verse así:

    Demo

    Accessibility

    Los elementos con la directiva igxTooltip tienen una propiedad id generada automáticamente (si no la establece el desarrollador), una role de información sobre herramientas y el atributo aria-hidden que se actualiza automáticamente dependiendo de si la información sobre herramientas es visible o no. Al establecer el atributo aria-describedby del objetivo en su respectivo id de información sobre herramientas, se proporcionará una referencia al elemento de información sobre herramientas. Esto proporciona a los lectores de pantalla la información necesaria para leer el contenido de la información sobre herramientas cuando el usuario final activa la información sobre herramientas.

    Se debe tener especial cuidado en los siguientes escenarios:

    • El contenido de la información sobre herramientas es demasiado complejo para interpretarlo automáticamente.
    • La información sobre herramientas se utiliza con un comportamiento implementado manualmente (por ejemplo, mostrar/ocultar manualmente) en lugar del comportamiento integrado.
    • El elemento objetivo no se puede enfocar.

    API References

    En este artículo, aprendimos cómo crear, configurar y diseñar increíbles información sobre herramientas para los elementos de nuestra página. ¡También utilizamos algunas Ignite UI for Angular como íconos y avatares para mejorar el diseño de nuestra aplicación! Las API respectivas se enumeran a continuación:

    Componentes y/o directivas adicionales que se utilizaron:

    Styles:

    Additional Resources

    Nuestra comunidad es activa y siempre da la bienvenida a nuevas ideas.