chrome.input.ime

Mô tả

Dùng API chrome.input.ime để triển khai một IME tuỳ chỉnh cho ChromeOS. Điều này cho phép tiện ích của bạn xử lý các lần nhấn phím, đặt thành phần và quản lý cửa sổ đề xuất.

Quyền

input

Bạn phải khai báo quyền "input" trong tệp kê khai tiện ích để sử dụng API input.ime. Ví dụ:

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

Phạm vi cung cấp

Chỉ dành cho ChromeOS

Ví dụ

Đoạn mã sau đây tạo một IME chuyển đổi các chữ cái đã nhập thành chữ hoa.

var context_id = -1;

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

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

Loại

AssistiveWindowButton

Chrome 85 trở lên

Mã nhận dạng của các nút trong cửa sổ hỗ trợ.

Enum

"undo"

"addToDictionary"

AssistiveWindowProperties

Chrome 85 trở lên

Thuộc tính của cửa sổ hỗ trợ.

Thuộc tính

  • announceString

    chuỗi không bắt buộc

    Các chuỗi để ChromeVox thông báo.

  • loại

    "undo"

  • hiển thị

    boolean

    Đặt thành true để hiện AssistiveWindow, đặt thành false để ẩn.

AssistiveWindowType

Chrome 85 trở lên

Loại cửa sổ hỗ trợ.

Giá trị

"undo"

AutoCapitalizeType

Chrome 69 trở lên

Loại tự động viết hoa của trường văn bản.

Enum

"characters"

"words"

"sentences"

InputContext

Mô tả một bối cảnh đầu vào

Thuộc tính

  • autoCapitalize

    AutoCapitalizeType

    Chrome 69 trở lên

    Loại tự động viết hoa của trường văn bản.

  • autoComplete

    boolean

    Trường văn bản có muốn tính năng tự động hoàn thành hay không.

  • autoCorrect

    boolean

    Trường văn bản có muốn tự động sửa lỗi hay không.

  • contextID

    số

    Tham số này dùng để chỉ định mục tiêu của các thao tác trên trường văn bản. Mã nhận dạng này sẽ không hợp lệ ngay khi onBlur được gọi.

  • shouldDoLearning

    boolean

    Chrome 68 trở lên

    Liệu văn bản đã nhập vào trường văn bản có được dùng để cải thiện các đề xuất nhập cho người dùng hay không.

  • spellCheck

    boolean

    Trường văn bản có muốn kiểm tra chính tả hay không.

  • Loại giá trị mà trường văn bản này chỉnh sửa (Văn bản, Số, URL, v.v.)

InputContextType

Chrome 44 trở lên

Loại giá trị mà trường văn bản này chỉnh sửa (Văn bản, Số, URL, v.v.)

Enum

"text"

"search"

"tel"

"url"

"email"

"number"

"password"

"null"

KeyboardEvent

Xem http://www.w3.org/TR/DOM-Level-3-Events/#events-KeyboardEvent

Thuộc tính

  • altKey

    boolean không bắt buộc

    Liệu bạn có nhấn phím ALT hay không.

  • altgrKey

    boolean không bắt buộc

    Chrome 79 trở lên

    Liệu phím ALTGR có được nhấn hay không.

  • capsLock

    boolean không bắt buộc

    CAPS_LOCK có được bật hay không.

  • mã

    chuỗi

    Giá trị của phím vật lý đang được nhấn. Giá trị này không bị ảnh hưởng bởi bố cục bàn phím hiện tại hoặc trạng thái của phím bổ trợ.

  • ctrlKey

    boolean không bắt buộc

    Liệu phím CTRL có được nhấn hay không.

  • extensionId

    chuỗi không bắt buộc

    Mã nhận dạng tiện ích của người gửi sự kiện khoá này.

  • phím

    chuỗi

    Giá trị của khoá đang được nhấn

  • keyCode

    number không bắt buộc

    keyCode HTML không dùng nữa, là mã số phụ thuộc vào hệ thống và quá trình triển khai, biểu thị giá trị nhận dạng chưa sửa đổi được liên kết với phím đã nhấn.

  • requestId

    chuỗi không bắt buộc

    (Không dùng nữa) Mã nhận dạng của yêu cầu. Thay vào đó, hãy sử dụng tham số requestId trong sự kiện onKeyEvent.

  • shiftKey

    boolean không bắt buộc

    Liệu bạn có nhấn phím SHIFT hay không.

  • Một trong các sự kiện keyup hoặc keydown.

