Oma toteutus lukijalle

Edistyneiden käyttäjien on mahdollista tehdä oma toteutus verkkosivulukijalle. Tällöin voit itse luoda koko soittimen ulkoasun ja piilottaa oletuksena näkyvän soittimen. Soittimen toimintoja ohjataan JavaScriptillä lukijan tarjoaman API:n kautta.

Valmistelu

Ota lukija käyttöön normaalisti edellisen sivun ohjeen mukaan.

Kun verkkosivulukija on otettu käyttöön, se luo automaattisesti namespacen window.AimReader, jonka kautta lukijaa voi ohjata.

Lukijan saatavuus

Lukijan namespace on saatavilla vasta sen jälkeen, kun lukijan skripti on ladattu. Voit tarkastaa saatavuuden suoraan namespacen kautta tai kuuntelemalla eventiä 'AimReader.ready'.

if (window.AimReader?.ready) {
    // Lukija on käytettävissä
} else {
    window.addEventListener('AimReader.ready', () => {
        // Lukija on käytettävissä
    }, { once: true });
}

Oletussoittimen piilotus

Kun luot itse soittimen ulkoasun, kannattaa oletussoitin piilottaa kokonaan näkyvistä. Voit piilottaa soittimen käyttämällä seuraavaa CSS-koodia.

.aim-player-host {
    display: none !important;
}

Monta soitinta

Jos olet Portalin asetuksissa ottanut usean soittimen näyttämisen käyttöön, voit tunnistaa soittimet antamalla niille uniikin ID-arvon. ID-arvo määritetään data-aim-player-id-attribuutin avulla.

<article class="aim-readable" data-aim-player-id="my-article-1">
    ...
</article>

<article class="aim-readable" data-aim-player-id="my-article-2">
    ...
</article>

Voit tämän jälkeen käyttää ID-arvoa API:n metodeissa, jotka tukevat sitä. Voit esimerkiksi aloittaa toistamaan jälkimmäistä artikkelia kutsumalla window.AimReader.play('my-article-2').

API

Kun AimReader namespace on saatavilla, seuraavat ominaisuudet ja funktiot ovat käytettävissä namespacen kautta, esimerkiksi window.AimReader.play().

Ominaisuudet

Ominaisuus	Tyyppi	Kuvaus
active	boolean, readonly	Onko lukija aktiivinen, eli voiko sillä toistaa audiota. Oletuksena true, jos et erikseen deaktivoi lukijaa.
ready	true, readonly	Onko AimReader namespace valmis käyttöön.
speed	number	Lukijan toistonopeus välillä 0.5 - 4.0. Oletuksena 1.0, jos et ole määrittänyt oletusnopeutta Portalissa. Voit vaihtaa nopeutta asettamalla tähän uuden arvon.
volume	number	Lukijan äänenvoimakkuus välillä 0.0 - 1.0. Oletuksena 1.0, jos et ole määrittänyt oletusäänenvoimakkuutta Portalissa. Voit vaihtaa äänenvoimakkuutta asettamalla tähän uuden arvon.

Metodit

Metodi	Paluuarvo	Kuvaus
activate()	void	Aktivoi lukijan, jos se on deaktivoituna. Lukija aktivoidaan automaattisesti, kun skripti ladataan.
deactivate()	void	Deaktivoi lukijan. Tätä voit käyttää, jos haluat väliaikaisesti ottaa lukijan kokonaan pois käytöstä nykyisellä sivulla.
next(playerId?: string)	Promise<void>	Siirtyy toistamaan seuraavaa lausetta. Promise valmistuu, kun seuraavan lauseen toisto on alkanut.
pause()	void	Pysäyttää toiston. Toistoa voi jatkaa kutsumalla play() tai playPause().
play(playerId?: string)	Promise<void>	Aloittaa toiston tai jatkaa pysäytettyä toistoa. Promise valmistuu, kun toisto on alkanut.
playPause(playerId?: string)	Promise<void>	Vaihtaa toiston tilaa pysäytyksen ja toiston välillä. Promise valmistuu, kun toisto on alkanut.
previous(playerId?: string)	Promise<void>	Siirtyy toistamaan edellistä lausetta. Promise valmistuu, kun edellisen lauseen toisto on alkanut.
stop()	void	Pysäyttää toiston kokonaan ja poistaa lauseiden korostuksen näkyvistä. Toistoa ei voi enää jatkaa samasta kohtaa, vaan ainoastaan aloittaa alusta.

Eventit

