イマーシブ リーダー JavaScript SDK リファレンス (v1.2)

イマーシブ リーダー SDK には、お客様のアプリケーションにイマーシブ リーダーを統合させる JavaScript ライブラリが含まれています。

npmyarn、または HTML<script> 要素を使用して、Web アプリケーションに最新の安定したビルドのライブラリを含めることができます。

<script type='text/javascript' src='https://ircdname.azureedge.net/immersivereadersdk/immersive-reader-sdk.1.2.0.js'></script>
npm install @microsoft/immersive-reader-sdk
yarn add @microsoft/immersive-reader-sdk

関数

SDK では、次の関数が公開されています。


launchAsync

Web アプリケーションの HTMLiframe 要素内でイマーシブ リーダーを起動します。 コンテンツのサイズは最大 50 MB に制限されています。

launchAsync(token: string, subdomain: string, content: Content, options?: Options): Promise<LaunchResponse>;

launchAsync のパラメーター

名前 Type 説明
token string Azure AD 認証トークン。 詳細については、イマーシブ リーダー リソースの作成方法に関するページを参照してください。
subdomain string Azure 内のイマーシブ リーダー リソースのカスタム サブドメイン。 詳細については、イマーシブ リーダー リソースの作成方法に関するページを参照してください。
content コンテンツ イマーシブ リーダーで表示するコンテンツを含むオブジェクト。
options [オプション] イマーシブ リーダーの特定の動作を構成するオプション。 省略可能。

戻り値

イマーシブ リーダーが読み込まれたときに解決される Promise<LaunchResponse> を返します。 PromiseLaunchResponse オブジェクトに解決されます。

例外

イマーシブ リーダーの読み込みに失敗した場合、返された PromiseError オブジェクトで拒否されます。 詳細については、「エラー コード」を参照してください。


close

イマーシブ リーダーを閉じます。

この関数のユース ケースの例には、hideExitButton: trueオプション を設定して終了ボタンを非表示にする場合があります。 その後、別のボタン (たとえば、モバイル ヘッダーの戻る矢印) がクリックされたときに、この close 関数を呼び出すことができます。

close(): void;

イマーシブ リーダーの起動ボタン

SDK は、イマーシブ リーダーの起動用ボタンに既定のスタイルを提供します。 このスタイルを有効にするには、immersive-reader-button クラス属性を使用します。 詳細については、「イマーシブ リーダーのボタンをカスタマイズする方法」を参照してください。

<div class='immersive-reader-button'></div>

省略可能な属性

ボタンのルック アンド フィールを構成するには、次の属性を使用します。

属性 説明
data-button-style ボタンのスタイルを設定します。 icontext、または iconAndText を指定できます。 既定値は icon です。
data-locale ロケールを設定します。 たとえば、en-US または fr-FR です。 既定値は英語 en です。
data-icon-px-size アイコンのサイズをピクセル単位で設定します。 既定値は 20px です。

renderButtons

イマーシブ リーダーのボタンをカスタマイズする方法」のガイダンスを使用している場合は、renderButtons 関数は必要ありません。

この関数は、ドキュメントのイマーシブ リーダー ボタン要素のスタイル設定と更新を行います。 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;

renderButtons のパラメーター

名前 Type 説明
options renderButtons のオプション renderButtons 関数の特定の動作を構成するためのオプション。 省略可能。

renderButtons のオプション

イマーシブ リーダー ボタンをレンダリングするためのオプション。

{
    elements: HTMLDivElement[];
}

renderButtons のオプションのパラメーター

設定 Type 説明
要素 HTMLDivElement[] イマーシブ リーダー ボタンを内部にレンダリングする要素。
elements
Type: HTMLDivElement[]
Required: false

LaunchResponse

ImmersiveReader.launchAsync の呼び出しからの応答を含みます。 イマーシブ リーダーを含む HTMLiframe 要素への参照には、container.firstChild を使用してアクセスできます。

{
    container: HTMLDivElement;
    sessionId: string;
    charactersProcessed: number;
}

LaunchResponse のパラメーター

設定 Type 説明
container HTMLDivElement イマーシブ リーダーの iframe 要素が含まれる HTML 要素。
sessionID String このセッションのグローバル一意識別子。デバッグに使用されます。
charactersProcessed number 処理対象の文字の合計数