KeyboardEventType

Chrome 44 trở lên

Enum

"keyup"

"keydown"

MenuItem

Một mục trong trình đơn mà phương thức nhập dùng để tương tác với người dùng trong trình đơn ngôn ngữ.

Thuộc tính

  • đã chọn

    boolean không bắt buộc

    Cho biết mục này sẽ được vẽ bằng dấu kiểm.

  • đang bật

    boolean không bắt buộc

    Cho biết mục này đã được bật.

  • id

    chuỗi

    Chuỗi sẽ được truyền đến các lệnh gọi lại tham chiếu MenuItem này.

  • nhãn

    chuỗi không bắt buộc

    Văn bản xuất hiện trong trình đơn cho mục này.

  • kiểu

    MenuItemStyle không bắt buộc

    Loại mục trong trình đơn.

  • hiển thị

    boolean không bắt buộc

    Cho biết mục này đang hiển thị.

MenuItemStyle

Chrome 44 trở lên

Loại mục trong trình đơn. Các nút chọn giữa các dấu phân cách được coi là được nhóm lại với nhau.

Enum

"check"

"radio"

"separator"

MenuParameters

Chrome 88 trở lên

Thuộc tính

  • engineID

    chuỗi

    Mã nhận dạng của công cụ cần sử dụng.

  • mục

    MenuItem[]

    MenuItems cần thêm hoặc cập nhật. Các giá trị này sẽ được thêm theo thứ tự xuất hiện trong mảng.

MouseButton

Chrome 44 trở lên

Nút chuột nào đã được nhấp.

Enum

"left"

"middle"

"right"

ScreenType

Chrome 44 trở lên

Loại màn hình mà IME được kích hoạt.

Enum

"normal"

"login"

"lock"

"secondary-login"

UnderlineStyle

Chrome 44 trở lên

Loại đường gạch chân cần sửa đổi đoạn này.

Enum

"underline"

"doubleUnderline"

"noUnderline"

WindowPosition

Chrome 44 trở lên

Vị trí hiển thị cửa sổ đề xuất. Nếu được đặt thành "cursor", cửa sổ sẽ theo con trỏ. Nếu được đặt thành "composition", cửa sổ sẽ bị khoá ở đầu thành phần.

Enum

"cursor"

"composition"

Phương thức

clearComposition()

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

Xoá thành phần hiện tại. Nếu tiện ích này không sở hữu IME đang hoạt động, thì thao tác này sẽ không thành công.

Thông số

  • tham số

    đối tượng

    • contextID

      số

      Mã nhận dạng của ngữ cảnh nơi thành phần sẽ bị xoá

Giá trị trả về

  • Promise<boolean>

    Chrome 111 trở lên

commitText()

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

Xác nhận văn bản đã cung cấp cho nội dung đầu vào hiện tại.

Thông số

  • tham số

    đối tượng

    • contextID

      số

      Mã nhận dạng của ngữ cảnh nơi văn bản sẽ được xác nhận

    • văn bản

      chuỗi

      Văn bản cần xác nhận

Giá trị trả về

  • Promise<boolean>

    Chrome 111 trở lên

deleteSurroundingText()

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

Xoá văn bản xung quanh dấu nháy.

Thông số

  • tham số

    đối tượng

    • contextID

      số

      Mã nhận dạng của ngữ cảnh mà văn bản xung quanh sẽ bị xoá.

    • engineID

      chuỗi

      Mã nhận dạng của công cụ nhận được sự kiện.

    • chiều dài

      số

      Số ký tự cần xoá

    • bù trừ

      số

      Độ lệch so với vị trí dấu nháy nơi sẽ bắt đầu xoá. Giá trị này có thể là số âm.

Giá trị trả về

  • Promise<void>

    Chrome 111 trở lên

hideInputView()

chrome.input.ime.hideInputView(): void

