browser.input.ime

설명

chrome.input.ime API를 사용하여 Chrome OS용 맞춤 IME를 구현합니다. 이렇게 하면 확장 프로그램에서 키 입력을 처리하고, 컴포지션을 설정하고, 후보 창을 관리할 수 있습니다.

권한

input

input.ime API를 사용하려면 확장 프로그램 매니페스트에서 'input' 권한을 선언해야 합니다. 예를 들면 다음과 같습니다.

{
  "name": "My extension",
  ...
  "permissions": [
    "input"
  ],
  ...
}

가용성

ChromeOS만 해당

예

다음 코드는 입력된 문자를 대문자로 변환하는 IME를 만듭니다.

var context_id = -1;

browser.input.ime.onFocus.addListener(function(context) {
  context_id = context.contextID;
});

browser.input.ime.onKeyEvent.addListener(
  function(engineID, keyData) {
    if (keyData.type == "keydown" && keyData.key.match(/^[a-z]$/)) {
      browser.input.ime.commitText({"contextID": context_id,
                                    "text": keyData.key.toUpperCase()});
      return true;
    } else {
      return false;
    }
  }
);

유형

AssistiveWindowButton

Chrome 85 이상 브라우저.*(Chrome 148부터)

보조 창에 있는 버튼의 ID입니다.

열거형

"undo"

"addToDictionary"

AssistiveWindowProperties

Chrome 85 이상 브라우저.*(Chrome 148부터)

보조 창의 속성입니다.

속성

  • announceString

    문자열 선택사항

    ChromeVox에서 알릴 문자열입니다.

  • 유형

    "undo"

  • visible

    부울

    AssistiveWindow를 표시하려면 true로 설정하고 숨기려면 false로 설정합니다.

AssistiveWindowType

Chrome 85 이상 브라우저.*(Chrome 148부터)

보조 기간의 유형입니다.

값

"undo"

AutoCapitalizeType

Chrome 69 이상 브라우저.* Chrome 148부터

텍스트 필드의 자동 대문자 유형입니다.

열거형

"characters"

"words"

"sentences"

InputContext

입력 컨텍스트를 설명합니다.

속성

  • autoCapitalize
    Chrome 69 이상 브라우저.* Chrome 148부터

    텍스트 필드의 자동 대문자 유형입니다.

  • autoComplete

    부울

    텍스트 필드에서 자동 완성을 원하는지 여부입니다.

  • autoCorrect

    부울

    텍스트 필드에서 자동 수정을 원하는지 여부입니다.

  • contextID

    숫자

    텍스트 필드 작업의 타겟을 지정하는 데 사용됩니다. 이 ID는 onBlur가 호출되는 즉시 무효화됩니다.

  • shouldDoLearning

    부울

    Chrome 68 이상 브라우저.*(Chrome 148부터)

    텍스트 필드에 입력된 텍스트를 사용자의 입력 추천을 개선하는 데 사용할지 여부입니다.

  • spellCheck

    부울

    텍스트 필드에서 맞춤법 검사를 원하는지 여부입니다.

  • 이 텍스트 필드가 수정하는 값의 유형(텍스트, 숫자, URL 등)입니다.

InputContextType

Chrome 44 이상 브라우저.*(Chrome 148부터)

이 텍스트 필드가 수정하는 값의 유형(텍스트, 숫자, URL 등)입니다.

열거형

"text"

"search"

"tel"

"url"

"email"

"number"

"password"

"null"

KeyboardEvent

http://www.w3.org/TR/DOM-Level-3-Events/#events-KeyboardEvent를 참고하세요.

