chrome.input.ime

חשוב: ממשק ה-API הזה פועל רק ב-ChromeOS.

תיאור

אפשר להשתמש ב-chrome.input.ime API כדי להטמיע IME מותאם אישית ב-ChromeOS. כך התוסף יכול לטפל בהקשות, להגדיר את ההרכב ולנהל את חלון האפשרויות.

הרשאות

input

כדי להשתמש ב-input.ime API, צריך להצהיר על ההרשאה input במניפסט התוסף. לדוגמה:

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

זמינות

ל-ChromeOS בלבד

דוגמאות

הקוד הבא יוצר IME שממיר אותיות מוקלדות לאותיות רישיות.

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;
    }
  }
);

סוגים

AssistiveWindowButton

‫Chrome 85 ואילך

מזהה של לחצנים בחלון של הטכנולוגיה המסייעת.

Enum

‫"undo"

‫"addToDictionary"

AssistiveWindowProperties

‫Chrome 85 ואילך

מאפיינים של חלון העזרה.

מאפיינים

• announceString

  מחרוזת אופציונלי

  מחרוזות ש-ChromeVox יקריא.

• סוג

  ‫"undo"
  

• גלוי

  בוליאני

  הגדרה ל-True תציג את AssistiveWindow, הגדרה ל-False תסתיר אותו.

AssistiveWindowType

‫Chrome 85 ואילך

סוג חלון העזרה.

ערך

‫"undo"

AutoCapitalizeType

‫Chrome 69 ואילך

סוג השימוש האוטומטי באותיות רישיות בשדה הטקסט.

Enum

‫'characters'

‫"words"

‫"sentences"

InputContext

מתאר הקשר של קלט

מאפיינים

• autoCapitalize

  AutoCapitalizeType

  ‫Chrome 69 ואילך

  סוג השימוש האוטומטי באותיות רישיות בשדה הטקסט.

• autoComplete

  בוליאני

  האם שדה הטקסט רוצה השלמה אוטומטית.

• autoCorrect

  בוליאני

  אם שדה הטקסט צריך תיקון אוטומטי.

• contextID

  number

  המאפיין הזה משמש לציון יעדים של פעולות בשדה טקסט. המזהה הזה הופך ללא תקף ברגע שמתבצעת קריאה ל-onBlur.

• shouldDoLearning

  בוליאני

  ‫Chrome 68 ואילך

  האם הטקסט שמוזן בשדה הטקסט צריך לשמש לשיפור ההצעות להקלדה עבור המשתמש.

• spellCheck

  בוליאני

  האם שדה הטקסט צריך בדיקת איות.

