javaScript SDK 참조 몰입형 리더(v1.4)

  • 아티클

몰입형 리더 SDK에는 몰입형 리더 애플리케이션에 통합할 수 있는 JavaScript 라이브러리가 포함되어 있습니다.

또는 HTML <script> 요소를 사용하여 yarnnpm웹 애플리케이션에 안정적인 최신 빌드 라이브러리를 포함할 수 있습니다.

<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는 다음 함수를 노출합니다.

함수: launchAsync

ImmersiveReader.launchAsync(token, subdomain, content, options)는 웹 애플리케이션의 HTML iframe 요소 내에서 몰입형 리더 시작합니다. 콘텐츠 크기는 최대 50MB로 제한됩니다.

launchAsync(token: string, subdomain: string, content: Content, options?: Options): Promise<LaunchResponse>;
매개 변수 형식 설명
token string Microsoft Entra 인증 토큰입니다. 자세한 내용은 몰입형 리더 리소스를 만드는 방법을 참조하세요.
하위 도메인 string Azure에서 몰입형 리더 리소스의 사용자 지정 하위 기본.
콘텐츠 콘텐츠 몰입형 리더 표시할 내용이 들어 있는 개체입니다.
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>

단추의 모양과 느낌을 구성하려면 다음 선택적 특성을 사용합니다.

attribute 설명
데이터 단추 스타일 단추의 스타일을 설정합니다. icon, text 또는 iconAndText일 수 있습니다. 기본값은 icon입니다.
데이터 로캘 로캘을 설정합니다. 예를 들어 en-US 또는 fr-FR입니다. 기본값은 영어 en입니다.
data-icon-px-size 아이콘의 크기를 픽셀 단위로 설정합니다. 기본값은 20px입니다.

LaunchResponse

에 대한 호출 ImmersiveReader.launchAsync의 응답을 포함합니다. 몰입형 리더 포함하는 HTML iframe 요소에 대한 참조는 을 통해 container.firstChild액세스할 수 있습니다.

{
    container: HTMLDivElement;
    sessionId: string;
    charactersProcessed: number;
}
매개 변수 형식 설명
컨테이너 HTMLDivElement Immersive Reader iframe 요소가 포함된 HTML 요소입니다.
sessionId 문자열 디버깅에 사용되는 이 세션의 전역적으로 고유한 식별자입니다.
charactersProcessed number 처리된 총 문자 수

오류

오류에 대한 정보를 포함합니다.

{
    code: string;
    message: string;
}
매개 변수 형식 설명
코드 문자열 오류 코드 집합 중 하나입니다.
message 문자열 사람이 읽을 수 있는 오류 표현입니다.
오류 코드 설명
BadArgument 제공된 인수가 잘못되었습니다. 오류의 매개 변수를 참조 message 하세요.
시간 제한 지정된 시간 제한 내에 몰입형 리더 로드하지 못했습니다.
TokenExpired 제공된 토큰이 만료되었습니다.
Throttled 호출 속도 제한을 초과했습니다.

유형

콘텐츠

몰입형 리더 표시할 콘텐츠를 포함합니다.

{
    title?: string;
    chunks: Chunk[];
}
매개 변수 형식 설명
제목 문자열 몰입형 리더 맨 위에 표시된 제목 텍스트(선택 사항)
청크 청크[] 청크 배열
title
Type: String
Required: false
Default value: "Immersive Reader"
chunks
Type: Chunk[]
Required: true
Default value: null

Chunk

몰입형 리더 콘텐츠에 전달되는 단일 데이터 청크입니다.

{
    content: string;
    lang?: string;
    mimeType?: string;
}
매개 변수 형식 설명
콘텐츠 문자열 몰입형 리더 전송된 콘텐츠가 들어 있는 문자열입니다.
lang 문자열 텍스트의 언어로, 값은 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 서식 문서입니다.

옵션

몰입형 리더 특정 동작을 구성하는 속성을 포함합니다.