속성

  • altKey

    불리언 선택사항

    ALT 키를 눌렀는지 여부입니다.

  • altgrKey

    불리언 선택사항

    Chrome 79 이상 Chrome 148 이후 browser.*

    ALTGR 키를 눌렀는지 여부입니다.

  • capsLock

    불리언 선택사항

    CAPS_LOCK이 사용 설정되어 있는지 여부입니다.

  • 코드

    문자열

    눌린 물리적 키의 값입니다. 이 값은 현재 키보드 레이아웃이나 보조키 상태의 영향을 받지 않습니다.

  • ctrlKey

    불리언 선택사항

    Ctrl 키를 눌렀는지 여부입니다.

  • extensionId

    문자열 선택사항

    이 키 이벤트 발신자의 확장 프로그램 ID입니다.

  • 키

    문자열

    누른 키의 값

  • keyCode

    number 선택사항

    지원 중단된 HTML keyCode는 시스템 및 구현에 따라 달라지는 숫자 코드로, 누른 키와 연결된 수정되지 않은 식별자를 나타냅니다.

  • requestId

    문자열 선택사항

    (지원 중단됨) 요청 ID입니다. 대신 onKeyEvent 이벤트의 requestId 매개변수를 사용하세요.

  • shiftKey

    불리언 선택사항

    Shift 키를 눌렀는지 여부입니다.

  • keyup 또는 keydown 중 하나입니다.

KeyboardEventType

Chrome 44 이상 브라우저.*(Chrome 148부터)

열거형

'keyup'

"keydown"

MenuItem

언어 메뉴에서 사용자와 상호작용하기 위해 입력 방식에서 사용하는 메뉴 항목입니다.

속성

  • 선택됨

    불리언 선택사항

    이 항목을 체크표시와 함께 그려야 함을 나타냅니다.

  • 운영중

    불리언 선택사항

    이 항목이 사용 설정되어 있음을 나타냅니다.

  • id

    문자열

    이 MenuItem을 참조하는 콜백에 전달될 문자열입니다.

  • 라벨

    문자열 선택사항

    이 항목의 메뉴에 표시되는 텍스트입니다.

  • 스타일

    MenuItemStyle 선택사항

    메뉴 항목의 유형입니다.

  • visible

    불리언 선택사항

    이 항목이 표시됨을 나타냅니다.

MenuItemStyle

Chrome 44 이상 브라우저.*(Chrome 148부터)

메뉴 항목의 유형입니다. 구분자 사이에 있는 라디오 버튼은 그룹화된 것으로 간주됩니다.

열거형

'확인'

"radio"

"separator"

MenuParameters

Chrome 88 이상 브라우저(Chrome 148 이후).*

속성

  • engineID

    문자열

    사용할 엔진의 ID입니다.

  • 항목

    추가하거나 업데이트할 MenuItems입니다. 배열에 있는 순서대로 추가됩니다.

MouseButton

Chrome 44 이상 브라우저.*(Chrome 148부터)

클릭된 마우스 버튼입니다.

열거형

"left"

"middle"

"right"

ScreenType

Chrome 44 이상 브라우저.*(Chrome 148부터)

IME가 활성화되는 화면 유형입니다.

열거형

"normal"

"login"

"lock"

"secondary-login"

UnderlineStyle

Chrome 44 이상 브라우저.*(Chrome 148부터)

이 세그먼트를 수정할 밑줄 유형입니다.

열거형

"underline"

"doubleUnderline"

"noUnderline"

WindowPosition

Chrome 44 이상 브라우저.*(Chrome 148부터)

후보 창을 표시할 위치입니다. 'cursor'로 설정하면 창이 커서를 따라갑니다. 'composition'으로 설정하면 기간이 컴포지션 시작 부분으로 고정됩니다.

열거형

"cursor"

"composition"

메서드

clearComposition()

browser.input.ime.clearComposition(
  parameters: object,
)
: Promise<boolean>

현재 작성 중인 내용을 지웁니다. 이 확장 프로그램이 활성 IME를 소유하지 않으면 실패합니다.

매개변수

  • 매개변수

    객체

    • contextID

      숫자

      컴포지션이 삭제될 컨텍스트의 ID

반환 값

  • Promise<boolean>

    Chrome 111 이상 Chrome 148 이후 browser.*

    텍스트가 수락되었는지 여부를 나타내는 불리언과 함께 작업이 완료되면 확인됩니다. 실패하면 프로미스가 거부됩니다.

