イマーシブ リーダー JavaScript SDK リファレンス (v1.4)
イマーシブ リーダー SDK には、お客様のアプリケーションにイマーシブ リーダーを統合させる JavaScript ライブラリが含まれています。
npm、yarn、または HTML <script>要素を使用して、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
関数
SDK では、次の関数が公開されます。
- ImmersiveReader.launchAsync(token, subdomain, content, options)
- ImmersiveReader.close()
- ImmersiveReader.renderButtons(options)
機能： launchAsync
ImmersiveReader.launchAsync(token, subdomain, content, options)は、Web アプリケーションの HTML iframe要素内でイマーシブ リーダーを起動します。 コンテンツのサイズは最大 50 MB に制限されています。
launchAsync(token: string, subdomain: string, content: Content, options?: Options): Promise<LaunchResponse>;
| パラメーター | 型 | 説明 |
|---|---|---|
| token | string | Microsoft Entra 認証トークン。 詳細については、「イマーシブ リーダー リソースを作成する方法を参照してください。 |
| サブドメイン | string | Azure のイマーシブ リーダー リソースのカスタム サブドメイン。 |
| content | コンテンツ | イマーシブ リーダーに表示するコンテンツを含むオブジェクト。 |
| options | [オプション] | イマーシブ リーダーの特定の動作を構成するオプション。 省略可能。 |
戻り値
イマーシブ リーダーが読み込まれたときに解決される Promise<LaunchResponse> を返します。 Promiseは、LaunchResponse オブジェクトに解決されます。
例外
イマーシブ リーダーの読み込みに失敗した場合、返されたPromiseは、Error オブジェクトで拒否されます。
機能： close
ImmersiveReader.close()は、イマーシブ リーダーを閉じます。
この関数のユース ケースの例には、hideExitButton: trueオプションで を設定して終了ボタンを非表示にする場合があります。 その後、別のボタン (モバイル ヘッダーの戻る矢印など) をクリックすると、この close 関数を呼び出すことができます。
close(): void;
機能： renderButtons
イマーシブ リーダー ボタンをカスタマイズする方法ガイダンス使用する場合、ImmersiveReader.renderButtons(options)関数は必要ありません。
この関数は、ドキュメントのイマーシブ リーダー ボタン要素のスタイル設定と更新を行います。 options.elements指定すると、options.elementsで提供される各要素内にボタンがレンダリングされます。 ドキュメント内にイマーシブ リーダーを起動するセクションが複数あり、同じスタイルで複数のボタンを簡単にレンダリングしたい場合、またはシンプルな同じデザイン パターンでボタンをレンダリングしたい場合は、options.elements パラメーターを使用すると便利です。 renderButtons オプション パラメーターでこの関数を使用するには、次のコード スニペットに示すように、ページ読み込み時にImmersiveReader.renderButtons(options: RenderButtonsOptions);を呼び出します。 それ以外の場合は、「イマーシブ リーダー ボタンをカスタマイズする方法に示すように、クラスがimmersive-reader-buttonされているドキュメントの要素内にボタンがレンダリングされます。
// 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});
その他のレンダリング オプションについては、 起動ボタン 省略可能な属性を参照してください。 これらのオプションを使用するには、いずれかのオプション属性をページの HTML の各 HTMLDivElement に追加します。
renderButtons(options?: RenderButtonsOptions): void;
| パラメーター | 型 | 説明 |
|---|---|---|
| options | renderButtons のオプション | renderButtons 関数の特定の動作を構成するためのオプション。 省略可能。 |
renderButtons のオプション
イマーシブ リーダー ボタンをレンダリングするためのオプション。
{
elements: HTMLDivElement[];
}
| パラメーター | 型 | 説明 |
|---|---|---|
| 要素 | HTMLDivElement[] | イマーシブ リーダー ボタンを内部にレンダリングする要素。 |
Type: HTMLDivElement[]
Required: false
[起動] ボタン
SDK には、イマーシブ リーダー起動ボタンの既定のスタイル設定が用意されています。 このスタイルを有効にするには、immersive-reader-button クラス属性を使用します。 詳細については、「イマーシブ リーダー ボタンをカスタマイズする方法を参照してください。
<div class='immersive-reader-button'></div>
ボタンの外観を構成するには、次の省略可能な属性を使用します。
| 属性 | 説明 |
|---|---|
| data-button-style | ボタンのスタイルを設定します。 icon、text、または iconAndText を指定できます。 既定値は icon です。 |
| data-locale | ロケールを設定します。 たとえば、en-US または fr-FR です。 既定値は英語 en です。 |
| data-icon-px-size | アイコンのサイズをピクセル単位で設定します。 既定値は 20 px です。 |
LaunchResponse
ImmersiveReader.launchAsync の呼び出しからの応答を含みます。 イマーシブ リーダーを含む HTML iframe要素への参照は、container.firstChild経由でアクセスできます。
{
container: HTMLDivElement;
sessionId: string;
charactersProcessed: number;
}
| パラメーター | 型 | 説明 |
|---|---|---|
| container | HTMLDivElement | イマーシブ リーダーの iframe 要素が含まれる HTML 要素。 |
| sessionID | String | このセッションのグローバル一意識別子。デバッグに使用されます。 |
| charactersProcessed | number | 処理対象の文字の合計数 |
エラー
エラーに関する情報が含まれます。
{
code: string;
message: string;
}
| パラメーター | 型 | 説明 |
|---|---|---|
| code | String | エラー コードのセットの1つ。 |
| message | String | 人が判読できるエラーの表現。 |
| エラー コード | 説明 |
|---|---|
| BadArgument | 指定された引数が無効です。 エラー message パラメーターを参照してください。 |
| タイムアウト | 指定されたタイムアウト時間内にイマーシブ リーダーを読み込めませんでした。 |
| TokenExpired | 与えられたトークンの期限が切れています。 |
| Throttled | 呼び出しレートの制限を超えました。 |
型
コンテンツ
イマーシブ リーダーで表示するコンテンツを含みます。
{
title?: string;
chunks: Chunk[];
}
| パラメーター | 型 | 説明 |
|---|---|---|
| 肩書き | String | イマーシブ リーダーの上部に表示されるタイトルのテキスト (省略可能) |
| チャンク | Chunk[] | チャンクの配列 |
title
Type: String
Required: false
Default value: "Immersive Reader"
chunks
Type: Chunk[]
Required: true
Default value: null
チャンク
データの 1 つのチャンク。イマーシブ リーダーのコンテンツに渡されます。
{
content: string;
lang?: string;
mimeType?: string;
}
| パラメーター | 型 | 説明 |
|---|---|---|
| コンテンツ | String | イマーシブ リーダーに送信されるコンテンツが含まれる文字列。 |
| lang | String | テキストの言語。値は IETF BCP 47 言語 タグ形式 (en、es-ES など) です。 言語が指定されていない場合、自動的に検出されます。 詳細については、サポートされる言語 を参照してください。 |
| mimeType | string | プレーンテキスト、MathML、HTML、Microsoft Word DOCX の形式がサポートされています。 詳細については、「サポートされている MIME タイプ」を参照してください。 |
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"
サポートされている MIME タイプ
| MIME のタイプ | 説明 |
|---|---|
| text/plain | プレーンテキスト。 |
| text/html | HTML コンテンツ。 |
| application/mathml+xml | 数学マークアップ言語 (MathML)。 |
| application/vnd.openxmlformats-officedocument.wordprocessingml.document | Microsoft Word の .docx 形式のドキュメント。 |
Options
イマーシブ リーダーの特定の動作を構成するプロパティを含みます。
{
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;
}
| パラメーター | 型 | 説明 |
|---|---|---|
| uiLang | String | UI の言語。値は IETF BCP 47 言語 タグ形式 (en、es-ES など) です。 指定しない場合の既定値はブラウザーの言語です。 |
| timeout | 番号 | launchAsync がタイムアウト エラーで失敗するまでの期間 (ミリ秒単位) (既定値は 15,000 ミリ秒)。 このタイムアウトは、リーダー ページの初回起動にのみ適用されます (リーダー ページが正常に開き、スピナーが開始された場合)。 タイムアウトの調整は必要ありません。 |
| uiZIndex | 番号 | 作成される HTML iframe 要素の Z インデックス (既定値は 1000)。 |
| useWebview | Boolean | Chrome Apps との互換性のために、HTML iframe 要素の代わりに Webview タグを使用します (既定値は false)。 |
| onExit | 機能 | イマーシブ リーダーが終了したときに実行されます。 |
| customDomain | String | 内部使用のために予約されています。 イマーシブ リーダーの webapp がホストされているカスタム ドメイン (既定値は null)。 |
| allowFullscreen | Boolean | 全画面表示を切り替える機能 (既定値は true)。 |
| parent | ノード | HTML iframe 要素または Webview コンテナーが配置されているノード。 この要素が存在しない場合、iframe は body に配置されます。 |
| hideExitButton | Boolean | イマーシブ リーダーの終了ボタンの矢印を非表示にします (既定値は false)。 この値は、イマーシブ リーダーを終了するための代替メカニズム (モバイル ツール バーの戻る矢印など) がある場合にのみ true にする必要があります。 |
| cookiePolicy | CookiePolicy | イマーシブ リーダーでの Cookie の使用の設定 (既定値は CookiePolicy.Disable)。 EU の Cookie コンプライアンス ポリシーに従って必要なユーザーの同意を取得するのは、ホスト アプリケーションの責任となります。 詳細については、「 Cookie ポリシー オプション」を参照してください。 |
| disableFirstRun | Boolean | 最初の実行のエクスペリエンスを無効にします。 |
| readAloudOptions | ReadAloudOptions | 音声読み上げを構成するためのオプション。 |
| translationOptions | TranslationOptions | 翻訳を構成するためのオプション。 |
| displayOptions | DisplayOptions | テキスト サイズ、フォント、テーマなどを構成するためのオプション。 |
| preferences | String | イマーシブ リーダーでのユーザーの個人設定を表す、onPreferencesChanged から返される文字列。 詳細については、「 ユーザー設定を保存する方法」を参照してください。 |
| onPreferencesChanged | 機能 | ユーザーの個人設定が変更されたときに実行されます。 詳細については、「 ユーザー設定を保存する方法」を参照してください。 |
| disableTranslation | ブール値 | 単語とドキュメントの翻訳エクスペリエンスを無効にします。 |
| disableGrammar | ブール値 | 文法エクスペリエンスを無効にします。 このオプションでは、音声の部分に依存する音節、音声の部分、図辞書も無効になります。 |
| disableLanguageDetection | ブール値 | 言語検出を無効にして、イマーシブ リーダーが Content/Chunk[] で明示的に指定された言語のみ使用するようにします。 このオプションは、主に言語検出が機能しない状況では、慎重に使用する必要があります。 たとえば、この問題は、100 文字未満の短い一節で発生する可能性が高くなります。 テキスト読み上げでは正しい音声が得られないため、送信する言語について確認する必要があります。 言語が正しくない場合、音節、音声パーツ、図辞書が正しく機能しません。 |
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
注意事項
Immersive Reader アプリケーションとの間で送受信される -preferences 文字列の値を、プログラムで変更しようとしないでください。それによって予期しない動作が発生し、ユーザー エクスペリエンスが低下する可能性があります。 ホスト アプリケーションによってカスタム値を割り当てたり、-preferences 文字列を操作したりしないでください。 -preferences 文字列オプションを使用する場合は、-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;
};
| パラメーター | 型 | 説明 |
|---|---|---|
| voice | String | 音声( Female または Male。 すべての言語で両方の性別がサポートされているわけではありません。 |
| 速度 | 番号 | 再生速度。 0.5 ~ 2.5 の間である必要があります (両端を含む)。 |
| autoPlay | Boolean | イマーシブ リーダーが読み込まれたら、読み上げを自動的に開始します。 |
Note
ブラウザーの制限により、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;
};
| パラメーター | 型 | 説明 |
|---|---|---|
| language | String | 翻訳言語を設定します。値は IETF BCP 47 言語 タグ形式 (fr-FR、es-MX、zh-Hans-CN など) です。 単語またはドキュメントの翻訳を自動的に有効にするために必要です。 |
| autoEnableDocumentTranslation | Boolean | ドキュメント全体を自動的に翻訳します。 |
| autoEnableWordTranslation | Boolean | 単語の翻訳を自動的に有効にします。 |
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
};
| パラメーター | 型 | 説明 |
|---|---|---|
| textSize | 番号 | 選択されたテキストのサイズを設定します。 |
| increaseSpacing | Boolean | テキストの間隔をオンまたはオフに切り替えるかどうかを設定します。 |
| fontFamily | String | 選択したフォント (Calibri、 ComicSans、または Sitka) を設定します。 |
| themeOption | ThemeOption | リーダーの選択したテーマ (Light、 Dark) を設定します。 |
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"
CookiePolicy オプション
enum CookiePolicy { Disable, Enable }
次の設定は情報提供のみを目的としています。 イマーシブ リーダーの設定 (またはユーザーの個人設定) は、Cookie に格納されます。 この cookiePolicy オプションを使用すると、EU の Cookie コンプライアンス法に準拠するため、Cookie の使用が既定で無効になります。 Cookie を再度有効にし、イマーシブ リーダーユーザー設定の既定の機能を復元する場合は、Cookie を有効にするために、Web サイトまたはアプリケーションがユーザーから適切な同意を得る必要があります。 その後、イマーシブ リーダーで Cookie を再び有効にするには、イマーシブ リーダーを起動するときに、cookiePolicy オプションを明示的に CookiePolicy.Enable に設定する必要があります。
次の表では、cookiePolicy オプションが有効になっている場合にイマーシブ リーダーが Cookie に格納する設定について説明します。
| 設定 | Type | 説明 |
|---|---|---|
| textSize | 番号 | 選択されたテキストのサイズを設定します。 |
| fontFamily | String | 選択したフォント (Calibri、 ComicSans、または Sitka) を設定します。 |
| textSpacing | 番号 | テキストの間隔をオンまたはオフに切り替えるかどうかを設定します。 |
| formattingEnabled | Boolean | HTML の書式設定をオンまたはオフに切り替えるかどうかを設定します。 |
| テーマ | String | 選択したテーマ (Light、 Dark) を設定します。 |
| syllabificationEnabled | Boolean | 分節法をオンまたはオフに切り替えるかどうかを設定します。 |
| nounHighlightingEnabled | Boolean | 名詞の強調表示をオンまたはオフに切り替えます。 |
| nounHighlightingColor | String | 選択した名詞の強調表示色を設定します。 |
| verbHighlightingEnabled | Boolean | 動詞の強調表示をオンまたはオフに切り替えます。 |
| verbHighlightingColor | String | 選択した動詞の強調表示色を設定します。 |
| adjectiveHighlightingEnabled | Boolean | 形容詞の強調表示をオンまたはオフに切り替えます。 |
| adjectiveHighlightingColor | String | 選択した形容詞の強調表示色を設定します。 |
| adverbHighlightingEnabled | Boolean | 副詞の強調表示をオンまたはオフに切り替えます。 |
| adverbHighlightingColor | String | 選択した副詞の強調表示色を設定します。 |
| pictureDictionaryEnabled | Boolean | 絵辞書をオンまたはオフに切り替えるかどうかを設定します。 |
| posLabelsEnabled | Boolean | 強調表示されている各品詞の上付きテキスト ラベルをオンまたはオフに切り替えるかどうかを設定します。 |
サポートされている言語
イマーシブ リーダーの翻訳機能では、多くの言語がサポートされています。 詳細については、「言語サポート」を参照してください。
HTML サポート
書式設定が有効になっている場合、次のコンテンツはイマーシブ リーダーで HTML としてレンダリングされます。
| HTML | サポートされているコンテンツ |
|---|---|
| フォント スタイル | 太字、斜体、下線、コード、取り消し線、上付き文字、下付き文字 |
| 順序指定されていないリスト | ディスク、円、四角形 |
| 順序指定されたリスト | Decimal、upper-Alpha、lower-Alpha、upper-Roman、lower-Roman |
サポートされていないタグは、比較可能にレンダリングされます。 イメージとテーブルは現在サポートされていません。
ブラウザーのサポート
イマーシブ リーダーのエクスペリエンスを最適化するには、次のブラウザーの最新バージョンを使用してください。
- Microsoft Edge
- Google Chrome
- Mozilla Firefox
- Apple Safari