Ẩn cửa sổ khung hiển thị nhập, cửa sổ này sẽ tự động bật lên theo hệ thống. Nếu cửa sổ khung hiển thị đầu vào đã bị ẩn, thì hàm này sẽ không làm gì cả.

keyEventHandled()

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

Cho biết rằng sự kiện chính do onKeyEvent nhận được đã được xử lý. Bạn chỉ nên gọi phương thức này nếu trình nghe onKeyEvent là không đồng bộ.

Thông số

  • requestId

    chuỗi

    Mã yêu cầu của sự kiện đã được xử lý. Giá trị này phải đến từ keyEvent.requestId

  • phản hồi

    boolean

    True nếu tổ hợp phím đã được xử lý, false nếu chưa

sendKeyEvents()

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

Gửi sự kiện chính. Hàm này dự kiến sẽ được bàn phím ảo sử dụng. Khi người dùng nhấn(các) phím trên bàn phím ảo, hàm này được dùng để truyền sự kiện đó đến hệ thống.

Thông số

  • tham số

    đối tượng

    • contextID

      số

      Mã nhận dạng của bối cảnh mà các sự kiện chính sẽ được gửi hoặc bằng 0 để gửi các sự kiện chính đến trường không phải là trường nhập.

    • keyData

      KeyboardEvent[]

      Dữ liệu về sự kiện chính.

Giá trị trả về

  • Promise<void>

    Chrome 111 trở lên

setAssistiveWindowButtonHighlighted()

Chrome 86 trở lên 
chrome.input.ime.setAssistiveWindowButtonHighlighted(
  parameters: object,
): Promise<void>

Làm nổi bật/Huỷ làm nổi bật một nút trong cửa sổ hỗ trợ.

Thông số

  • tham số

    đối tượng

    • announceString

      chuỗi không bắt buộc

      Văn bản mà trình đọc màn hình sẽ thông báo.

    • Mã nhận dạng của nút

    • contextID

      số

      Mã nhận dạng của ngữ cảnh sở hữu cửa sổ hỗ trợ.

    • được làm nổi bật

      boolean

      Nút có nên được làm nổi bật hay không.

    • windowType

      "undo"

      Loại cửa sổ mà nút thuộc về.

Giá trị trả về

  • Promise<void>

    Chrome 111 trở lên

setAssistiveWindowProperties()

Chrome 85 trở lên 
chrome.input.ime.setAssistiveWindowProperties(
  parameters: object,
): Promise<boolean>

Hiện/Ẩn một cửa sổ hỗ trợ có các thuộc tính đã cho.

Thông số

  • tham số

    đối tượng

    • contextID

      số

      Mã nhận dạng của ngữ cảnh sở hữu cửa sổ hỗ trợ.

    • Thuộc tính của cửa sổ hỗ trợ.

Giá trị trả về

  • Promise<boolean>

    Chrome 111 trở lên

setCandidates()

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

Đặt danh sách đề xuất hiện tại. Thao tác này sẽ không thành công nếu tiện ích này không sở hữu IME đang hoạt động

Thông số

  • tham số

    đối tượng

    • đề xuất

      object[]

      Danh sách các đề xuất sẽ xuất hiện trong cửa sổ đề xuất

      • chú thích

        chuỗi không bắt buộc

        Văn bản bổ sung mô tả ứng cử viên

      • đề xuất

        chuỗi

        Ứng cử viên

      • id

        số

        Mã nhận dạng của đề xuất

      • nhãn

        chuỗi không bắt buộc

        Chuỗi ngắn xuất hiện bên cạnh đề xuất, thường là phím tắt hoặc chỉ mục

      • parentId

        number không bắt buộc

        Mã nhận dạng để thêm những đề xuất này vào

      • mức sử dụng

        đối tượng không bắt buộc

        Cách sử dụng hoặc nội dung mô tả chi tiết về từ.

        • body

          chuỗi

          Chuỗi nội dung của phần mô tả chi tiết.

        • tiêu đề

          chuỗi

          Chuỗi tiêu đề của nội dung mô tả chi tiết.

    • contextID

      số

      Mã nhận dạng của ngữ cảnh sở hữu cửa sổ đề xuất.

Giá trị trả về

  • Promise<boolean>

    Chrome 111 trở lên

