Įrankių antraščių pridėjimas "WordPress" be įskiepių

Terminas tooltip neturi vienintelio vertimo į lietuvių kalbą, jis gali būti apibūdinamas kaip "įrankio užuomina", "pagalbos balionas", "iššokantis aprašas" ar net "pagalbos tekstas", priklausomai nuo konteksto, kuriame jis vartojamas.

Įrankių užuomina - tai iššokantis pranešimas, kuris rodomas sąveikaujant su elementu, spustelėjus ant jo arba užvedus pelę. Šios įrankių užuominos naudojamos papildomai informacijai pateikti, neužimant nuolatinės vietos. Idealiai tinka piktogramoms, techniniams terminams ar veiksmams sąsajose paaiškinti.

Ar įrankių užrašai kenkia, ar padeda SEO?

Na, kaip ir beveik į viską, atsakymas visada priklauso nuo situacijos. Nors SEO puristai įspėja, kad "Google" nemėgsta "paslėpto" arba užmaskuoto turinio ir griežtai baudžia už jo naudojimą, tai būtų kraštutinumas piktnaudžiavimo atvejais , kurie gali "kanibalizuoti" jūsų turinį. Tačiau įrankių užrašai, naudojami laikantis tam tikros pusiausvyros ir minimalios logikos, gali būti naudingi.

Priemonių žymų naudojimo privalumai

Apskritai, jei šie pranešimai yra draugiški ir neįkyrūs, jie gali padėti pagerinti įvairius naudotojo patirties aspektus. Be kita ko, jie sumažina atmetimo rodiklius ir pagerina prieinamumą. Taip pat gali suteikti galimybių naudoti papildomus raktinius žodžius, kurie natūraliai netelpa į pagrindinį turinį, o tai padeda semantiniam SEO.

Be to, jie gali pagerinti paspaudimų skaičių. Siūlydami įrankių užrašus navigacijoje arba raginimo imtis veiksmų mygtukus, jie gali veiksmingiau nukreipti naudotojus ir taip padidinti paspaudimų skaičių. Tačiau kad visa tai būtų įmanoma, reikia laikytis kelių būtiniausių gairių.

Rekomendacijos dėl išvaizdos, turinio ir veikimo

HTML elementų ir ARIA atributų naudojimas siekiant užtikrinti, kad ekrano skaitytuvai ir paieškos sistemos galėtų pasiekti juose esančią informaciją.
Įrankių užuomina turi būti trumpa. Akivaizdu, kad iššokančiame lange niekas nesiruošia skaityti didžiulio kiekio informacijos, o jūs aprėpsite didžiąją dalį turinio. Jame turėtų būti pateikta minimali, tiksli ir būtina informacija, kuri neturėtų būti kritinė naudotojui atliekant ar užbaigiant kokį nors veiksmą.
Turinys neturėtų būti perteklinis ar pasikartojantis, įsitikinkite, kad pateikiate papildomos naudingos ir reikalingos informacijos ir kad ji nesikartoja jūsų turinyje, kad išvengtumėte "turinio dubliavimo".
Stenkitės kuo labiau vengti įrankių užrašų, kurie išnyksta, kai pastumiate žymeklį, arba naudokite juos tik pranešimuose, kuriuose nėra daug informacijos ir (arba) turinio. Geriausia, kad jos būtų rodomos po vieno paspaudimo ir užsidarytų, kai dar kartą paspaudžiate bet kurioje ekrano vietoje.
Įsitikinkite, kad jie yra įskaitomi ir tinkamo dydžio.
Nepridėkite dvidešimties skirtingo dizaino įrankių užuominų piktogramų ar nuorodų, nes tai tik sukelia painiavą. Pastovus ir nuoseklus dizainas padės lankytojams jas atpažinti iš pirmo žvilgsnio.
Nepersistenkite, gerai suplanuokite savo strategiją, kad juos pridėtumėte tik ten, kur, jūsų manymu, jie palengvina prieigą prie svarbios ir (arba) būtinos papildomos informacijos.

Kodo savybės ir funkcijos

Šiuo atveju naudojamas šis .png vaizdas su skaidriu fonu.

Čia galite išbandyti galutinį rezultatą [tooltip text="Pavyzdys tooltip naudojamas jrmora.com" position="auto"].