commitText()

browser.input.ime.commitText(
  parameters: object,
)
: Promise<boolean>

제공된 텍스트를 현재 입력에 커밋합니다.

매개변수

  • 매개변수

    객체

    • contextID

      숫자

      텍스트가 커밋될 컨텍스트의 ID입니다.

    • 텍스트

      문자열

      커밋할 텍스트

반환 값

  • Promise<boolean>

    Chrome 111 이상 Chrome 148 이후 browser.*

    텍스트가 수락되었는지 여부를 나타내는 불리언과 함께 작업이 완료되면 확인됩니다. 실패하면 프로미스가 거부됩니다.

deleteSurroundingText()

browser.input.ime.deleteSurroundingText(
  parameters: object,
)
: Promise<void>

캐럿 주변의 텍스트를 삭제합니다.

매개변수

  • 매개변수

    객체

    • contextID

      숫자

      주변 텍스트가 삭제될 컨텍스트의 ID입니다.

    • engineID

      문자열

      이벤트를 수신하는 엔진의 ID입니다.

    • 길이

      숫자

      삭제할 문자 수

    • 오프셋

      숫자

      삭제가 시작되는 캐럿 위치의 오프셋입니다. 이 값은 음수일 수 있습니다.

반환 값

  • 약속<void>

    Chrome 111 이상 Chrome 148 이후 browser.*

    작업이 완료되면 확인됩니다.

hideInputView()

browser.input.ime.hideInputView(): void

시스템에 의해 자동으로 표시되는 입력 뷰 창을 숨깁니다. 입력 뷰 창이 이미 숨겨져 있으면 이 함수는 아무 작업도 하지 않습니다.

keyEventHandled()

browser.input.ime.keyEventHandled(
  requestId: string,
  response: boolean,
)
: void

onKeyEvent에서 수신한 키 이벤트가 처리되었음을 나타냅니다. onKeyEvent 리스너가 비동기인 경우에만 호출해야 합니다.

매개변수

  • requestId

    문자열

    처리된 이벤트의 요청 ID입니다. keyEvent.requestId에서 가져와야 합니다.

  • 응답

    부울

    키 입력이 처리된 경우 true, 그렇지 않은 경우 false입니다.

sendKeyEvents()

browser.input.ime.sendKeyEvents(
  parameters: object,
)
: Promise<void>

주요 이벤트를 전송합니다. 이 함수는 가상 키보드에서 사용될 것으로 예상됩니다. 사용자가 가상 키보드의 키를 누르면 이 함수가 이벤트를 시스템에 전파하는 데 사용됩니다.

매개변수

  • 매개변수

    객체

    • contextID

      숫자

      주요 이벤트를 전송할 컨텍스트의 ID입니다. 입력란이 아닌 필드로 주요 이벤트를 전송하려면 0을 입력합니다.

    • keyData

      주요 이벤트에 관한 데이터입니다.

반환 값

  • 약속<void>

    Chrome 111 이상 Chrome 148 이후 browser.*

    작업이 완료되면 확인됩니다.

setAssistiveWindowButtonHighlighted()

Chrome 86 이상 Chrome 148 이후 browser.*
browser.input.ime.setAssistiveWindowButtonHighlighted(
  parameters: object,
)
: Promise<void>

보조 창에서 버튼을 강조 표시하거나 강조 표시를 해제합니다.

매개변수

  • 매개변수

    객체

    • announceString

      문자열 선택사항

      스크린 리더가 읽어주는 텍스트입니다.

    • 버튼의 ID입니다.

    • contextID

      숫자

      보조 창을 소유하는 컨텍스트의 ID입니다.

    • 눈에 띄는 채팅 메시지

      부울

      버튼을 강조 표시할지 여부입니다.

    • windowType

      "undo"

      버튼이 속한 창 유형입니다.

반환 값

  • 약속<void>

    Chrome 111 이상 Chrome 148 이후 browser.*

    작업이 완료되면 확인됩니다. 실패하면 프로미스가 거부됩니다.