setCandidateWindowProperties()

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

Đặt các thuộc tính của cửa sổ đề xuất. Thao tác này sẽ không thành công nếu tiện ích không sở hữu IME đang hoạt động

Thông số

  • tham số

    đối tượng

    • engineID

      chuỗi

      Mã nhận dạng của công cụ để đặt các thuộc tính.

    • tài sản

      đối tượng

      • auxiliaryText

        chuỗi không bắt buộc

        Văn bản xuất hiện ở cuối cửa sổ đề xuất.

      • auxiliaryTextVisible

        boolean không bắt buộc

        Đặt là true để hiển thị văn bản phụ, đặt là false để ẩn văn bản phụ.

      • currentCandidateIndex

        number không bắt buộc

        Chrome 84 trở lên

        Chỉ mục của ứng cử viên hiện được chọn trong tổng số ứng cử viên.

      • cursorVisible

        boolean không bắt buộc

        Đặt là true để hiện con trỏ, đặt là false để ẩn con trỏ.

      • pageSize

        number không bắt buộc

        Số lượng ứng viên để hiển thị trên mỗi trang.

      • totalCandidates

        number không bắt buộc

        Chrome 84 trở lên

        Tổng số ứng viên cho cửa sổ ứng viên.

      • ngành dọc

        boolean không bắt buộc

        True nếu cửa sổ đề xuất cần được hiển thị theo chiều dọc, false nếu bạn muốn hiển thị theo chiều ngang.

      • hiển thị

        boolean không bắt buộc

        Đặt thành true để hiện cửa sổ Đề xuất, đặt thành false để ẩn cửa sổ này.

      • windowPosition

        WindowPosition không bắt buộc

        Vị trí hiển thị cửa sổ đề xuất.

Giá trị trả về

  • Promise<boolean>

    Chrome 111 trở lên

setComposition()

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

Đặt thành phần hiện tại. Nếu tiện ích này không sở hữu IME đang hoạt động, thì thao tác này sẽ không thành công.

Thông số

  • tham số

    đối tượng

    • contextID

      số

      Mã của ngữ cảnh nơi văn bản thành phần sẽ được đặt

    • con trỏ

      số

      Vị trí của con trỏ trong văn bản.

    • phân đoạn

      object[] không bắt buộc

      Danh sách các phân khúc và loại được liên kết.

      • end

        số

        Chỉ mục của ký tự để kết thúc phân đoạn này.

      • bắt đầu

        số

        Chỉ mục của ký tự để bắt đầu phân đoạn này

      • Loại đường gạch chân cần sửa đổi đoạn này.

    • selectionEnd

      number không bắt buộc

      Vị trí trong văn bản mà lựa chọn kết thúc.

    • selectionStart

      number không bắt buộc

      Vị trí trong văn bản mà lựa chọn bắt đầu.

    • văn bản

      chuỗi

      Văn bản cần thiết lập

Giá trị trả về

  • Promise<boolean>

    Chrome 111 trở lên

setCursorPosition()

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

Đặt vị trí của con trỏ trong cửa sổ đề xuất. Đây là một thao tác không có hiệu lực nếu tiện ích này không sở hữu IME đang hoạt động.

Thông số

  • tham số

    đối tượng

    • candidateID

      số

      Mã nhận dạng của ứng cử viên cần chọn.

    • contextID

      số

      Mã nhận dạng của ngữ cảnh sở hữu cửa sổ đề xuất.

Giá trị trả về

  • Promise<boolean>

    Chrome 111 trở lên

setMenuItems()

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

Thêm các mục trình đơn được cung cấp vào trình đơn ngôn ngữ khi IME này đang hoạt động.

Thông số

Giá trị trả về

  • Promise<void>

    Chrome 111 trở lên

updateMenuItems()

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

Cập nhật trạng thái của các MenuItem được chỉ định

Thông số

Giá trị trả về

  • Promise<void>

    Chrome 111 trở lên

Sự kiện

onActivate

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

Sự kiện này được gửi khi một IME được kích hoạt. Điều này cho biết IME sẽ nhận được các sự kiện onKeyPress.

Thông số

  • callback

    hàm

    Tham số callback có dạng như sau: 

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