Šioje eilutėje tarp kabučių įrašomas paveikslėlio URL adresas:

$default_image = 'URL-de-tu-imagen';

Jei nuspręsite pakeisti kodą, kad būtų naudojama SVG HTML piktograma, kaip ši, galėsite lengviau keisti spalvą, foną, storį ir t. t.

Išmanusis automatinis padėties reguliavimas, kad būtų išvengta ekrano kraštų. T. y. kai artėjama prie viršutinio krašto, įrankių užrašas rodomas apačioje, ir vivecersa.

Į įrankių užuominą galima įtraukti visiškai veikiančias nuorodas su pritaikomais stiliais. Nors nuorodų pridėti nerekomenduojama, gali būti, kad kartais to prireiks. Jei įrankių užuominoje yra nuoroda, automatinis paslėpimas atidedamas 200 ms, kad ją būtų lengviau spustelėti.

Saugus HTML palaikymas. Palaiko:

<strong>, <em>, <a>, <br>, <span>

Pozicija, fiksuoti ir pritaikomi atributai.

Atributos de posición disponibles:  position="auto" (default), top, bottom, left, right

ARIA atributai (aria-expanded, role="tooltip").

Atnaujinti. Į paveikslėlį pridėta aria-hidden="true" ir role="presentation", o dekoratyvinė piktograma paslėpta ekrano skaitytuvams.

Pertekliaus išvengiama naudojant aria-ženklą, kuri leidžia pritaikyti tekstą, pasiekiamą iš trumpojo kodo.

[tooltip text="Contenido" aria_label="Ver detalles sobre este elemento"]

Šis sprendimas atitinka WCAG 2.1 AA ir pašalina "PageSpeed Insights" įspėjimą, kad mygtukas neturi prieinamo pavadinimo.

Prisitaikantis dizainas.

Pritaikoma mobiliesiems įrenginiams (paspaudžiamas perjungiklis).

Iš naujo nustatymas keičiant dydį, pasukant ar perkeliant

Pagrindinės CSS klasės:

.tooltip-container /* Contenedor principal */
.tooltip-trigger  /* Botón/icono que activa el tooltip */
.tooltip          /* Caja del mensaje emergente */
.tooltip-arrow    /* Flecha indicadora */

Pagrindinės JS funkcijos:

calculateBestPosition() // Determina si colocar el tooltip arriba, abajo, etc.
showTooltip()          // Muestra el tooltip
hideTooltip()          // Oculta el tooltip con retraso

Trumpųjų kodų pavyzdžiai:

[tooltip text="Texto a mostrar"] 

[tooltip text="Texto a mostrar <strong>en negrita</strong> donde sea" position="auto"] 

[tooltip text="Texto <strong>importante</strong> y <em>énfasis</em>"]

[tooltip text="<a href='https://ejemplo.com' target='_blank'>Visite nuestro sitio</a>"]

Kalbant apie našumą:

Išankstinis turto įkėlimas: iš anksto įkelti vaizdai ir CSS.
Lėtas krovimas: atributai Loading="lazy" ir decoding="async" paveikslėliui.
Sąlyginis įkėlimas: JS įkeliamas tik tada, kai naudojamas trumpasis kodas.
Debounce: dydžio keitimo ir slinkties įvykių optimizavimas.
Optimizuotas CSS: naudojamas "will-change" ir šiuolaikiniai vienetai (min()).
Spartinančiosios versijos: Naudokite filemtime(), kad išvengtumėte pasenusios spartinančiosios talpyklos.

Šį kodą naudojau savo konkretiems poreikiams tenkinti. Supraskite jį kaip pradinį tašką. Jį galima patobulinti. Galite netgi apsvarstyti jį nenaudodami "Javascript" ir pritaikyti taip, kad jį būtų galima taikyti ir turinio žodžiams nerodant piktogramos.

Norėdami jį naudoti, kaip visada, tiesiog pridėkite jį į functions.php ir savo šablono arba savo antrinės temos aplanką assets/css/ ir asstes/js/, jei norite, kad pakeitimai būtų išsaugoti atnaujinant šabloną.

Kodas

Tokia yra failų struktūra:

jūsų šablonas/
├── functions.php (pabaigoje pridėkite PHP kodą)
├── assets/
│ ├───── css/
│ │ │ └└──── tooltip.css (CSS stiliai)
│ └└└└── js/
│ └└─── tooltip.js (JavaScript)