setAssistiveWindowProperties()

Chrome 85 이상 브라우저.*(Chrome 148부터)
browser.input.ime.setAssistiveWindowProperties(
  parameters: object,
)
: Promise<boolean>

지정된 속성이 있는 보조 창을 표시하거나 숨깁니다.

매개변수

  • 매개변수

    객체

    • contextID

      숫자

      보조 창을 소유하는 컨텍스트의 ID입니다.

    • 보조 창의 속성입니다.

반환 값

  • Promise<boolean>

    Chrome 111 이상 Chrome 148 이후 browser.*

    작업이 완료되면 확인됩니다.

setCandidates()

browser.input.ime.setCandidates(
  parameters: object,
)
: Promise<boolean>

현재 후보 목록을 설정합니다. 이 확장 프로그램이 활성 IME를 소유하지 않으면 실패합니다.

매개변수

  • 매개변수

    객체

    • 후보

      object[]

      후보 창에 표시할 후보 목록

      • annotation

        문자열 선택사항

        후보를 설명하는 추가 텍스트

      • 조합

        문자열

        후보자

      • id

        숫자

        후보의 ID

      • 라벨

        문자열 선택사항

        후보 옆에 표시되는 짧은 문자열로, 주로 단축키 또는 색인입니다.

      • parentId

        number 선택사항

        이러한 후보를 추가할 ID

      • 사용량

        객체 선택사항

        단어의 사용법 또는 세부 설명입니다.

        • 본문

          문자열

          세부정보 설명의 본문 문자열입니다.

        • 제목

          문자열

          세부정보 설명의 제목 문자열입니다.

    • contextID

      숫자

      후보 창을 소유한 컨텍스트의 ID입니다.

반환 값

  • Promise<boolean>

    Chrome 111 이상 Chrome 148 이후 browser.*

    작업이 완료되면 확인됩니다.

setCandidateWindowProperties()

browser.input.ime.setCandidateWindowProperties(
  parameters: object,
)
: Promise<boolean>

후보 창의 속성을 설정합니다. 확장 프로그램이 활성 IME를 소유하지 않으면 실패합니다.

매개변수

  • 매개변수

    객체

    • engineID

      문자열

      속성을 설정할 엔진의 ID입니다.

    • 속성

      객체

      • auxiliaryText

        문자열 선택사항

        후보 창 하단에 표시되는 텍스트입니다.

      • auxiliaryTextVisible

        불리언 선택사항

        보조 텍스트를 표시하려면 true, 숨기려면 false입니다.

      • currentCandidateIndex

        number 선택사항

        Chrome 84 이상 Chrome 148 이후 browser.*

        전체 후보 중 현재 선택된 후보의 색인입니다.

      • cursorVisible

        불리언 선택사항

        커서를 표시하려면 true, 숨기려면 false입니다.

      • pageSize

        number 선택사항

        페이지당 표시할 후보 수입니다.

      • totalCandidates

        number 선택사항

        Chrome 84 이상 Chrome 148 이후 browser.*

        후보 기간의 총 후보 수입니다.

      • 카테고리

        불리언 선택사항

        후보 창을 세로로 렌더링해야 하는 경우 true, 가로로 렌더링해야 하는 경우 false입니다.

      • visible

        불리언 선택사항

        후보 창을 표시하려면 true, 숨기려면 false입니다.

      • windowPosition

        WindowPosition 선택사항

        후보 창을 표시할 위치입니다.

반환 값

  • Promise<boolean>

    Chrome 111 이상 Chrome 148 이후 browser.*

    작업이 완료되면 확인됩니다.

setComposition()

browser.input.ime.setComposition(
  parameters: object,
)
: Promise<boolean>

현재 컴포지션을 설정합니다. 이 확장 프로그램이 활성 IME를 소유하지 않으면 실패합니다.

