Utente:Codicorumus/$.fn.fittingColor

Lo script $.fn.fittingColor.js implementa un plugin jQuery che permette di verificare la leggibilità del testo di un elemento HTML e di modificarne il colore sostituendolo con uno ottimizzato in accordo allo sfondo. Il cambiamento di colore è realizzato modificando o impostando la proprietà CSS color.

Aggiunge agli oggetti jQuery la funzione fittingColor.

La funzione richiede un parametro obbligatorio, che indica il metodo invocato. Alcuni metodi prevedono un secondo parametro opzionale, che ne regola il funzionamento.

• $( ... ).fittingColor( metodo );
• $( ... ).fittingColor( metodo, opzioni );

Il parametro metodo è una stringa indicante il nome del metodo invocato; mentre il parametro opzioni è un oggetto costituito dalla lista delle opzioni con i rispettivi valori, in pratica i parametri del metodo.

Adopera il modulo jquery.colorUtil per le conversioni tra RGB, HSL e stili CSS.

Lo standard di default per la valutazione della leggibilità del testo è quello raccomandato dal W3C e può essere personalizzato modificando i livelli di soglia per le differenze di colore e luminosità tra testo e sfondo.

Non sono supportate le trasparenze né gli sfondi contenenti immagini. In genere, in questi casi si otterranno valori inadeguati, in quanto vengono considerati i valori di background-color e color, indipendentemente dalla presenza di immagini o trasparenze.

Esempi

set

$( '#content' ).css( 'background', '#333' );
$( '.firstHeading, .mw-headline, a' ).fittingColor( 'set', { mode:'b|w' } );

Nei siti basati su Mediawiki, la prima riga mette uno sfondo grigio scuro alla pagina, rendendo il testo nero poco leggibile. La seconda riga, restituisce visibilità al titolo della pagina, ai titoli di sezione e ai link presenti nella pagina, selezionando per essi il colore bianco.

$( ... ).fittingColor( 'set', { level:0.3 } );

Modifica il colore degli elementi della selezione jQuery che risultano poco leggibili, secondo una soglia di differenza testo/sfondo, indicata dall'opzione level, leggermente inferiore a quella standard, quindi in un numero minore di casi. Non essendo indicata una modalità, viene usata quella di default smooth.

fitting

$( ... ).fittingColor( 'fitting' );

Restituisce un colore adatto allo sfondo del primo elemento della selezione jQuery, nella forma di una stringa 'rgb(R,G,B)'.

oneIsBadNow

$( ... ).fittingColor( 'oneIsBadNow' );

Restituisce true se almeno uno degli elementi della selezione jQuery ha una combinazione di testo e sfondo poco leggibile.

Metodi di fittingColor

Nella prima riga, il nome del metodo.

Nella seconda riga, le sue caratteristiche. Le lettere che precedono la lineetta hanno il seguente significato:

• e  —  metodo che considera solo il primo elemento dell'oggetto jQuery;
• o  —  metodo che accetta opzioni;
• u  —  metodo che restituisce undefined quando non riesce a determinare il valore richiesto;
• c  —  metodo che restituisce l'oggetto jQuery e permette la concatenazione di istruzioni.

Nelle lista puntata, le opzioni supportate dal metodo. Una ulteriore lista puntata indica i valori possibili per l'opzione.

fitting

e o u  —  Restituisce un colore di testo adatto allo sfondo dell'elemento.

• mode  —  default = 'smooth'  —  Una stringa indicante una delle modalità supportate per la costruzione di un colore di testo adatto allo sfondo:

  • 'smooth'  —  Viene restituito un colore costruito a partire dalla rappresentazione HSL del colore di sfondo. H (tinta) e S (saturazione) vengono mantenuti inalterati, mentre L (luminosità) subisce una mezza pseudo-rotazione (p.e.: 0,1⇒0,6  —  0,55⇒0,05). Per la precisione, la rotazione non avviene esattamente sul valore di L ma su una sua linearizzazione, per ovviare alla distorsione introdotta dal fatto che, nel modello HSL, L=0,5 non corrisponde al centro dell'intervallo di luminosità percepita, ma alla luminosità della tinta H alla massima saturazione.
  • 'chroma'  —  All'effetto di 'smooth' viene aggiunta una mezza rotazione di H, ottenendo il colore complementare.
  • 'b|w'  —  Restituisce bianco o nero, rispettivamente per gli sfondi scuri e chiari.

• background  —  Un oggetto jQuery indicante in maniera esplicita l'elemento da cui estrarre il colore dello sfondo; viene considerato solo il suo primo elemento. Utile, per esempio, quando l'elemento contenente il testo non ha un proprio valore di background e non è posizionato all'interno del box generato dall'elemento che lo contiene nell'HTML.

set

o c  —  Imposta la proprietà color di tutti gli elementi ad un valore adatto al loro sfondo, se la differenza tra colore e sfondo del testo è inferiore alla soglia indicata dall'opzione level.

• mode  —  Come in fitting.
• level  —  default = 1  —  Un valore numerico compreso tra 0 e 1. Indica il valore di soglia nelle differenze di colore e luminosità in rapporto alle soglie raccomandate dal W3C come sufficienti a garantire la leggibilità del testo. Questi valori non sono direttamente corrispondenti a quelli in uscita da brightnessDiff e colorDiff ma sono rinormalizzati come indicato qui sotto.

  • Il valore 1 causa la sostituzione di color senza alcuna verifica sulla combinazione di colori.
  • Il valore 0.5 adotta le soglie indicate dal W3C.
  • Il valore 0 evita la sostituzione di color senza alcuna verifica sulla combinazione di colori.
  • Valore intermedi modificano linearmente i valori di soglia nei due segmenti in cui l'intervallo complessivo è diviso dalla soglia indicata dal W3C.

• background  —  Come in fitting.

isBadNow

e o u  —  Restituisce true se la combinazione corrente di colori non è ben leggibile.

• level  —  default = 0.5  —  Tranne il default, come in set.
• background  —  Come in fitting.

oneIsBadNow

o u  —  Restituisce true se la combinazione corrente di colori di almeno uno degli elementi non è ben leggibile.

• level  —  default = 0.5  —  Tranne il default, come in set.
• background  —  Come in fitting.

brightnessDiff

e o u  —  Restituisce la differenza di luminosità tra testo e sfondo, secondo la formula indicata nella raccomandazione W3C, ma normalizzata nell'intervallo [0, 1].

• background  —  Come in fitting.

colorDiff

e o u  —  Restituisce la differenza di colore tra testo e sfondo, secondo la formula indicata nella raccomandazione W3C, ma normalizzata nell'intervallo [0, 1].

• background  —  Come in fitting.

color

e u  —  Restituisce il color CSS dell'elemento.

background

e u  —  Restituisce il background-color CSS dell'elemento, eventualmente risalendo per i suoi elementi contenitori fino a trovarne uno con valore diverso da transparent.

colorAndBackgroundArray

e o u  —  Restituisce un array di due elementi, rappresentanti i colori del testo e dello sfondo dell'elemento in forma di array [R, G, B].

• background  —  Come in fitting.