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는 다음 함수를 노출합니다.
- ImmersiveReader.launchAsync(토큰, 하위 도메인, 콘텐츠, 옵션)
- ImmersiveReader.close()
- ImmersiveReader.renderButtons(옵션)
기능: 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에서 몰입형 리더 리소스의 사용자 지정 하위 도메인입니다. |
| content | 콘텐츠 | 몰입형 리더 표시할 내용이 들어 있는 개체입니다. |
| options | 옵션 | 몰입형 리더 특정 동작을 구성하는 옵션입니다. 선택 사항. |
반품
몰입형 리더 로드될 때 확인되는 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 | 번호 | 처리된 총 문자 수 |
Error
오류에 대한 정보를 포함합니다.
{
code: string;
message: string;
}
| 매개 변수 | 형식 | 설명 |
|---|---|---|
| 코드 | 문자열 | 오류 코드 집합 중 하나입니다. |
| message | 문자열 | 사람이 읽을 수 있는 오류 표현입니다. |
| 오류 코드 | 설명 |
|---|---|
| BadArgument | 제공된 인수가 잘못되었습니다. 오류의 매개 변수를 참조 message 하세요. |
| 시간 제한 | 지정된 시간 제한 내에 몰입형 리더 로드하지 못했습니다. |
| TokenExpired | 제공된 토큰이 만료되었습니다. |
| 정체됨 | 호출 속도 제한을 초과했습니다. |
유형
콘텐츠
몰입형 리더 표시할 콘텐츠를 포함합니다.
{
title?: string;
chunks: Chunk[];
}
| 매개 변수 | 형식 | 설명 |
|---|---|---|
| 제목 | 문자열 | 몰입형 리더 맨 위에 표시된 제목 텍스트(선택 사항) |
| 청크 | 청크[] | 청크 배열 |
title
Type: String
Required: false
Default value: "Immersive Reader"
chunks
Type: Chunk[]
Required: true
Default value: null
청크
몰입형 리더 콘텐츠에 전달되는 단일 데이터 청크입니다.
{
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)입니다. 지정하지 않으면 기본적으로 브라우저 언어로 설정됩니다. |
| 시간 제한 | number | launchAsync에서 시간 제한 오류가 발생하기 전까지의 기간(밀리초)입니다(기본값: 15000ms). 이 시간 제한은 리더 페이지가 성공적으로 열리고 회전자가 시작되면 리더 페이지의 초기 시작에만 적용됩니다. 시간 제한을 조정할 필요가 없습니다. |
| uiZIndex | number | 생성된 HTML iframe 요소의 Z 인덱스입니다(기본값은 1000). |
| useWebview | Boolean | Chrome Apps와의 호환성을 위해 HTML iframe 요소 대신 웹 보기 태그를 사용합니다(기본값은 false). |
| onExit | 함수 | 몰입형 리더가 종료될 때 실행됩니다. |
| customDomain | 문자열 | 내부용으로 예약되어 있습니다. 몰입형 리더 웹앱이 호스트되는 사용자 지정 도메인입니다(기본값은 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 | 문자열 | 음성, 여성 또는 남성 중 하나. 모든 언어가 두 성을 모두 지원하는 것은 아닙니다. |
| 속도 | number | 재생 속도. 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 | number | 선택한 텍스트 크기를 설정합니다. |
| 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 | number | 선택한 텍스트 크기를 설정합니다. |
| fontFamily | 문자열 | 선택한 글꼴(Calibri, ComicSans 또는 Sitka)을 설정합니다. |
| textSpacing | number | 텍스트 간격을 설정/해제할지 여부를 설정합니다. |
| 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