매개변수

  • 매개변수

    객체

    • contextID

      숫자

      작성 텍스트가 설정될 컨텍스트의 ID

    • cursor

      숫자

      커서의 텍스트 내 위치입니다.

    • 세그먼트

      object[] 선택사항

      세그먼트 및 관련 유형 목록입니다.

      • end

        숫자

        이 세그먼트를 종료할 문자의 색인입니다.

      • start

        숫자

        이 세그먼트를 시작할 문자의 색인

      • 스타일

        이 세그먼트를 수정할 밑줄 유형입니다.

    • selectionEnd

      number 선택사항

      선택이 끝나는 텍스트의 위치입니다.

    • selectionStart

      number 선택사항

      선택이 시작되는 텍스트의 위치입니다.

    • 텍스트

      문자열

      설정할 텍스트

반환 값

  • Promise<boolean>

    Chrome 111 이상 Chrome 148 이후 browser.*

    텍스트가 수락되었는지 여부를 나타내는 불리언과 함께 작업이 완료되면 확인됩니다. 실패하면 프로미스가 거부됩니다.

setCursorPosition()

browser.input.ime.setCursorPosition(
  parameters: object,
)
: Promise<boolean>

후보 창에서 커서의 위치를 설정합니다. 이 확장 프로그램이 활성 IME를 소유하지 않는 경우 이 작업은 실행되지 않습니다.

매개변수

  • 매개변수

    객체

    • candidateID

      숫자

      선택할 후보의 ID입니다.

    • contextID

      숫자

      후보 창을 소유한 컨텍스트의 ID입니다.

반환 값

  • Promise<boolean>

    Chrome 111 이상 Chrome 148 이후 browser.*

    작업이 완료되면 해결됩니다.

setMenuItems()

browser.input.ime.setMenuItems(
  parameters: MenuParameters,
)
: Promise<void>

이 IME가 활성 상태일 때 제공된 메뉴 항목을 언어 메뉴에 추가합니다.

매개변수

반환 값

  • 약속<void>

    Chrome 111 이상 Chrome 148 이후 browser.*

updateMenuItems()

browser.input.ime.updateMenuItems(
  parameters: MenuParameters,
)
: Promise<void>

지정된 MenuItems의 상태를 업데이트합니다.

매개변수

반환 값

  • 약속<void>

    Chrome 111 이상 Chrome 148 이후 browser.*

    작업이 완료되면 해결됩니다.

이벤트

onActivate

browser.input.ime.onActivate.addListener(
  callback: function,
)

이 이벤트는 IME가 활성화되면 전송됩니다. IME가 onKeyPress 이벤트를 수신할 것임을 알립니다.

매개변수

  • callback

    함수

    callback 매개변수는 다음과 같습니다.

    (engineID: string, screen: ScreenType) => void

onAssistiveWindowButtonClicked

Chrome 85 이상 브라우저.*(Chrome 148부터)
browser.input.ime.onAssistiveWindowButtonClicked.addListener(
  callback: function,
)

이 이벤트는 지원 창의 버튼을 클릭하면 전송됩니다.

매개변수

  • callback

    함수

    callback 매개변수는 다음과 같습니다.

    (details: object) => void

onBlur

browser.input.ime.onBlur.addListener(
  callback: function,
)

이 이벤트는 포커스가 텍스트 상자를 벗어날 때 전송됩니다. 이 이벤트를 수신 대기하고 사용자가 사용 설정한 모든 확장 프로그램에 전송됩니다.

매개변수

  • callback

    함수

    callback 매개변수는 다음과 같습니다.

    (contextID: number) => void

    • contextID

      숫자

onCandidateClicked

browser.input.ime.onCandidateClicked.addListener(
  callback: function,
)

이 이벤트는 이 확장 프로그램이 활성 IME를 소유하는 경우 전송됩니다.

매개변수

  • callback

    함수

    callback 매개변수는 다음과 같습니다.

    (engineID: string, candidateID: number, button: MouseButton) => void

    • engineID

      문자열

    • candidateID

      숫자

    • 버튼

onDeactivated

browser.input.ime.onDeactivated.addListener(
  callback: function,
)