Lukija lähettää joitain eventejä, joita voit kuunnella window.addEventListener-funktion avulla. Eventin nimi on muotoa 'AimReader.<event>', esimerkiksi 'AimReader.loading'. Jos eventin mukana on dataa, löytyy se detail-avaimen alta. Datan mukana lähetetään myös playerId, jolla voit tunnistaa mihin soittimeen event liittyy.

Eventin nimi	Data	Kuvaus
'AimReader.duration'	{ durationRemaining: number, totalDuration: number, playerId: string }	Audion arvioitu kokonaiskesto ja jäljellä oleva kesto sekunteina. Tämä event lähetetään sekunnin välein tai aina, kun jokin kesto muuttuu. Käytetty toistonopeus vaikuttaa audion kestoon.
'AimReader.error'	{ error: string | false, playerId: string }	Lukijassa tapahtui jokin virhe. Mahdolliset error-arvot: - 'server-error' - Palvelin ei vastaa normaalisti. - 'no-text-content-found' - Ei löytynyt tekstiä .aim-readable-elementeistä. - 'unknown-error' - Tuntematon virhe. - false - Edellinen virhetilanne on selvitetty.
'AimReader.loading'	{ loading: boolean, playerId: string }	Lukija alkaa lataamaan tai lopettaa lataamisen.
'AimReader.playback'	{ action: 'play' | 'pause' | 'stop', playerId: string }	Toiston tila muuttui. action kertoo mitä tapahtui.
'AimReader.ready'	void	Lukijan tarjoama namespace window.AimReader on valmis käyttöön.

Esimerkki

<html>
    <head>
        <!-- Load the reader script -->
        <script src="https://portal.aimater.com/static/reader/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.js"></script>

        <script>
            /**
             * Enable the custom reader when the `AimReader` namespace is ready.
             */
            function onAimReaderReady() {
                // Make your custom reader visible.
                const myCustomReader = document.getElementById('my-custom-reader');
                myCustomReader?.removeAttribute('hidden');

                // Show a loading icon when the reader is loading.
                const loadingIcon = document.getElementById('loading-icon');
                window.addEventListener(
                    'AimReader.loading',
                    (event) => {
                        if (event.detail.loading) {
                            loadingIcon?.removeAttribute('hidden');
                        } else {
                            loadingIcon?.setAttribute('hidden', '');
                        }
                    },
                );

                // Show an error message if the reader encounters an error.
                const errorMessage = document.getElementById('error-message');
                window.addEventListener(
                    'AimReader.error',
                    (event) => {
                        if (event.detail.error) {
                            errorMessage?.removeAttribute('hidden');
                        } else {
                            errorMessage?.setAttribute('hidden', '');
                        }
                    },
                );

                // Show the remaining duration of the audio.
                const durationElement = document.getElementById('duration');
                window.addEventListener(
                    'AimReader.duration',
                    (event) => {
                        durationElement.innerHTML = `Kesto: ${event.detail.durationRemaining} s`;
                    },
                );

                // Set initial values for volume and speed inputs
                const volumeInput = document.getElementById('volume-input');
                const speedInput = document.getElementById('speed-input');
                if (volumeInput) {
                    volumeInput.value = window.AimReader.volume;
                }
                if (speedInput) {
                    speedInput.value = window.AimReader.speed;
                }
            }

            // Wait for the reader to be ready.
            if (window.AimReader?.ready) {
                onAimReaderReady();
            } else {
                window.addEventListener(
                    'AimReader.ready',
                    onAimReaderReady,
                    { once: true },
                );
            }
        </script>

        <style>
            /* Hide the default player. */
            .aim-player-host {
                display: none !important;
            }
        </style>
    </head>

    <body>
        <aside id="my-custom-reader" hidden>
            <div id="loading-icon" hidden></div>

            <div id="error-message" hidden>Tapahtui odottamaton virhe.</div>

            <button type="button" onclick="window.AimReader.play()">Toista</button>
            <button type="button" onclick="window.AimReader.pause()">Tauko</button>
            <button type="button" onclick="window.AimReader.stop()">Lopeta</button>
            <button type="button" onclick="window.AimReader.previous()">Edellinen</button>
            <button type="button" onclick="window.AimReader.next()">Seuraava</button>

            <label for="volume-input">Äänenvoimakkuus</label>
            <input
                id="volume-input" type="range"
                min="0" max="1" step="0.1"
                oninput="window.AimReader.volume = this.value"
            />
            <label for="speed-input">Puhenopeus</label>
            <input
                id="speed-input" type="range"
                min="0.5" max="4" step="0.1"
                oninput="window.AimReader.speed = this.value"
            />

            <div id="duration">Kesto: 0 s</div>
        </aside>

        <article class="aim-readable">
            ...
        </article>
    </body>
</html>