イマーシブ リーダー 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>;

戻り値

イマーシブ リーダーが読み込まれたときに解決される 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;

renderButtons のオプション

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

{
    elements: HTMLDivElement[];
}

Type: HTMLDivElement[]
Required: false

[起動] ボタン

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

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

ボタンの外観を構成するには、次の省略可能な属性を使用します。

LaunchResponse

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

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

エラー

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

{
    code: string;
    message: string;
}

型

コンテンツ

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

{
    title?: string;
    chunks: 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;
}

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 タイプ

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

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

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

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

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

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 に格納する設定について説明します。

サポートされている言語

イマーシブ リーダーの翻訳機能では、多くの言語がサポートされています。 詳細については、「言語サポート」を参照してください。

HTML サポート

書式設定が有効になっている場合、次のコンテンツはイマーシブ リーダーで HTML としてレンダリングされます。

サポートされていないタグは、比較可能にレンダリングされます。 イメージとテーブルは現在サポートされていません。

ブラウザーのサポート

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

• Microsoft Edge
• Google Chrome
• Mozilla Firefox
• Apple Safari

次のステップ