Kodas, kurį reikia pridėti prie šablono functions.php

/**
 * Shortcode para tooltip accesible y optimizado
 * Uso: [tooltip text="Texto" position="auto" color="#6a0000" aria_label="Descripción"]
 */
function accessible_tooltip_shortcode($atts) {
    $default_image = 'https://jrmora.com/wp-content/uploads/2025/07/tooltip-negro.png';
    
    $atts = shortcode_atts(
        array(
            'text' => __('Información adicional', 'text-domain'),
            'position' => 'auto',
            'color' => '#6a0000',
            'shadow' => '#9c9c9c',
            'width' => '18px',
            'id' => 'tooltip-' . uniqid(),
            'aria_label' => __('Mostrar información adicional', 'text-domain')
        ),
        $atts,
        'tooltip'
    );

    // HTML permitido (seguro)
    $allowed_html = array(
        'strong' => array(),
        'b' => array(),
        'em' => array(),
        'i' => array(),
        'br' => array(),
        'span' => array(
            'style' => array(),
            'class' => array()
        ),
        'a' => array(
            'href' => array(),
            'title' => array(),
            'target' => array(),
            'style' => array(),
            'rel' => array()
        )
    );
    
    $text = wp_kses($atts['text'], $allowed_html);
    $position = in_array($atts['position'], ['top', 'bottom', 'left', 'right', 'auto']) ? $atts['position'] : 'auto';
    $color = sanitize_hex_color($atts['color']);
    $shadow = sanitize_hex_color($atts['shadow']);
    $width = esc_attr($atts['width']);
    $id = sanitize_html_class($atts['id']);
    $aria_label = esc_attr($atts['aria_label']);

    // Preload para la imagen (mejora rendimiento)
    add_action('wp_head', function() use ($default_image) {
        echo '<link rel="preload" href="' . esc_url($default_image) . '" as="image">';
    });

    return '
    <span class="tooltip-container" data-position="' . esc_attr($position) . '">
        <button class="tooltip-trigger" 
                aria-describedby="' . $id . '" 
                aria-expanded="false"
                aria-label="' . $aria_label . '">
            <img src="' . esc_url($default_image) . '" 
                 width="' . $width . '" 
                 alt=""
                 aria-hidden="true"
                 loading="lazy"
                 decoding="async"
                 role="presentation"/>
        </button>
        <span id="' . $id . '" role="tooltip" class="tooltip" style="background-color: ' . $color . '; box-shadow: 0 5px 10px ' . $shadow . ';">
            ' . $text . '
            <span class="tooltip-arrow"></span>
        </span>
    </span>';
}
add_shortcode('tooltip', 'accessible_tooltip_shortcode');

/**
 * Carga optimizada de assets
 */
function load_tooltip_assets() {
    global $post;
    
    // CSS externo
    wp_enqueue_style(
        'tooltip-css',
        get_theme_file_uri('/assets/css/tooltip.css'),
        array(),
        filemtime(get_theme_file_path('/assets/css/tooltip.css'))
    );
    
    // JS solo si se usa el shortcode
    if (is_a($post, 'WP_Post') && has_shortcode($post->post_content, 'tooltip')) {
        wp_enqueue_script(
            'tooltip-js',
            get_theme_file_uri('/assets/js/tooltip.js'),
            array(),
            filemtime(get_theme_file_path('/assets/js/tooltip.js')),
            true
        );
    }
}
add_action('wp_enqueue_scripts', 'load_tooltip_assets');

CSS / tooltip.css (turi būti išsaugotas šiame kelyje /assets/css/tooltip.css)

/* Contenedor principal */
.tooltip-container {
    display: inline-block;
    position: relative;
    vertical-align: middle;
}

/* Botón activador */
.tooltip-trigger {
    background: none;
    border: none;
    padding: 0;
    margin: 0 2px;
    cursor: pointer;
    line-height: 1;
}

/* Caja del tooltip */
.tooltip {
    position: absolute;
    color: #fff;
    padding: 10px 12px;
    border-radius: 4px;
    font-size: 14px;
    line-height: 1.5;
    width: 220px;
    max-width: min(90vw, 220px);
    text-align: left;
    visibility: hidden;
    opacity: 0;
    transition: opacity 0.25s ease;
    z-index: 100000;
    pointer-events: none;
    will-change: transform, opacity;
}

