I componenti
Tre degli elementi standard riguardano un'osservazione: la scena in cui viene riprodotta, il lettore che la mostra e l'editor che la descrive. L'editor di casi e l'editor di interviste hanno le loro sezioni, nelle pagine che ne parlano.
Web Component standard
Sono cinque Web Component — lo standard del browser stesso per un elemento personalizzato, non un componente del framework di qualcuno. Ciò che ne consegue merita di essere detto, perché è ciò che permette di metterti in mano lo strumento:
- Funzionano in qualsiasi pagina. Un sito statico, WordPress, un'applicazione
React o Vue, un wiki, un file HTML scritto a mano. Sono elementi: una pagina che può
contenere un
<video>può contenere anche questi. - Niente da compilare. Nessun bundler, nessuna fase di compilazione, nessuna configurazione nel tuo progetto. Il modulo registra il suo elemento all'importazione e il browser fa il resto.
- Niente da inseguire. Non c'è una versione di framework a cui adeguarsi, quindi la nuova major release di qualcun altro non può renderli obsoleti.
- Il loro interno è affar loro. Ognuno porta il proprio markup e i propri stili in uno shadow root, quindi il CSS della tua pagina non può romperli e loro non possono rompere la tua pagina.
Si compongono in una riga: sia <rr0-sighting> sia
<rr0-sighting-editor> contengono un <rr0-scene>, e la scena
contiene lo strato di riproduzione — la linea temporale, i controlli, il canvas del puntatore.
Quindi tutto ciò a cui risponde la scena è disponibile in tutti e tre — tramite
.scene e .scene.ufoElement dal più esterno, poiché la composizione
vive in uno shadow root.
A cosa serve ciascuno#
<rr0-scene>— il fenomeno nel mondo che lo circonda. La forma disegnata da un testimone, il suo colore, il suo alone e il suo movimento, collocata nel cielo, nell'orizzonte, nel meteo e nel suolo reali di una data, un'ora e un luogo dichiarati — nascosta da ciò che stava davanti. Utile anche da sola, per un cielo in cui non c'è niente.<rr0-sighting>— il resoconto, da guardare. Una scena più chi testimonia, i metadati dell'osservazione, i suoi crediti e le righe che permettono a un lettore di portarlo altrove. È così che appare un avvistamento pubblicato.<rr0-sighting-editor>— il resoconto, da ricostruire. Tutto quanto sopra più la barra degli strumenti di redazione: descrivere un'osservazione, o correggerne una.<rr0-case-editor>— un caso, da assemblare. Contiene un<rr0-sighting-editor>e gli presenta una registrazione di uncase.jsonalla volta: i resoconti dei testimoni e le letture che se ne fanno. Li aggiunge, li seleziona e li elimina, ed esporta il caso.<rr0-date-input>— una data, con la sua precisione. Un selettore per un istante completo, un testo per meno (EDTF), e il grado di certezza. Gli editor lo usano per l'inizio e la fine di un'osservazione e per la data di un caso; dice ciò che contiene con un eventodatechange.
Come si incastrano#
Non scrivi mai l'annidamento. Ogni elemento costruisce quello sottostante dentro il proprio shadow root, quindi ciò che la tua pagina contiene è un solo tag:
<rr0-sighting> chi testimonia, il pannello dei metadati, le righe di incorporamento
└─ <rr0-scene> il cielo, l'orizzonte, il meteo e lo scenario reali, il fenomeno, la riproduzione
<rr0-sighting-editor> gli otto pannelli di redazione
└─ <rr0-scene> una scena, non un avvistamento: un editor ha la propria barra degli strumenti
Ecco perché un solo tag script si porta dietro quelli sottostanti:
| Caricando questo | si registra |
|---|---|
/lib/rr0-scene.mjs | <rr0-scene> |
/lib/rr0-sighting.mjs | <rr0-sighting>, <rr0-scene> |
/lib/rr0-sighting-editor.mjs | <rr0-sighting-editor>, <rr0-scene> |
Così una pagina che mostra un avvistamento e, più in basso, un cielo tutto suo ha bisogno di un solo script e di due tag — il secondo elemento è già registrato.
Si può entrare in una composizione, una proprietà alla volta:
const sighting = document.querySelector("rr0-sighting")
sighting.scene // il <rr0-scene> che compone
sighting.scene.ufoElement // e lo strato di riproduzione sotto di esso
sighting.scene.ufoElement.play() // quindi la riproduzione è a due proprietà di distanza
<rr0-sighting-editor> tiene per sé la propria composizione: ciò che offre a
una pagina è la registrazione — sightingData — e l'evento che segnala che è
cambiata.
Quale ti serve#
Non sono varianti di un unico bundle: ognuno è autonomo, quindi carica solo quello che ti serve. Tutti e tre includono Three.js e un catalogo stellare, che è il prezzo di un cielo reale.
| Cosa stai facendo | Componente | Modulo | gzip |
|---|---|---|---|
| Mostrare un avvistamento UFO — un fascicolo, un articolo, un rapporto | <rr0-sighting> | /lib/rr0-sighting.mjs | 249 KB |
| Permettere a qualcuno di descriverne o correggerne uno | <rr0-sighting-editor> | /lib/rr0-sighting-editor.mjs | 293 KB |
| Mostrare un cielo senza niente — che aspetto avevano quella notte un alone, una cometa o il passaggio di un satellite | <rr0-scene> | /lib/rr0-scene.mjs | 238 KB |
| Mostrare un avvistamento dentro una scena tua, senza barra degli strumenti sopra | <rr0-scene> | /lib/rr0-scene.mjs | 238 KB |
| Non sei sicuro | <rr0-sighting> | /lib/rr0-sighting.mjs | 249 KB |
Metterne uno in una pagina richiede due righe.
Integrarlo nella tua applicazione#
Dopo npm install @rr0/ufoathome:
import "@rr0/ufoathome/scene" // registra <rr0-scene>
import "@rr0/ufoathome/sighting" // registra <rr0-sighting>
import "@rr0/ufoathome/editor" // registra <rr0-sighting-editor>
Oppure copia il contenuto delle cartelle dist-embed* del pacchetto sul tuo
server e punta lì il <script src>. Ogni modulo fa riferimento alle proprie
risorse — il catalogo stellare, l'audio meteorologico — in modo relativo a se stesso,
quindi continua a funzionare da qualsiasi percorso; basta tenere insieme i file di ogni
bundle. A quel punto nulla dipende più da questo sito.
Lingua#
Ogni etichetta è tradotta per rilevamento, senza selettore: prima la lingua dichiarata dalla
pagina stessa — l'attributo lang più vicino, quindi <html lang="fr">
ottiene etichette in francese — poi le preferenze del browser, poi l'inglese. Una pagina che non
dichiara alcuna lingua segue quindi le preferenze del browser.
<rr0-sighting>#
La vista standard di un avvistamento
La scelta predefinita per un avvistamento reale, con uno o più testimoni. Compone un
<rr0-scene> e aggiunge la barra degli strumenti: chi rende il resoconto, e il pannello i
con i metadati propri dell'osservazione e i suoi crediti, e un pulsante di condivisione: il link che la riproduce, e le sue righe di incorporamento.
<rr0-sighting src="sighting.json"></rr0-sighting>
<rr0-sighting src="case.json"></rr0-sighting> <!-- un caso, e tutti i suoi testimoni -->
| Membro | Tipo | Cosa fa |
|---|---|---|
src | attributo | Una sola registrazione, o un caso i cui eventi sighting ne elencano diverse (l'elemento distingue l'uno dall'altro dalla loro struttura). Un semplice array di registrazioni viene rifiutato: elencale come eventi sighting di un caso |
observerUrls | proprietà | Le registrazioni da mostrare, come semplice array di URL, invece di src. Reimpostarla mantiene il testimone mostrato se la nuova lista lo contiene ancora |
sightingData | proprietà | Una registrazione, impostata direttamente — per una pagina che ne tiene una in memoria invece che a un URL |
scene | proprietà (lettura) | Il <rr0-scene> composto, e attraverso scene.ufoElement i membri di riproduzione |
loadFromSrc(url) | metodo (async) | Ciò che l'attributo innesca |
show-labels | attributo | La striscia di chip che enunciano la registrazione sotto l'immagine, raggruppati (riepilogo, osservazione, posizione, momento, meteo, suono, testimone): la data detta a parole con il suo giorno della settimana, e un chip Descrizioneche mostra le prime parole del resoconto e apre il testo intero, con scorrimento oltre un'altezza massima, al posto dei chip. Disattivata per impostazione predefinita sull'elemento — la pagina del lettore la attiva — e un lettore può aprirla o chiuderla dal pannello i |
show-observer-map / hide-milestones | attributo | Passati attraverso il <rr0-scene> composto fino al lettore che li possiede |
start-time | attributo | Dove si apre la registrazione, come una durata dall'inizio: secondi (125), 1:30, 1m30s o una durata ISO 8601 (PT1M30S). Applicato una volta, alla registrazione che l'elemento carica dopo; un valore oltre la fine apre alla fine |
start-clock | attributo | Dove si apre la registrazione, come un'ora detta durante l'osservazione, nella sua ora locale: 02:33:15, o con il giorno 2026-08-11T02:33:15. L'inizio della registrazione la colloca; prevale su start-time quando può, ed è ignorata per una registrazione che non dice la sua ora |
compare-account | attributo | Parte con il resoconto del testimone mostrato accanto alla lettura scelta, e misurato rispetto ad essa |
Una registrazione che non nomina alcun testimone non ha nessuna riga “resoconto di”, ed è la cosa esatta da dire di un cielo preparato per mostrare un alone.
La registrazione di ogni testimone viene caricata non appena la lista è nota, quindi sceglierne un'altra
è immediato. La lista nomina ciascuno con il suo title, altrimenti con nomi e cognome,
altrimenti con il suo id; uno che non nomina nessuno è numerato secondo il suo posto nella lista.
Il pannello i
si apre come popover, che Esc o un clic all'esterno chiudono (solo un clic
all'esterno, su un browser senza popover). Indica il caso, la data, il luogo, il
resoconto e i tag; data, luogo e tag ne escono finché la striscia show-labels
li indica già. La data è all'ora del testimone stesso (utcOffsetHours, o
un'ora approssimata dalla longitudine), non a quella del lettore. La versione in fondo apre questa
osservazione nell'editor. Anche la descrizione lo lascia finché i chip sono mostrati: è nella loro scatola
Riepilogo
, che si apre con un clic.
Il pulsante Condividi
, tra quelli del lettore, apre un'unica finestra che dà il link o il codice da incorporare
(il codice in un editor che va a capo e si può modificare), per il lettore o per l'editor, con
le opzioni della pagina di condivisione, ciascuna offerta com'è il lettore. Il codice carica l'elemento da dovunque questa copia
sia stata a sua volta caricata, così che uno snippet copiato da una copia locale o di staging rimandi a quella
copia.
Cosa emette
| Evento | Quando | Dove ascoltarlo |
|---|---|---|
observerchange | Quando cambia la registrazione mostrata: caricata, impostata tramite sightingData, o un altro testimone scelto dalla lista. detail.src è il suo indirizzo, vuoto per una registrazione impostata da script | Su questo elemento. Non fa bubbling: ascolta sul <rr0-sighting> stesso, poi rileggi il suo sightingData (la sua descrizione, il suo id) |
recordingissues | Una volta che una registrazione caricata è stata verificata rispetto al formato: detail.issues elenca ciò che non è stato riprodotto come scritto (una chiave che nulla legge, un valore del tipo sbagliato o fuori dalla sua lista, un valore inventato perché il file lo ometteva), ciascuno con il suo kind e il suo path. Vuota quando non c'è nulla da dire. La stessa lista è mostrata sull'immagine dietro un ⚠, e scritta nella console | Ovunque sopra l'elemento: si propaga fuori da tutte le shadow root |
Inserirlo nella tua pagina
<script type="module" src="https://ufoathome.org/lib/rr0-sighting.mjs"></script>
<rr0-sighting src="sighting.json"></rr0-sighting>
sighting.json è un file di avvistamento. Oppure, dopo npm install @rr0/ufoathome: import "@rr0/ufoathome/sighting".
Il bundle pesa 249 KB compresso con gzip e registra il tag da sé — nient'altro da chiamare.
La presentazione sopra dice cos'altro comporta, e
condividere un'osservazione ha l'esempio completo, da provare e da copiare.
<rr0-scene>#
Il fenomeno, il cielo e il suolo
La forma disegnata da un testimone, collocata nel cielo, nell'orizzonte, nel meteo e nel suolo reali della data, dell'ora e del luogo della registrazione, e nascosta da ciò che le stava davanti — con i comandi di riproduzione sotto. È l'elemento su cui si costruiscono gli altri due.
<rr0-scene src="sighting.json"></rr0-scene>
| Membro | Tipo | Cosa fa |
|---|---|---|
src | attributo | URL di una registrazione, caricata alla connessione e a ogni cambiamento |
sightingData | proprietà | La registrazione come oggetto semplice (vedere il formato) — da rileggere dopo la modifica, o da impostare invece di usare src |
loadFromSrc(url) | metodo (async) | Ciò che l'attributo innesca internamente. Attendilo quando la registrazione deve essere GIÀ caricata prima di fare qualsiasi altra cosa |
ufoElement | proprietà (lettura) | Il livello di riproduzione che compone — la cronologia, i comandi, il canvas su cui agisce il puntatore — e, attraverso di esso, tutti i membri di riproduzione qui sotto |
sceneRenderer | proprietà (lettura) | Il motore di rendering 3D, per ciò che nient'altro espone |
show-compass | attributo | Le etichette N/NE/E/… lungo l'orizzonte. Disattivato per impostazione predefinita: utile quando si imposta una direzione, rumore quando si guarda |
star-catalog-src / deep-star-catalog-src | attributo | Da dove caricare il catalogo stellare, quando ne ospiti una tua copia invece di quella accanto al bundle: il livello base (fino alla magnitudine 7,5, caricato da ogni scena) e il livello profondo (da 7,5 a 9, caricato solo da una registrazione il cui strumento va oltre 7,5) |
max-pixel-ratio | attributo | Il massimo di pixel del dispositivo per pixel CSS con cui la scena può disegnare; quello dello schermo stesso, fino a 2, se assente. La scena lo abbassa da sé finché i fotogrammi sono in ritardo |
show-observer-map / hide-milestones | attributo | Passati tali e quali al livello di riproduzione sottostante — scrivili sul tag che la tua pagina contiene davvero |
Al passaggio del puntatore nomina ciò che c'è sotto — una stella con la sua magnitudine e la sua altezza, un pianeta, una cometa, un edificio, un altro testimone — e non dice nulla dove il suolo nasconde ciò che stai indicando.
Il pulsante ©
nel suo angolo elenca i crediti di ciò che mostra — le immagini del
suolo e della mappa, i modelli, le foto del luogo, i suoni. Dentro
<rr0-sighting> il pulsante è nascosto: sono nel suo pannello i
.
La riproduzione, su ufoElement
Tutto ciò che riguarda la riproduzione della registrazione sta una proprietà più in basso, nel livello di riproduzione —
scene.ufoElement.play() — lo stesso livello che gli altri due componenti raggiungono attraverso
la propria scene.
| Membro | Tipo | Cosa fa |
|---|---|---|
src | attributo | URL di una registrazione, caricata alla connessione e a ogni cambiamento |
sightingData | proprietà | La registrazione come oggetto semplice (vedere il formato) — da rileggere dopo la modifica, o da impostare invece di usare src |
sighting | proprietà (lettura) | Il modello vivo: ora e luogo reali più la cronologia della registrazione |
loadFromSrc(url) | metodo (async) | Ciò che l'attributo innesca internamente. Attendilo quando la registrazione deve essere GIÀ caricata prima di fare qualsiasi altra cosa — riprodurre prima che si risolva trova una cronologia di durata zero |
play() / pause() | metodo | Dicono quale stato si vuole, invece di invertire quello attuale |
togglePlayPause() | metodo | Ciò che fanno il pulsante, il clic e la barra spaziatrice |
playbackState | proprietà (lettura) | "stopped", "playing" o "paused" |
currentTime | proprietà | La testina di riproduzione, nelle unità proprie della cronologia — non in millisecondi reali, vedere positionLabel |
seekableDuration | proprietà (lettura) | L'intervallo che currentTime può assumere |
autoReplayEnabled | proprietà | La ripetizione in loop, disattivata per impostazione predefinita: una riproduzione va una volta, poi emette ended. Attivala per un loop |
positionLabel / durationLabel | proprietà (lettura) | La posizione e la durata già formattate dall'elemento: l'ora dell'orologio quando l'osservazione indica una data e la sua durata è nota, il tempo trascorso altrimenti. Un clic su uno dei due contatori sotto la barra (o Invio su di esso) passa dall'uno all'altro, ed emette timedisplaychange |
refresh() | metodo | Rilegge la durata e ridisegna — chiamalo dopo aver modificato sighting.timeline dall'esterno |
canvasElement / renderer | proprietà (lettura) | Il <canvas>, e il renderer che ci dipinge sopra |
enableClickToPlay | proprietà | Se un clic avvia o ferma la riproduzione e un doppio clic attiva o disattiva lo schermo intero (entrambe le cose, o nessuna). Il doppio clic riporta anche la riproduzione allo stato in cui era prima del suo primo clic. Impostala a false dove il canvas ti serve per altro |
fullscreenTarget | proprietà | Quale elemento viene ingrandito dal pulsante schermo intero. <rr0-scene> la imposta sul proprio palco, così che sia il cielo ad andare a schermo intero e non solo il livello sovrapposto. Dove il browser non offre lo schermo intero (un iPhone, un iframe senza allow="fullscreen"), l'elemento riempie invece la finestra, ed Esc ne esce allo stesso modo |
show-observer-map | attributo | Se la mappa del punto in cui si trovava il testimone parte aperta: presente la apre, "false" la tiene chiusa. Assente, decide la registrazione: il suo observerMap se lo indica, altrimenti aperta quando il testimone si è spostato (una camminata in un campo, un tragitto in auto, un volo), chiusa quando è rimasto dov'era. Decide lo stato iniziale della mappa, non se esista: il pulsante c'è per ogni registrazione che indica un luogo |
toggleObserverMap() | metodo | Ciò che fa quel pulsante. Sulla mappa stessa la rotella ingrandisce attorno al puntatore, un trascinamento sposta il terreno, e i suoi pulsanti ingrandiscono e tornano al percorso intero. Ingrandita, si ricentra sul testimone ogni volta che questi ne raggiunge il bordo, perché non ne esca mai |
observerPlacing | proprietà | Se un clic sul suolo libero della mappa emette observerplace con { lat, lng } — disattivata per impostazione predefinita, perché dire dove si trovava il testimone spetta alla registrazione. L'editor la attiva e scrive la posizione alla testina di riproduzione |
hide-milestones | attributo | Toglie i momenti nominati del resoconto — le tacche lungo la barra, la didascalia che nomina quello in riproduzione e i punti con lettera sulla mappa. Compaiono ovunque una registrazione ne nomini qualcuno, quindi questo è l'unico modo di dire il contrario |
toggleMilestones() | metodo | Ciò che fa quel pulsante |
I momenti nominati e la mappa sono le sole due cose che questo elemento mostra o nasconde per impostazione predefinita (i momenti visibili, la mappa nascosta), e la differenza è voluta. I momenti nominati di una registrazione sono le sue stesse parole su di sé, quindi si mostrano ovunque esistano; la mappa costa richieste di tile a una terza parte la prima volta che si apre, e non spetta a una pagina spenderle per conto di un lettore senza dirlo. In entrambi i casi il lettore conserva i due pulsanti, accanto a quello dello schermo intero — una pagina che imposta un valore predefinito non è una pagina che vieta il contrario.
La barra degli strumenti e i pulsanti dell'angolo compaiono solo mentre il puntatore è sopra l'immagine, in riproduzione o in pausa, o quando la tastiera vi porta il focus. Uno schermo tattile, che non ha un puntatore con cui passarci sopra, li tiene visibili.
Con la barra del tempo attiva, i tasti funzionano come su un sito di video: ← torna indietro di 5 s, → va avanti di 5 s e Spazio avvia o mette in pausa. Avviare o mettere in pausa, con un tasto, con il pulsante o con un clic sull'immagine, ne mostra il simbolo per un istante al centro dell'immagine.
Cosa emette
| Evento | Quando | Dove ascoltarlo |
|---|---|---|
ended | Una volta, quando la riproduzione arriva alla fine senza ripartire in loop. Non a una pausa, né trascinando fino alla fine | Ovunque: è bubbling e composed, quindi esce da <rr0-scene> e da <rr0-sighting> e raggiunge l'elemento che hai messo nella pagina. È così che si riproducono più registrazioni una dopo l'altra |
timedisplaychange | Quando i contatori passano dall'ora dell'orologio al tempo trascorso, o viceversa | Ovunque, come sopra |
timeupdate | A ogni passo della riproduzione e a ogni salto, con detail.time | Solo su questo elemento. Non è né bubbling né composed, quindi una pagina che contiene un <rr0-scene> deve passare dal suo ufoElement — è pensato per gli elementi che lo contengono |
Inserirlo nella tua pagina
<script type="module" src="https://ufoathome.org/lib/rr0-scene.mjs"></script>
<rr0-scene src="sighting.json"></rr0-scene>
sighting.json è un file di avvistamento. Oppure, dopo npm install @rr0/ufoathome: import "@rr0/ufoathome/scene".
Il bundle pesa 238 KB compresso con gzip e registra il tag da sé — nient'altro da chiamare.
La presentazione sopra dice cos'altro comporta, e
condividere un'osservazione ha l'esempio completo, da provare e da copiare.
<rr0-sighting-editor>#
L'editor
Una scena (<rr0-scene>) più la barra degli strumenti di creazione. Mettilo in una pagina dove le persone devono poter
descrivere o correggere un'osservazione da sé.
<rr0-sighting-editor></rr0-sighting-editor>
<rr0-sighting-editor src="sighting.json"></rr0-sighting-editor>
Il suo canvas è una superficie di modifica, quindi enableClickToPlay lì è disattivato: un clic
seleziona e trascina una forma invece di avviare o fermare la riproduzione. Cosa fanno gli otto gruppi della sua barra degli strumenti
è spiegato nella pagina dell'editor.
| Membro | Tipo | Cosa fa |
|---|---|---|
ufoElement | proprietà (lettura) | Dà accesso al canvas, alla cronologia e al lavoro sull'aspetto |
appearance | proprietà | L'aspetto che avrà la prossima forma disegnata: { presetId, color, transparency, haloScale, blur, brightness }, dove presetId vale "oval" o "polygon" e gli altri sono i campi di forma con lo stesso nome. Impostarla prende solo i campi che fornisci |
sightingchange | evento | Emesso dopo ogni modifica — l'unico segnale che la registrazione è cambiata |
Cosa emette
| Evento | Quando | Dove ascoltarlo |
|---|---|---|
sightingchange | Dopo una modifica: un campo scritto, uno strumento scelto, un fuso orario dedotto, una forma spostata lungo la cronologia | Su questo elemento. Non fa bubbling, quindi ascolta sul <rr0-sighting-editor> stesso — poi rileggi il suo sightingData |
Inserirlo nella tua pagina
<script type="module" src="https://ufoathome.org/lib/rr0-sighting-editor.mjs"></script>
<rr0-sighting-editor></rr0-sighting-editor>
Oppure, dopo npm install @rr0/ufoathome: import "@rr0/ufoathome/editor".
Il bundle pesa 293 KB compresso con gzip e registra il tag da sé — nient'altro da chiamare.
La presentazione sopra dice cos'altro comporta, e
condividere un'osservazione ha l'esempio completo, da provare e da copiare.