エラー

エラーに関する情報が含まれます。

{
    code: string;
    message: string;
}

エラーのパラメーター

設定 Type 説明
code String エラー コードのセットの1つ。 詳細については、 エラー コードをご覧ください
message String 人が判読できるエラーの表現。

エラー コード

コード 説明
BadArgument 指定した引数が無効です。「エラー」の message パラメーターを参照してください。
タイムアウト 指定されたタイムアウト時間内にイマーシブ リーダーを読み込めませんでした。
TokenExpired 与えられたトークンの期限が切れています。
Throttled 呼び出しレートの制限を超えました。

コンテンツ

イマーシブ リーダーで表示するコンテンツを含みます。

{
    title?: string;
    chunks: Chunk[];
}

Content のパラメーター

名前 Type 説明
title 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;
}

Chunk のパラメーター

名前 Type 説明
コンテンツ 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 Mathematical Markup Language (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;
}

Options のパラメーター

名前 Type 説明
uiLang String UI の言語。値は IETF BCP 47 の言語タグ形式です (例: en、es-ES)。 指定しない場合の既定値はブラウザーの言語です。
timeout 番号 launchAsync がタイムアウト エラーで失敗するまでの期間 (ミリ秒単位) (既定値は 15,000 ミリ秒)。 このタイムアウトは、リーダー ページの初回起動にのみ適用されます (リーダー ページが正常に開き、スピナーが開始された場合)。 タイムアウトを調整する必要はありません。
uiZIndex 番号 作成される HTMLiframe 要素の Z インデックス (既定値は 1000)。
useWebview Boolean Chrome アプリとの互換性のために、HTMLiframe 要素の代わりに webview タグを使用します (既定値は false)。
onExit 機能 イマーシブ リーダーが終了したときに実行されます。
customDomain String 内部使用のために予約されています。 イマーシブ リーダーの webapp がホストされているカスタム ドメイン (既定値は null)。
allowFullscreen Boolean 全画面表示を切り替える機能 (既定値は true)。
parent Node HTMLiframe 要素または 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

注意事項

重要 イマーシブ リーダー アプリケーションとの間で送受信される -preferences の文字列の値を、プログラムで変更しようとしないでください。予期しない動作が発生し、顧客のユーザー エクスペリエンスが低下する可能性があります。 ホスト アプリケーションによってカスタム値を割り当てたり、-preferences 文字列を操作したりしないでください。 -preferences 文字列オプションを使用する場合は、-onPreferencesChanged コールバック オプションから返された正確な値のみを使用してください。

Type: String
Required: false
Default value: null
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;
};

ReadAloudOptions のパラメーター

名前 Type 説明
voice String 音声。"Female" または "Male"。 すべての言語で両方の性別がサポートされているわけではありません。
速度 番号 再生速度。0.5 から 2.5 の範囲で指定する必要があります。
autoPlay Boolean イマーシブ リーダーが読み込まれたら、読み上げを自動的に開始します。
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

Note

ブラウザーの制限により、Safari では自動再生はサポートされていません。


TranslationOptions

type TranslationOptions = {
    language: string;
    autoEnableDocumentTranslation?: boolean;
    autoEnableWordTranslation?: boolean;
};

TranslationOptions のパラメーター

名前 Type 説明
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
};

DisplayOptions のパラメーター

名前 Type 説明
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 を再度有効にし、イマーシブ リーダーのユーザー個人設定の既定の機能を元に戻す必要がある場合は、Web サイトまたはアプリケーションで、ユーザーから Cookie を有効にする適切な同意を得る必要があります。 その後、イマーシブ リーダーで 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 サポートされているコンテンツ
フォント スタイル 太字、斜体、下線、コード、取り消し線、上付き文字、下付き文字
順不同のリスト ディスク、円、正方形
順序指定済みリスト 小数点、大文字アルファベット、小文字アルファベット、大文字ローマ字、小文字ローマ字

サポートされていないタグが同等にレンダリングされます。 イメージとテーブルは現在サポートされていません。


ブラウザーのサポート

イマーシブ リーダーのエクスペリエンスを最適化するには、次のブラウザーの最新バージョンを使用してください。

  • Microsoft Edge
  • Internet Explorer 11
  • Google Chrome
  • Mozilla Firefox
  • Apple Safari

次のステップ