onAssistiveWindowButtonClicked

Chrome 85 trở lên 
chrome.input.ime.onAssistiveWindowButtonClicked.addListener(
  callback: function,
)

Sự kiện này được gửi khi người dùng nhấp vào một nút trong cửa sổ hỗ trợ.

Thông số

  • callback

    hàm

    Tham số callback có dạng như sau: 

    (details: object) => void

onBlur

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

Sự kiện này được gửi khi tiêu điểm rời khỏi một hộp văn bản. Thông báo này được gửi đến tất cả những tiện ích đang theo dõi sự kiện này và được người dùng bật.

Thông số

  • callback

    hàm

    Tham số callback có dạng như sau: 

    (contextID: number) => void

    • contextID

      số

onCandidateClicked

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

Sự kiện này được gửi nếu tiện ích này sở hữu IME đang hoạt động.

Thông số

  • callback

    hàm

    Tham số callback có dạng như sau: 

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

onDeactivated

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

Sự kiện này được gửi khi một IME bị vô hiệu hoá. Sự kiện này cho biết IME sẽ không nhận được các sự kiện onKeyPress nữa.

Thông số

  • callback

    hàm

    Tham số callback có dạng như sau: 

    (engineID: string) => void

    • engineID

      chuỗi

onFocus

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

Sự kiện này được gửi khi tiêu điểm đi vào một hộp văn bản. Thông báo này được gửi đến tất cả những tiện ích đang theo dõi sự kiện này và được người dùng bật.

Thông số

onInputContextUpdate

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

Sự kiện này được gửi khi các thuộc tính của InputContext hiện tại thay đổi, chẳng hạn như loại. Thông báo này được gửi đến tất cả những tiện ích đang theo dõi sự kiện này và được người dùng bật.

Thông số

onKeyEvent

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

Được kích hoạt khi một sự kiện nhấn phím được gửi từ hệ điều hành. Sự kiện sẽ được gửi đến tiện ích nếu tiện ích này sở hữu IME đang hoạt động. Hàm trình nghe sẽ trả về giá trị true nếu sự kiện đã được xử lý và trả về giá trị false nếu sự kiện chưa được xử lý. Nếu sự kiện sẽ được đánh giá không đồng bộ, thì hàm này phải trả về giá trị không xác định và IME phải gọi keyEventHandled() sau đó bằng kết quả.

Thông số

  • callback

    hàm

    Tham số callback có dạng như sau: 

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

    • returns

      boolean | undefined

onMenuItemActivated

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

Được gọi khi người dùng chọn một mục trong trình đơn

Thông số

  • callback

    hàm

    Tham số callback có dạng như sau: 

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

    • engineID

      chuỗi

    • tên

      chuỗi

onReset

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

Sự kiện này được gửi khi Chrome kết thúc phiên nhập văn bản đang diễn ra.

Thông số

  • callback

    hàm

    Tham số callback có dạng như sau: 

    (engineID: string) => void

    • engineID

      chuỗi

onSurroundingTextChanged

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

Được gọi khi chuỗi có thể chỉnh sửa xung quanh dấu nháy thay đổi hoặc khi vị trí dấu nháy được di chuyển. Độ dài văn bản tối đa là 100 ký tự cho mỗi hướng qua lại.

Thông số

  • callback

    hàm

    Tham số callback có dạng như sau: 

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

    • engineID

      chuỗi

    • surroundingInfo

      đối tượng

      • liên kết

        số

        Vị trí bắt đầu của vùng chọn. Giá trị này cho biết vị trí dấu nháy nếu không có lựa chọn nào.

      • tiêu điểm

        số

        Vị trí kết thúc của vùng chọn. Giá trị này cho biết vị trí dấu nháy nếu không có lựa chọn nào.

      • bù trừ

        số

        Chrome 46 trở lên

        Vị trí bù của text. Vì text chỉ bao gồm một tập hợp con của văn bản xung quanh con trỏ, nên độ lệch cho biết vị trí tuyệt đối của ký tự đầu tiên trong text.

      • văn bản

        chuỗi

        Văn bản quanh con trỏ. Đây chỉ là một phần của tất cả văn bản trong trường nhập.