{
    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 문자열 UI의 언어로, 값은 IETF BCP 47 언어 태그 형식(예: en, es-ES)입니다. 지정하지 않으면 기본적으로 브라우저 언어로 설정됩니다.
시간 제한 숫자 launchAsync에서 시간 제한 오류가 발생하기 전까지의 기간(밀리초)입니다(기본값: 15000ms). 이 시간 제한은 리더 페이지가 성공적으로 열리고 회전자가 시작되면 리더 페이지의 초기 시작에만 적용됩니다. 시간 제한을 조정할 필요가 없습니다.
uiZIndex 숫자 생성된 HTML iframe 요소의 Z 인덱스입니다(기본값은 1000).
useWebview Boolean Chrome Apps와의 호환성을 위해 HTML iframe 요소 대신 웹 보기 태그를 사용합니다(기본값은 false).
Onexit 함수 몰입형 리더가 종료될 때 실행됩니다.
customDo기본 문자열 내부용으로 예약되어 있습니다. 사용자 지정 기본 몰입형 리더 웹앱이 호스트되는 위치입니다(기본값은 null).
allowFullscreen Boolean 전체 화면을 토글하는 기능입니다(기본값은 true).
parent 노드 HTML iframe 요소 또는 Webview 컨테이너가 배치되는 노드입니다. 요소가 없으면 iframe은 body에 배치됩니다.
hideExitButton Boolean Immersive Reader의 종료 단추 화살표를 숨깁니다(기본값: false). 이 값은 몰입형 리더 종료하기 위해 제공되는 대체 메커니즘(예: 모바일 도구 모음의 뒤로 화살표)이 있는 경우에만 true여야 합니다.
cookiePolicy CookiePolicy 몰입형 리더의 쿠키 사용에 대한 설정입니다(기본값은 CookiePolicy.Disable). 호스트 애플리케이션에서 EU 쿠키 준수 정책에 따라 필요한 모든 사용자 동의를 얻어야 합니다. 자세한 내용은 쿠키 정책 옵션을 참조 하세요.
disableFirstRun Boolean 첫 번째 실행 환경을 사용하지 않도록 설정합니다.
readAloudOptions ReadAloudOptions 소리 내어 읽기를 구성하는 옵션입니다.
translationOptions TranslationOptions 번역을 구성하는 옵션입니다.
displayOptions DisplayOptions 텍스트 크기, 글꼴, 테마 등을 구성하는 옵션입니다.
preferences 문자열 몰입형 리더 사용자의 기본 설정을 나타내는 onPreferencesChanged에서 반환된 문자열입니다. 자세한 내용은 사용자 기본 설정을 저장하는 방법을 참조 하세요.
onPreferencesChanged 함수 사용자 기본 설정이 변경될 때 실행됩니다. 자세한 내용은 사용자 기본 설정을 저장하는 방법을 참조 하세요.
disableTranslation Boolean 단어 및 문서 번역 환경을 사용하지 않습니다.
disableGrammar Boolean 문법 환경을 사용하지 않습니다. 또한 이 옵션은 음절, 음성 부분 및 그림 사전을 사용하지 않도록 설정합니다. 이 사전은 음성의 일부에 따라 달라집니다.
disableLanguageDetection Boolean Immersive Reader에서 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

주의

예기치 않은 동작으로 인해 사용자 환경이 저하될 수 있으므로 몰입형 리더 애플리케이션과 주고 받는 문자열의 -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 문자열 음성, 여성 또는 남성 중 하나. 모든 언어가 두 성을 모두 지원하는 것은 아닙니다.
속도 숫자 재생 속도. 0.5에서 2.5 사이여야 합니다.
자동 Boolean 몰입형 리더 로드되면 소리 내어 읽기를 자동으로 시작합니다.

참고 항목

브라우저 제한으로 인해 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;
};
매개 변수 형식 설명
언어 문자열 번역 언어를 설정합니다. 값은 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 문자열 선택한 글꼴(Calibri, ComicSans 또는 Sitka)을 설정합니다.
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 }

다음 설정은 정보 제공 용도로만 사용됩니다. 몰입형 리더 쿠키에 설정 또는 사용자 기본 설정을 저장합니다. 이 cookiePolicy 옵션은 EU 쿠키 규정 준수법을 준수하기 위해 기본적으로 쿠키 사용을 중지합니다. 쿠키를 다시 사용하도록 설정하고 몰입형 리더 사용자 기본 설정에 대한 기본 기능을 복원하려면 웹 사이트 또는 애플리케이션이 쿠키를 사용하도록 설정하기 위해 사용자의 적절한 동의가 필요합니다. 그런 다음, 몰입형 리더 쿠키를 다시 사용하도록 설정하려면 몰입형 리더 시작할 때 cookiePolicy 옵션을 CookiePolicy.Enable으로 명시적으로 설정해야 합니다.

다음 표에서는 cookiePolicy 옵션을 사용할 때 몰입형 리더 쿠키에 저장하는 설정을 설명합니다.

설정 Type 설명
textSize 숫자 선택한 텍스트 크기를 설정합니다.
fontFamily 문자열 선택한 글꼴(Calibri, ComicSans 또는 Sitka)을 설정합니다.
textSpacing 숫자 텍스트 간격을 설정/해제할지 여부를 설정합니다.
formattingEnabled Boolean HTML 서식 지정을 켜거나 끌지 설정합니다.
테마 문자열 선택한 테마(밝게, 어둡게)를 설정합니다.
syllabificationEnabled Boolean 실라비화를 설정/해제할지 여부를 설정합니다.
nounHighlightingEnabled Boolean 명사 강조 표시를 켜거나 끌지 설정합니다.
nounHighlightingColor 문자열 선택한 명사 강조 표시 색을 설정합니다.
verbHighlightingEnabled Boolean 동사 강조 표시를 켜거나 끌지 설정합니다.
verbHighlightingColor 문자열 선택한 동사 강조 표시 색을 설정합니다.
adjectiveHighlightingEnabled Boolean 형용사 강조 표시를 켜거나 끌지 설정합니다.
adjectiveHighlightingColor 문자열 선택한 형용사 강조 표시 색을 설정합니다.
adverbHighlightingEnabled Boolean 부사 강조 표시를 켜거나 끌지 설정합니다.
adverbHighlightingColor 문자열 선택한 부사 강조 표시 색을 설정합니다.
pictureDictionaryEnabled Boolean 그림 사전을 설정/해제할지 여부를 설정합니다.
posLabelsEnabled Boolean 강조 표시된 각 음성 부분의 위 첨자 텍스트 레이블을 설정하거나 해제할지 여부를 설정합니다.

지원되는 언어

몰입형 리더의 번역 기능은 다양한 언어를 지원합니다. 자세한 내용은 언어 지원을 참조하세요.

HTML 지원

서식을 사용하도록 설정하면 다음 콘텐츠가 몰입형 리더 HTML로 렌더링됩니다.

HTML 지원되는 콘텐츠
글꼴 스타일 굵게, 기울기, 밑줄, 코드, 취소선, 위 첨자, 아래 첨자
순서가 지정되지 않은 목록 디스크, 원, 정사각형
순서가 지정된 목록 10진수, 상위 알파, 하위 알파, 상위 로마, 하부 로마

지원되지 않는 태그는 비교적 렌더링됩니다. 이미지 및 테이블은 현재 지원되지 않습니다.

브라우저 지원

몰입형 리더 최상의 환경을 위해 다음 브라우저의 최신 버전을 사용합니다.

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

다음 단계

몰입형 리더 SDK 살펴보기