• סוג

  InputContextType

  סוג הערך ששדה הטקסט הזה עורך (טקסט, מספר, כתובת URL וכו')

InputContextType

‫Chrome 44 ואילך

סוג הערך ששדה הטקסט הזה עורך (טקסט, מספר, כתובת URL וכו')

Enum

‫"text"

"search"

‎"tel"

"url"

‫"email"

‎"number"

"password"

"null"

KeyboardEvent

מידע נוסף זמין בכתובת http://www.w3.org/TR/DOM-Level-3-Events/#events-KeyboardEvent

מאפיינים

• altKey

  boolean אופציונלי

  אם מקש ALT נלחץ או לא.

• altgrKey

  boolean אופציונלי

  ‫Chrome 79 ואילך

  אם מקש ALTGR נלחץ או לא.

• capsLock

  boolean אופציונלי

  האם CAPS_LOCK מופעל.

• קוד

  מחרוזת

  הערך של המקש הפיזי שנלחץ. הערך לא מושפע מפריסת המקלדת הנוכחית או ממצב המקש לשינוי.

• ctrlKey

  boolean אופציונלי

  האם מקש ה-CTRL נלחץ או לא.

• extensionId

  מחרוזת אופציונלי

  מזהה התוסף של השולח של אירוע המקשים הזה.

• מקש

  מחרוזת

  הערך של המקש שנלחץ

• keyCode

  מספר אופציונלי

  המאפיין keyCode ב-HTML שיצא משימוש, שהוא קוד מספרי שתלוי במערכת וביישום ומציין את המזהה הלא משונה שמשויך למקש שנלחץ.

• requestId

  מחרוזת אופציונלי

  (הוצא משימוש) מזהה הבקשה. במקום זאת, צריך להשתמש בפרמטר requestId מהאירוע onKeyEvent.

• shiftKey

  boolean אופציונלי

  אם מקש ה-SHIFT לחוץ או לא.

• סוג

  KeyboardEventType

  אחד מהאירועים keyup או keydown.

KeyboardEventType

‫Chrome 44 ואילך

Enum

‪"keyup"

‎"keydown"

MenuItem

פריט בתפריט שמשמש שיטת קלט כדי לקיים אינטראקציה עם המשתמש מתפריט השפה.

מאפיינים

• בוצע סימון

  boolean אופציונלי

  מציין שצריך לצייר את הפריט הזה עם סימן וי.

• פעיל

  boolean אופציונלי

  מציין שהפריט הזה מופעל.

• id [מזהה]

  מחרוזת

  מחרוזת שתועבר לקריאות חוזרות (callback) שמפנות ל-MenuItem הזה.

• תווית

  מחרוזת אופציונלי

  הטקסט שמוצג בתפריט עבור הפריט הזה.

• סגנון

  ‫MenuItemStyle אופציונלי

  סוג הפריט בתפריט.

• גלוי

  boolean אופציונלי

  מציין שהפריט הזה גלוי.

MenuItemStyle

‫Chrome 44 ואילך

סוג הפריט בתפריט. כפתורי בחירה בין מפרידים נחשבים לקבוצה.

Enum

"check"

‫"radio"

‎"separator"

MenuParameters

‫Chrome 88 ואילך

מאפיינים

• engineID

  מחרוזת

  המזהה של המנוע שבו רוצים להשתמש.

• פריטים

  MenuItem[]

  פריטים בתפריט שרוצים להוסיף או לעדכן. הם יתווספו לפי הסדר שבו הם מופיעים במערך.

MouseButton

‫Chrome 44 ואילך

כפתורי העכבר שנלחצו.

Enum

"left"

‎"middle"‎

"right"

ScreenType

‫Chrome 44 ואילך

סוג המסך שבו מופעל ה-IME.

Enum

"normal"

‎"login"

"lock"

‫"secondary-login"

UnderlineStyle

‫Chrome 44 ואילך

סוג הקו התחתון שרוצים לשנות בפלח הזה.

Enum

‫"underline"

"doubleUnderline"

‫"noUnderline"

WindowPosition

‫Chrome 44 ואילך

איפה להציג את חלון המועמדים. אם ההגדרה היא 'סמן', החלון עוקב אחרי הסמן. אם המדיניות מוגדרת כ-'composition', החלון נעול לתחילת ההרכב.

Enum

‫"cursor"

‫'composition'

Methods

clearComposition()

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

ניקוי ההרכב הנוכחי. הפעולה תיכשל אם התוסף הזה לא בבעלות ה-IME הפעיל.

פרמטרים

• פרמטרים

  אובייקט

  • contextID

    number

    המזהה של ההקשר שבו יבוטל השילוב

החזרות

• Promise<boolean>

  ‫Chrome 111 ואילך

  הפונקציה מחזירה ערך בוליאני שמציין אם הטקסט התקבל או לא, כשהפעולה מסתיימת. אם הפעולה תיכשל, ההבטחה תידחה.

commitText()

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

מאשר את הטקסט שסופק לקלט הנוכחי.

פרמטרים

• פרמטרים

  אובייקט

  • contextID

    number

    המזהה של ההקשר שבו הטקסט יאושר

  • text

    מחרוזת

    הטקסט שרוצים להוסיף

החזרות

• Promise<boolean>

  ‫Chrome 111 ואילך

  הפונקציה מחזירה ערך בוליאני שמציין אם הטקסט התקבל או לא, כשהפעולה מסתיימת. אם הפעולה תיכשל, ההבטחה תידחה.

deleteSurroundingText()

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

מחיקת הטקסט מסביב לסמן.

פרמטרים

• פרמטרים

  אובייקט

  • contextID

    number

    המזהה של ההקשר שבו הטקסט שמסביב יימחק.

  • engineID

    מחרוזת

    המזהה של המנוע שמקבל את האירוע.

  • length

    number

    מספר התווים שצריך למחוק

  • היסט

    number

    ההיסט ממיקום הסמן שבו תתחיל המחיקה. הערך הזה יכול להיות שלילי.

החזרות

• Promise<void>

  ‫Chrome 111 ואילך

  ההבטחה ממומשת כשהפעולה מסתיימת.

hideInputView()

chrome.input.ime.hideInputView(): void

הסתרת חלון תצוגת הקלט, שמופיע אוטומטית במערכת. אם חלון תצוגת הקלט כבר מוסתר, הפונקציה הזו לא תעשה כלום.

keyEventHandled()

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

מציין שהאירוע המרכזי שהתקבל על ידי onKeyEvent מטופל. אפשר להפעיל אותה רק אם מאזין האירועים onKeyEvent הוא אסינכרוני.

פרמטרים

• requestId

  מחרוזת

  מזהה הבקשה של האירוע שטופל. הערך הזה צריך להגיע מ-keyEvent.requestId

• תשובה

  בוליאני

  אם הלחיצה על המקש טופלה, התנאי מתקיים. אם לא, התנאי לא מתקיים

sendKeyEvents()

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

שליחת האירועים המרכזיים. הפונקציה הזו מיועדת לשימוש במקלדות וירטואליות. כשמשתמש לוחץ על מקש או מקשים במקלדת וירטואלית, הפונקציה הזו משמשת להפצת האירוע הזה למערכת.

פרמטרים

• פרמטרים

  אובייקט

  • contextID

    number

    המזהה של ההקשר שבו יישלחו האירועים המרכזיים, או אפס כדי לשלוח אירועים מרכזיים לשדה שאינו שדה קלט.

  • keyData

    ‫KeyboardEvent[]

    נתונים על האירוע המרכזי.

החזרות

• Promise<void>

  ‫Chrome 111 ואילך

  ההבטחה ממומשת כשהפעולה מסתיימת.

setAssistiveWindowButtonHighlighted()

‫Chrome 86 ואילך

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

הדגשה או ביטול הדגשה של לחצן בחלון עזר.

פרמטרים

• פרמטרים

  אובייקט

  • announceString

    מחרוזת אופציונלי

    הטקסט שקורא המסך יקריא.

  • buttonID

    AssistiveWindowButton

    המזהה של הלחצן

  • contextID

    number

    המזהה של ההקשר שאליו שייך חלון העזרה.

  • מודגש

    בוליאני

    האם להדגיש את הלחצן.

  • windowType

    ‫"undo"
    

    סוג החלון שאליו הכפתור שייך.

החזרות

• Promise<void>

  ‫Chrome 111 ואילך

  ההבטחה ממומשת כשהפעולה מסתיימת. אם הפעולה תיכשל, ההבטחה תידחה.

setAssistiveWindowProperties()

‫Chrome 85 ואילך

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

הפונקציה מציגה או מסתירה חלון עזר עם המאפיינים שצוינו.

פרמטרים

• פרמטרים

  אובייקט

  • contextID

    number

    המזהה של ההקשר שאליו שייך חלון העזרה.

  • נכסים

    AssistiveWindowProperties

    מאפיינים של חלון העזרה.

החזרות

• Promise<boolean>

  ‫Chrome 111 ואילך

  ההבטחה ממומשת כשהפעולה מסתיימת.

setCandidates()

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

מגדיר את רשימת המועמדים הנוכחית. הפעולה תיכשל אם התוסף הזה לא בבעלות של ה-IME הפעיל

פרמטרים

• פרמטרים

  אובייקט

  • מועמדים

    object[]

    רשימת המועמדים שיוצגו בחלון המועמדים

    • אנוטציה

      מחרוזת אופציונלי

      טקסט נוסף שמתאר את המועמד

    • שילוב אפשרי למיקוד

      מחרוזת

      המועמד

    • id [מזהה]

      number

      מזהה המועמד

    • תווית

      מחרוזת אופציונלי

      מחרוזת קצרה שמוצגת ליד המועמד, לרוב מקש הקיצור או האינדקס

    • parentId

      מספר אופציונלי

      המזהה שאליו רוצים להוסיף את המועמדים האלה

    • שימוש

      אובייקט אופציונלי

      השימוש או התיאור המפורט של המילה.

      • body

        מחרוזת

        מחרוזת הגוף של התיאור המפורט.

      • title

        מחרוזת

        מחרוזת השם של תיאור הפרטים.

  • contextID

    number

    המזהה של ההקשר שבבעלותו חלון המועמדים.

החזרות

• Promise<boolean>

  ‫Chrome 111 ואילך

  ההבטחה ממומשת כשהפעולה מסתיימת.

setCandidateWindowProperties()

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

הגדרת המאפיינים של חלון המועמדים. הפעולה תיכשל אם התוסף לא יהיה הבעלים של ה-IME הפעיל

פרמטרים

• פרמטרים

  אובייקט

  • engineID

    מחרוזת

    המזהה של המנוע שרוצים להגדיר בו מאפיינים.

  • נכסים

    אובייקט

    • auxiliaryText

      מחרוזת אופציונלי

      הטקסט שמוצג בחלק התחתון של חלון המועמד.

    • auxiliaryTextVisible

      boolean אופציונלי

      הערך True יציג את הטקסט המשני, והערך False יסתיר אותו.

    • currentCandidateIndex

      מספר אופציונלי

      ‫Chrome 84 ואילך

      האינדקס של המועמד הנוכחי שנבחר מתוך סך המועמדים.

    • cursorVisible

      boolean אופציונלי

      הערך True אם רוצים להציג את הסמן, הערך False אם רוצים להסתיר אותו.

    • pageSize

      מספר אופציונלי

      מספר המועמדים שיוצגו בכל דף.

    • totalCandidates

      מספר אופציונלי

      ‫Chrome 84 ואילך

      המספר הכולל של המועמדים בחלון המועמדים.

    • לאורך

      boolean אופציונלי

      אם חלון המועמדים צריך להיות מוצג בצורה אנכית, הערך הוא True. אם הוא צריך להיות מוצג בצורה אופקית, הערך הוא False.

    • גלוי

      boolean אופציונלי

      הערך True כדי להציג את חלון המועמדים, הערך False כדי להסתיר אותו.

    • windowPosition

      ‫WindowPosition אופציונלי

      איפה להציג את חלון המועמדים.

החזרות

• Promise<boolean>

  ‫Chrome 111 ואילך

  ההבטחה ממומשת כשהפעולה מסתיימת.

setComposition()

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

הגדרת הקומפוזיציה הנוכחית. הפעולה תיכשל אם התוסף הזה לא בבעלות ה-IME הפעיל.

פרמטרים

• פרמטרים

  אובייקט

  • contextID

    number

    המזהה של ההקשר שבו יוגדר טקסט היצירה

  • סמן

    number

    המיקום בטקסט של הסמן.

  • פלחים

    ‫object[] אופציונלי

    רשימה של פילוחים והסוגים המשויכים שלהם.

    • End

      number

      אינדקס של התו שאחריו צריך לסיים את המקטע הזה.

    • start

      number

      האינדקס של התו שבו מתחיל הקטע הזה

    • סגנון

      UnderlineStyle

      סוג הקו התחתון שרוצים לשנות בפלח הזה.

  • selectionEnd

    מספר אופציונלי

    המיקום בטקסט שבו מסתיימת הבחירה.

  • selectionStart

    מספר אופציונלי

    המיקום בטקסט שבו מתחילה הבחירה.

  • text

    מחרוזת

    הטקסט להגדרה

החזרות

• Promise<boolean>

  ‫Chrome 111 ואילך

  הפונקציה מחזירה ערך בוליאני שמציין אם הטקסט התקבל או לא, כשהפעולה מסתיימת. אם הפעולה תיכשל, ההבטחה תידחה.

setCursorPosition()

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

מגדירים את מיקום הסמן בחלון המועמדים. אם התוסף הזה לא בבעלות של ה-IME הפעיל, הפעולה הזו לא תבצע כלום.

פרמטרים

• פרמטרים

  אובייקט

  • candidateID

    number

    המזהה של המועמד שנבחר.

  • contextID

    number

    המזהה של ההקשר שבבעלותו חלון המועמדים.

החזרות

• Promise<boolean>

  ‫Chrome 111 ואילך

  ההבטחה מסתיימת כשהפעולה מסתיימת

setMenuItems()

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

הוספת פריטים לתפריט השפה כשמפעילים את ה-IME הזה.

פרמטרים

• פרמטרים

  MenuParameters

החזרות

• Promise<void>

  ‫Chrome 111 ואילך

updateMenuItems()

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

מעדכנים את המצב של פריטי התפריט שצוינו

פרמטרים

• פרמטרים

  MenuParameters

החזרות

• Promise<void>

  ‫Chrome 111 ואילך

  ההבטחה מסתיימת כשהפעולה מסתיימת

אירועים

onActivate

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

האירוע הזה נשלח כשמפעילים IME. הוא מציין שממשק ה-IME יקבל אירועים מסוג onKeyPress.

פרמטרים

• callback

  פונקציה

  הפרמטר callback נראה כך:

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

  • engineID

    מחרוזת

  • סינון שיחות

    ScreenType

onAssistiveWindowButtonClicked

‫Chrome 85 ואילך

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

האירוע הזה נשלח כשלוחצים על לחצן בחלון של תכונת נגישות.

פרמטרים

• callback

  פונקציה

  הפרמטר callback נראה כך:

  (details: object) => void

  • פרטים

    אובייקט

    • buttonID

      AssistiveWindowButton

      המזהה של הלחצן שעליו לחצו.

    • windowType

      AssistiveWindowType

      סוג חלון העזרה.

onBlur

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

האירוע הזה נשלח כשהפוקוס עובר מתיבת טקסט. היא נשלחת לכל התוספים שמקשיבים לאירוע הזה ושהמשתמש הפעיל.

פרמטרים

• callback

  פונקציה

  הפרמטר callback נראה כך:

  (contextID: number) => void

  • contextID

    number

onCandidateClicked

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

האירוע הזה נשלח אם התוסף הזה הוא הבעלים של ה-IME הפעיל.

פרמטרים

• callback

  פונקציה

  הפרמטר callback נראה כך:

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

  • engineID

    מחרוזת

  • candidateID

    number

  • כפתור

    MouseButton

onDeactivated

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

האירוע הזה נשלח כשמשביתים את ה-IME. הוא מציין שממשק ה-IME לא יקבל יותר אירועי onKeyPress.

פרמטרים

• callback

  פונקציה

  הפרמטר callback נראה כך:

  (engineID: string) => void

  • engineID

    מחרוזת

onFocus

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

האירוע הזה נשלח כשמועבר מיקוד לתיבת טקסט. היא נשלחת לכל התוספים שמקשיבים לאירוע הזה ושהמשתמש הפעיל.

פרמטרים

• callback

  פונקציה

  הפרמטר callback נראה כך:

  (context: InputContext) => void

  • הקשר

    InputContext

onInputContextUpdate

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

האירוע הזה נשלח כשמאפייני InputContext הנוכחי משתנים, כמו הסוג. היא נשלחת לכל התוספים שמקשיבים לאירוע הזה ושהמשתמש הפעיל.

פרמטרים

• callback

  פונקציה

  הפרמטר callback נראה כך:

  (context: InputContext) => void

  • הקשר

    InputContext

onKeyEvent

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

מופעל כשאירוע מרכזי נשלח ממערכת ההפעלה. האירוע יישלח לתוסף אם התוסף הזה הוא הבעלים של ה-IME הפעיל. פונקציית ה-listener צריכה להחזיר true אם האירוע טופל, ו-false אם הוא לא טופל. אם האירוע יוערך באופן אסינכרוני, הפונקציה הזו תחזיר undefined, ובהמשך ה-IME יצטרך לקרוא ל-keyEventHandled() עם התוצאה.

פרמטרים

• callback

  פונקציה

  הפרמטר callback נראה כך:

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

  • engineID

    מחרוזת

  • keyData

    KeyboardEvent

  • requestId

    מחרוזת

  • החזרות

    boolean | undefined

onMenuItemActivated

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

מופעל כשמשתמש בוחר פריט בתפריט

פרמטרים

• callback

  פונקציה

  הפרמטר callback נראה כך:

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

  • engineID

    מחרוזת

  • שם

    מחרוזת

onReset

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

האירוע הזה נשלח כש-Chrome מסיים סשן פעיל של הזנת טקסט.

פרמטרים

• callback

  פונקציה

  הפרמטר callback נראה כך:

  (engineID: string) => void

  • engineID

    מחרוזת

onSurroundingTextChanged

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

הפונקציה מופעלת כשמחרוזת הטקסט שניתנת לעריכה מסביב למיקום הסמן משתנה, או כשמיקום הסמן משתנה. אורך הטקסט מוגבל ל-100 תווים לכל כיוון של שיחה.

פרמטרים

• callback

  פונקציה

  הפרמטר callback נראה כך:

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

  • engineID

    מחרוזת

  • surroundingInfo

    אובייקט

    • עוגן

      number

      מיקום ההתחלה של הבחירה. הערך הזה מציין את מיקום הסמן אם לא נבחר טקסט.

    • מיקוד

      number

      מיקום הסיום של הבחירה. הערך הזה מציין את מיקום הסמן אם לא נבחר טקסט.

    • היסט

      number

      ‫Chrome 46 ואילך

      מיקום ההיסט של text. מכיוון שהשדה text כולל רק קבוצת משנה של הטקסט מסביב למיקום הסמן, הערך של offset מציין את המיקום המוחלט של התו הראשון בשדה text.

    • text

      מחרוזת

      הטקסט שמסביב לסמן. זהו רק חלק מהטקסט בשדה הקלט.