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;
}

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()`	`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()`	`Promise<void>`	Aloittaa toiston tai jatkaa pysäytettyä toistoa. `Promise` valmistuu, kun toisto on alkanut.
`playPause()`	`Promise<void>`	Vaihtaa toiston tilaa pysäytyksen ja toiston välillä. `Promise` valmistuu, kun toisto on alkanut.
`previous()`	`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.

Eventin nimi	Data	Kuvaus
`'AimReader.duration'`	`{ totalDuration: number, durationRemaining: number }`	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 }`	Lukijassa tapahtui jokin virhe. Mahdolliset `error`-arvot: - `'server-error'` - Palvelin ei vastaa normaalisti. - `'no-text-content-found'` - Ei löytynyt tekstiä `.aim-readable`-elementeistä. - `false` - Edellinen virhetilanne on selvitetty.
`'AimReader.loading'`	`{ loading: boolean }`	Lukija alkaa lataamaan tai lopettaa lataamisen.
`'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 reader is ready.
             */
            function onReaderReady() {
                // 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) {
                onReaderReady();
            } else {
                window.addEventListener(
                    'AimReader.ready',
                    onReaderReady,
                    { 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>

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search