/* Flecha indicadora */
.tooltip-arrow {
    position: absolute;
    width: 0;
    height: 0;
    border: 7px solid transparent;
}

/* Posiciones */
.tooltip[data-position="top"] {
    bottom: 100%;
    left: 50%;
    transform: translateX(-50%);
    margin-bottom: 10px;
}
.tooltip[data-position="top"] .tooltip-arrow {
    top: 100%;
    left: 50%;
    transform: translateX(-50%);
    border-top-color: inherit;
}

.tooltip[data-position="bottom"] {
    top: 100%;
    left: 50%;
    transform: translateX(-50%);
    margin-top: 10px;
}
.tooltip[data-position="bottom"] .tooltip-arrow {
    bottom: 100%;
    left: 50%;
    transform: translateX(-50%);
    border-bottom-color: inherit;
}

/* Interacción */
.tooltip-trigger:hover + .tooltip,
.tooltip-trigger:focus + .tooltip,
.tooltip-trigger[aria-expanded="true"] + .tooltip {
    visibility: visible;
    opacity: 1;
}

/* Enlaces dentro del tooltip */
.tooltip a {
    color: #fff !important;
    text-decoration: underline;
    pointer-events: auto !important;
}

/* Focus para accesibilidad */
.tooltip-trigger:focus {
    outline: 2px solid #005fcc;
    outline-offset: 2px;
}

Javascript / Tooltip.js (turi būti išsaugotas kelyje /assets/js/tooltip.js)

document.addEventListener("DOMContentLoaded", () => {
    const tooltips = document.querySelectorAll('.tooltip-container[data-position="auto"]');
    if (!tooltips.length) return;

    // Debounce para optimización
    const debounce = (func, wait = 50) => {
        let timeout;
        return (...args) => {
            clearTimeout(timeout);
            timeout = setTimeout(() => func.apply(this, args), wait);
        };
    };

    // Configurar cada tooltip
    tooltips.forEach(container => {
        const tooltip = container.querySelector('.tooltip');
        const trigger = container.querySelector('.tooltip-trigger');
        let hoverTimeout;
        let isMouseIn = false;

        // Calcular mejor posición
        const calculatePosition = () => {
            const rect = trigger.getBoundingClientRect();
            const viewportHeight = window.innerHeight;
            return (rect.top < viewportHeight / 2) ? 'bottom' : 'top';
        };

        // Actualizar posición (optimizado)
        const updatePosition = debounce(() => {
            tooltip.dataset.position = calculatePosition();
        });

        // Mostrar tooltip
        const showTooltip = () => {
            clearTimeout(hoverTimeout);
            tooltip.style.visibility = 'visible';
            tooltip.style.opacity = '1';
            trigger.setAttribute('aria-expanded', 'true');
        };

        // Ocultar con retraso (para enlaces)
        const hideTooltip = () => {
            if (!isMouseIn) {
                hoverTimeout = setTimeout(() => {
                    tooltip.style.visibility = 'hidden';
                    tooltip.style.opacity = '0';
                    trigger.setAttribute('aria-expanded', 'false');
                }, 200);
            }
        };

        // Eventos
        trigger.addEventListener('mouseenter', showTooltip);
        trigger.addEventListener('mouseleave', hideTooltip);
        trigger.addEventListener('focus', showTooltip);
        trigger.addEventListener('blur', hideTooltip);

        tooltip.addEventListener('mouseenter', () => {
            isMouseIn = true;
            clearTimeout(hoverTimeout);
        });

        tooltip.addEventListener('mouseleave', () => {
            isMouseIn = false;
            hideTooltip();
        });

        // Inicialización
        updatePosition();
        window.addEventListener('resize', updatePosition);
        window.addEventListener('scroll', updatePosition, { passive: true });
    });

    // Cerrar al hacer clic fuera
    document.addEventListener('click', (e) => {
        if (!e.target.closest('.tooltip-container') && !e.target.closest('.tooltip a')) {
            document.querySelectorAll('.tooltip').forEach(t => {
                t.style.visibility = 'hidden';
                t.style.opacity = '0';
            });
        }
    });
});