이 이벤트는 IME가 비활성화되면 전송됩니다. IME가 더 이상 onKeyPress 이벤트를 수신하지 않음을 나타냅니다.

매개변수

  • callback

    함수

    callback 매개변수는 다음과 같습니다.

    (engineID: string) => void

    • engineID

      문자열

onFocus

browser.input.ime.onFocus.addListener(
  callback: function,
)

이 이벤트는 포커스가 텍스트 상자에 들어갈 때 전송됩니다. 이 이벤트를 수신 대기하고 사용자가 사용 설정한 모든 확장 프로그램에 전송됩니다.

매개변수

  • callback

    함수

    callback 매개변수는 다음과 같습니다.

    (context: InputContext) => void

onInputContextUpdate

browser.input.ime.onInputContextUpdate.addListener(
  callback: function,
)

이 이벤트는 현재 InputContext의 속성(예: 유형)이 변경될 때 전송됩니다. 이 이벤트를 수신 대기하고 사용자가 사용 설정한 모든 확장 프로그램에 전송됩니다.

매개변수

  • callback

    함수

    callback 매개변수는 다음과 같습니다.

    (context: InputContext) => void

onKeyEvent

browser.input.ime.onKeyEvent.addListener(
  callback: function,
)

운영체제에서 키 이벤트가 전송될 때 실행됩니다. 이 확장 프로그램이 활성 IME를 소유한 경우 이벤트가 확장 프로그램으로 전송됩니다. 리스너 함수는 이벤트가 처리된 경우 true를 반환하고 처리되지 않은 경우 false를 반환해야 합니다. 이벤트가 비동기식으로 평가되는 경우 이 함수는 정의되지 않은 값을 반환해야 하며 IME는 나중에 결과와 함께 keyEventHandled()를 호출해야 합니다.

매개변수

  • callback

    함수

    callback 매개변수는 다음과 같습니다.

    (engineID: string, keyData: KeyboardEvent, requestId: string) => boolean | undefined

    • returns

      boolean | undefined

onMenuItemActivated

browser.input.ime.onMenuItemActivated.addListener(
  callback: function,
)

사용자가 메뉴 항목을 선택할 때 호출됩니다.

매개변수

  • callback

    함수

    callback 매개변수는 다음과 같습니다.

    (engineID: string, name: string) => void

    • engineID

      문자열

    • name

      문자열

onReset

browser.input.ime.onReset.addListener(
  callback: function,
)

이 이벤트는 Chrome에서 진행 중인 텍스트 입력 세션을 종료할 때 전송됩니다.

매개변수

  • callback

    함수

    callback 매개변수는 다음과 같습니다.

    (engineID: string) => void

    • engineID

      문자열

onSurroundingTextChanged

browser.input.ime.onSurroundingTextChanged.addListener(
  callback: function,
)

캐럿 주변의 수정 가능한 문자열이 변경되거나 캐럿 위치가 이동될 때 호출됩니다. 텍스트 길이는 각 방향으로 100자(영문 기준)로 제한됩니다.

매개변수

  • callback

    함수

    callback 매개변수는 다음과 같습니다.

    (engineID: string, surroundingInfo: object) => void

    • engineID

      문자열

    • surroundingInfo

      객체

      • 앵커

        숫자

        선택 영역의 시작 위치입니다. 이 값은 선택 항목이 없는 경우 캐럿 위치를 나타냅니다.

      • 포커스

        숫자

        선택의 종료 위치입니다. 이 값은 선택 항목이 없는 경우 캐럿 위치를 나타냅니다.

      • 오프셋

        숫자

        Chrome 46 이상 Chrome 148 이후 browser.*

        text의 오프셋 위치입니다. text에는 커서 주변의 텍스트 하위 집합만 포함되므로 오프셋은 text의 첫 번째 문자의 절대 위치를 나타냅니다.

      • 텍스트

        문자열

        커서 주변의 텍스트입니다. 이는 입력 필드의 모든 텍스트 중 일부에 불과합니다.