Informazioni di riferimento su JavaScript SDK Strumento di lettura immersiva (v1.4)
L'SDK di Strumento di lettura immersiva contiene una libreria JavaScript che consente di integrare il Strumento di lettura immersiva nell'applicazione.
È possibile usare npm, yarno un elemento HTML <script> per includere la libreria della build stabile più recente nell'applicazione Web:
<script type='text/javascript' src='https://ircdname.azureedge.net/immersivereadersdk/immersive-reader-sdk.1.4.0.js'></script>
npm install @microsoft/immersive-reader-sdk
yarn add @microsoft/immersive-reader-sdk
Funzioni
L'SDK espone queste funzioni:
- ImmersiveReader.launchAsync(token, sottodominio, contenuto, opzioni)
- ImmersiveReader.close()
- ImmersiveReader.renderButtons(options)
Funzione: launchAsync
ImmersiveReader.launchAsync(token, subdomain, content, options)avvia il Strumento di lettura immersiva all'interno di un elemento HTML iframe nell'applicazione Web. Le dimensioni del contenuto sono limitate a un massimo di 50 MB.
launchAsync(token: string, subdomain: string, content: Content, options?: Options): Promise<LaunchResponse>;
| Parametro | Tipo | Descrizione |
|---|---|---|
| token | string | Token di autenticazione di Microsoft Entra. Per altre informazioni, vedere Come creare una risorsa Strumento di lettura immersiva. |
| subdomain | string | Sottodominio personalizzato della risorsa Strumento di lettura immersiva in Azure. |
| content | Contenuto | Oggetto che contiene il contenuto da visualizzare nella Strumento di lettura immersiva. |
| opzioni | Opzioni | Opzioni per la configurazione di determinati comportamenti del Strumento di lettura immersiva. Facoltativo. |
Valori restituiti
Restituisce un Promise<LaunchResponse>oggetto , che viene risolto quando viene caricato il Strumento di lettura immersiva. Viene Promise risolto in un oggetto LaunchResponse .
Eccezioni
Se il Strumento di lettura immersiva non viene caricato, l'oggetto restituito Promise viene rifiutato con un oggetto Error.
Funzione: close
ImmersiveReader.close()chiude il Strumento di lettura immersiva.
Un caso d'uso di esempio per questa funzione è se il pulsante di uscita è nascosto impostando hideExitButton: true nelle opzioni. Quindi, un pulsante diverso (ad esempio, la freccia indietro di un'intestazione per dispositivi mobili) può chiamare questa close funzione quando viene fatto clic.
close(): void;
Funzione: renderButtons
La ImmersiveReader.renderButtons(options) funzione non è necessaria se si usa il materiale sussidiario su come personalizzare il pulsante Strumento di lettura immersiva.
Questa funzione stili e aggiorna gli elementi del pulsante Strumento di lettura immersiva del documento. Se options.elements viene specificato, il rendering dei pulsanti viene eseguito all'interno di ogni elemento fornito in options.elements. L'uso del options.elements parametro è utile quando nel documento sono presenti più sezioni in cui avviare il Strumento di lettura immersiva e si vuole un modo semplificato per eseguire il rendering di più pulsanti con lo stesso stile o per eseguire il rendering dei pulsanti con un modello di progettazione semplice e coerente. Per usare questa funzione con il parametro delle opzioni renderButtons, chiamare ImmersiveReader.renderButtons(options: RenderButtonsOptions); il caricamento della pagina come illustrato nel frammento di codice seguente. In caso contrario, il rendering dei pulsanti viene eseguito all'interno degli elementi del documento con la classe immersive-reader-button come illustrato in Come personalizzare il pulsante Strumento di lettura immersiva.
// This snippet assumes there are two empty div elements in
// the page HTML, button1 and button2.
const btn1: HTMLDivElement = document.getElementById('button1');
const btn2: HTMLDivElement = document.getElementById('button2');
const btns: HTMLDivElement[] = [btn1, btn2];
ImmersiveReader.renderButtons({elements: btns});
Per altre opzioni di rendering, vedere gli attributi facoltativi del pulsante di avvio. Per usare queste opzioni, aggiungere uno qualsiasi degli attributi di opzione a ognuno HTMLDivElement nel codice HTML della pagina.
renderButtons(options?: RenderButtonsOptions): void;
| Parametro | Tipo | Descrizione |
|---|---|---|
| opzioni | Opzioni renderButtons | Opzioni per la configurazione di determinati comportamenti della funzione renderButtons. Facoltativo. |
Opzioni renderButtons
Opzioni per il rendering dei pulsanti di Strumento di lettura immersiva.
{
elements: HTMLDivElement[];
}
| Parametro | Tipo | Descrizione |
|---|---|---|
| Elementi figlio | HTMLDivElement[] | Elementi in cui eseguire il rendering dei pulsanti di Strumento di lettura immersiva. |
Type: HTMLDivElement[]
Required: false
Pulsante Di avvio
L'SDK fornisce uno stile predefinito per il pulsante di avvio Strumento di lettura immersiva. Usare l'attributo della classe immersive-reader-button per abilitare questo stile. Per altre informazioni, vedere Come personalizzare il pulsante Strumento di lettura immersiva.
<div class='immersive-reader-button'></div>
Usare gli attributi facoltativi seguenti per configurare l'aspetto del pulsante.
| Attributo | Descrizione |
|---|---|
| stile pulsante dati | Imposta lo stile del pulsante. Può essere icon, text o iconAndText. Il valore predefinito è icon. |
| impostazioni locali dei dati | Imposta le impostazioni locali. Ad esempio, en-US o fr-FR. L'impostazione predefinita è inglese en. |
| data-icon-px-size | Imposta le dimensioni dell'icona in pixel. Il valore predefinito è 20 px. |
LaunchResponse
Contiene la risposta dalla chiamata a ImmersiveReader.launchAsync. È possibile accedere a un riferimento all'elemento HTML iframe che contiene il Strumento di lettura immersiva tramite container.firstChild.
{
container: HTMLDivElement;
sessionId: string;
charactersProcessed: number;
}
| Parametro | Tipo | Descrizione |
|---|---|---|
| container | HTMLDivElement | Elemento HTML che contiene l'elemento Strumento di lettura immersivaiframe. |
| sessionId | String | Identificatore univoco globale per questa sessione, usato per il debug. |
| charactersProcessed | number | Numero totale di caratteri elaborati |
Error
Contiene informazioni su un errore.
{
code: string;
message: string;
}
| Parametro | Tipo | Descrizione |
|---|---|---|
| codice | String | Uno di un set di codici di errore. |
| messaggio | String | Rappresentazione leggibile dell'errore. |
| Codice errore | Descrizione |
|---|---|
| BadArgument | L'argomento fornito non è valido. Vedere message il parametro dell'errore. |
| Timeout | Impossibile caricare il Strumento di lettura immersiva entro il timeout specificato. |
| TokenExpired | Il token fornito è scaduto. |
| Sospensione causata dal servizio Microsoft FullText | È stato superato il limite di frequenza delle chiamate. |
Tipi
Contenuto
Contiene il contenuto da visualizzare nella Strumento di lettura immersiva.
{
title?: string;
chunks: Chunk[];
}
| Parametro | Tipo | Descrizione |
|---|---|---|
| titolo | String | Testo del titolo visualizzato nella parte superiore del Strumento di lettura immersiva (facoltativo) |
| Blocchi | Blocco[] | Matrice di blocchi |
title
Type: String
Required: false
Default value: "Immersive Reader"
chunks
Type: Chunk[]
Required: true
Default value: null
Blocco
Un singolo blocco di dati, che viene passato al contenuto del Strumento di lettura immersiva.
{
content: string;
lang?: string;
mimeType?: string;
}
| Parametro | Tipo | Descrizione |
|---|---|---|
| content | String | Stringa contenente il contenuto inviato al Strumento di lettura immersiva. |
| lang | String | Lingua del testo, il valore è in formato tag IETF BCP 47-language , ad esempio en, es-ES. La lingua viene rilevata automaticamente se non specificata. Per altre informazioni, vedi Lingue supportate. |
| mimeType | string | Sono supportati i formati testo normale, MathML, HTML e Microsoft Word DOCX. Per altre informazioni, vedere Tipi MIME supportati. |
content
Type: String
Required: true
Default value: null
lang
Type: String
Required: false
Default value: Automatically detected
mimeType
Type: String
Required: false
Default value: "text/plain"
Tipi MIME supportati
| tipo MIME | Descrizione |
|---|---|
| text/plain | Testo normale. |
| text/html | Contenuto HTML. |
| application/mathml+xml | MathML (Math Markup Language). |
| application/vnd.openxmlformats-officedocument.wordprocessingml.document | Documento di formato .docx di Microsoft Word. |
Opzioni
Contiene proprietà che configurano determinati comportamenti del Strumento di lettura immersiva.
{
uiLang?: string;
timeout?: number;
uiZIndex?: number;
useWebview?: boolean;
onExit?: () => any;
customDomain?: string;
allowFullscreen?: boolean;
parent?: Node;
hideExitButton?: boolean;
cookiePolicy?: CookiePolicy;
disableFirstRun?: boolean;
readAloudOptions?: ReadAloudOptions;
translationOptions?: TranslationOptions;
displayOptions?: DisplayOptions;
preferences?: string;
onPreferencesChanged?: (value: string) => any;
disableGrammar?: boolean;
disableTranslation?: boolean;
disableLanguageDetection?: boolean;
}
| Parametro | Tipo | Descrizione |
|---|---|---|
| uiLang | String | Lingua dell'interfaccia utente, il valore è in formato tag IETF BCP 47-language , ad esempio en, es-ES. L'impostazione predefinita è la lingua del browser, se non è specificata. |
| timeout | Numero | Durata (in millisecondi) prima dell'errore launchAsync con un errore di timeout (il valore predefinito è 15.000 ms). Questo timeout si applica solo all'avvio iniziale della pagina Lettore, quando la pagina Lettore viene aperta correttamente e viene avviata la selezione. La regolazione del timeout non deve essere necessaria. |
| uiZIndex | Numero | Indice Z dell'elemento HTML iframe creato (il valore predefinito è 1000). |
| useWebview | Booleano | Usa un tag webview invece di un elemento HTML iframe , per compatibilità con Chrome Apps (il valore predefinito è false). |
| onExit | Funzione | Viene eseguito quando il Strumento di lettura immersiva viene chiuso. |
| customDomain | String | Riservato a un uso interno. Dominio personalizzato in cui è ospitata l'app Web Strumento di lettura immersiva (il valore predefinito è Null). |
| allowFullscreen | Booleano | Possibilità di attivare/disattivare lo schermo intero (il valore predefinito è true). |
| parent | Node | Nodo in cui viene inserito l'elemento o Webview il contenitore HTMLiframe. Se l'elemento non esiste, iframe viene inserito in body. |
| hideExitButton | Booleano | Nasconde la freccia del pulsante di uscita del Strumento di lettura immersiva (il valore predefinito è false). Questo valore deve essere true solo se è disponibile un meccanismo alternativo per uscire dal Strumento di lettura immersiva (ad esempio, la freccia indietro di una barra degli strumenti per dispositivi mobili). |
| cookiePolicy | CookiePolicy | Impostazione per l'utilizzo dei cookie di Strumento di lettura immersiva (il valore predefinito è CookiePolicy.Disable). È responsabilità dell'applicazione host ottenere il consenso dell'utente necessario seguendo i criteri di conformità dei cookie dell'UE. Per altre informazioni, vedere Opzioni dei criteri cookie. |
| disableFirstRun | Booleano | Disabilitare la prima esperienza di esecuzione. |
| readAloudOptions | ReadAloudOptions | Opzioni per configurare Lettura ad alta voce. |
| translationOptions | TranslationOptions | Opzioni per configurare la traduzione. |
| displayOptions | DisplayOptions | Opzioni per configurare le dimensioni del testo, il tipo di carattere, il tema e così via. |
| Preferenze | String | Stringa restituita da onPreferencesChanged che rappresenta le preferenze dell'utente nella Strumento di lettura immersiva. Per altre informazioni, vedere Come archiviare le preferenze utente. |
| onPreferencesChanged | Funzione | Viene eseguito quando le preferenze dell'utente sono state modificate. Per altre informazioni, vedere Come archiviare le preferenze utente. |
| disableTranslation | Booleano | Disabilitare l'esperienza di traduzione di parole e documenti. |
| disableGrammar | Booleano | Disabilitare l'esperienza grammatica. Questa opzione disabilita anche Syllables, Parts of Speech e Picture Dictionary, che dipende da parti del parlato. |
| disableLanguageDetection | Booleano | Disabilitare il rilevamento della lingua per assicurarsi che il Strumento di lettura immersiva usi solo la lingua specificata in modo esplicito nel blocco di contenuto/[]. Questa opzione deve essere usata con moderazione, principalmente in situazioni in cui il rilevamento della lingua non funziona. Ad esempio, questo problema è più probabile che si verifichi con brevi passaggi di meno di 100 caratteri. Si dovrebbe essere certi della lingua che si sta inviando, perché la sintesi vocale non avrà la voce corretta. Le sillabe, le parti del parlato e il dizionario immagini non funzionano correttamente se la lingua non è corretta. |
uiLang
Type: String
Required: false
Default value: User's browser language
timeout
Type: Number
Required: false
Default value: 15000
uiZIndex
Type: Number
Required: false
Default value: 1000
onExit
Type: Function
Required: false
Default value: null
preferences
Type: String
Required: false
Default value: null
Attenzione
Non tentare di modificare a livello di codice i valori della stringa -preferences inviata da e verso l'applicazione dello Strumento di lettura immersiva perché questo potrebbe causare un comportamento imprevisto risultante in un'esperienza utente deteriorata. Le applicazioni host non devono mai assegnare un valore personalizzato o modificare la stringa -preferences. Quando si usa l'opzione della stringa -preferences, usare solo il valore esatto restituito dall'opzione di callback -onPreferencesChanged.
onPreferencesChanged
Type: Function
Required: false
Default value: null
customDomain
Type: String
Required: false
Default value: null
ReadAloudOptions
type ReadAloudOptions = {
voice?: string;
speed?: number;
autoplay?: boolean;
};
| Parametro | Tipo | Descrizione |
|---|---|---|
| voice | String | Voce, femminile o maschile. Non tutte le lingue supportano entrambi i sessi. |
| velocità | Numero | Velocità di riproduzione. Deve essere compreso tra 0,5 e 2,5 inclusi. |
| autoPlay | Booleano | Avvia automaticamente Read Aloud quando il Strumento di lettura immersiva viene caricato. |
Nota
A causa delle limitazioni del browser, la riproduzione automatica non è supportata in Safari.
voice
Type: String
Required: false
Default value: "Female" or "Male" (determined by language)
Values available: "Female", "Male"
speed
Type: Number
Required: false
Default value: 1
Values available: 0.5, 0.75, 1, 1.25, 1.5, 1.75, 2, 2.25, 2.5
TranslationOptions
type TranslationOptions = {
language: string;
autoEnableDocumentTranslation?: boolean;
autoEnableWordTranslation?: boolean;
};
| Parametro | Tipo | Descrizione |
|---|---|---|
| lingua | String | Imposta la lingua di traduzione, il valore è in formato tag IETF BCP 47-language , ad esempio fr-FR, es-MX, zh-Hans-CN. Obbligatorio per abilitare automaticamente la traduzione di parole o documenti. |
| autoEnableDocumentTranslation | Booleano | Converte automaticamente l'intero documento. |
| autoEnableWordTranslation | Booleano | Abilitare automaticamente la traduzione di parole. |
language
Type: String
Required: true
Default value: null
Values available: For more information, see the Supported languages section
ThemeOption
enum ThemeOption { Light, Dark }
DisplayOptions
type DisplayOptions = {
textSize?: number;
increaseSpacing?: boolean;
fontFamily?: string;
themeOption?: ThemeOption
};
| Parametro | Tipo | Descrizione |
|---|---|---|
| textSize | Numero | Imposta la dimensione del testo scelta. |
| aumentoSpacing | Booleano | Imposta se l'interlinea del testo è attivata o disattivata. |
| fontFamily | String | Imposta il tipo di carattere scelto (Calibri, ComicSans o Sitka). |
| themeOption | ThemeOption | Imposta il tema scelto del lettore (Chiaro, Scuro). |
textSize
Type: Number
Required: false
Default value: 20, 36 or 42 (Determined by screen size)
Values available: 14, 20, 28, 36, 42, 48, 56, 64, 72, 84, 96
fontFamily
Type: String
Required: false
Default value: "Calibri"
Values available: "Calibri", "Sitka", "ComicSans"
Opzioni CookiePolicy
enum CookiePolicy { Disable, Enable }
Le impostazioni seguenti sono solo a scopo informativo. Il Strumento di lettura immersiva archivia le impostazioni o le preferenze dell'utente nei cookie. Questa opzione cookiePolicy disabilita l'uso dei cookie per impostazione predefinita per seguire le leggi di conformità ai cookie dell'UE. Se si desidera riabilitare i cookie e ripristinare la funzionalità predefinita per Strumento di lettura immersiva preferenze utente, il sito Web o l'applicazione necessita del consenso appropriato dell'utente per abilitare i cookie. Quindi, per riabilitare i cookie nella Strumento di lettura immersiva, è necessario impostare in modo esplicito l'opzione cookiePolicy.Enable quando si avvia il Strumento di lettura immersiva.
Nella tabella seguente vengono descritte le impostazioni archiviate dal Strumento di lettura immersiva nel cookie quando l'opzione cookiePolicy è abilitata.
| Impostazione | Tipo | Descrizione |
|---|---|---|
| textSize | Numero | Imposta la dimensione del testo scelta. |
| fontFamily | String | Imposta il tipo di carattere scelto (Calibri, ComicSans o Sitka). |
| textSpacing | Numero | Imposta se l'interlinea del testo è attivata o disattivata. |
| formattingEnabled | Booleano | Imposta un valore che indica se la formattazione HTML è attivata o disattivata. |
| tema | String | Imposta il tema scelto (Chiaro, Scuro). |
| syllabificationEnabled | Booleano | Imposta se la sillabificazione è attivata o disattivata. |
| sostantivoHighlightingEnabled | Booleano | Imposta un valore che indica se l'evidenziazione del sostantivo è attivata o disattivata. |
| nounHighlightingColor | String | Imposta il colore di evidenziazione sostantivo scelto. |
| verbHighlightingEnabled | Booleano | Imposta un valore che indica se l'evidenziazione dei verbi è attivata o disattivata. |
| verbHighlightingColor | String | Imposta il colore di evidenziazione del verbo scelto. |
| aggettivoHighlightingEnabled | Booleano | Imposta se l'evidenziazione aggettivo è attivata o disattivata. |
| aggettivoHighlightingColor | String | Imposta il colore di evidenziazione aggettivo scelto. |
| adverbHighlightingEnabled | Booleano | Imposta un valore che indica se l'evidenziazione di adverb è attivata o disattivata. |
| adverbHighlightingColor | String | Imposta il colore di evidenziazione dell'elemento adverb scelto. |
| pictureDictionaryEnabled | Booleano | Imposta un valore che indica se il dizionario immagini è attivato o disattivato. |
| posLabelsEnabled | Booleano | Imposta un valore che indica se l'etichetta di testo apice di ogni parte di riconoscimento vocale evidenziata è attivata o disattivata. |
Lingue supportate
La funzionalità di traduzione di Strumento di lettura immersiva supporta molte lingue. Per altre informazioni, vedere Supporto per le lingue.
Supporto HTML
Quando la formattazione è abilitata, il rendering del contenuto seguente viene eseguito come HTML nel Strumento di lettura immersiva.
| HTML | Contenuto supportato |
|---|---|
| Stili carattere | Grassetto, corsivo, sottolineatura, codice, barrato, apice, pedice |
| Elenchi non ordinati | Disco, cerchio, quadrato |
| Elenchi ordinati | Decimal, upper-Alpha, lower-Alpha, upper-Roman, lower-Roman |
Il rendering dei tag non supportati viene eseguito in modo confronto. Le immagini e le tabelle non sono attualmente supportate.
Supporto browser
Usare le versioni più recenti dei browser seguenti per un'esperienza ottimale con il Strumento di lettura immersiva.
- Microsoft Edge
- Google Chrome
- Mozilla Firefox
- Apple Safari