chrome.input.ime

תיאור

משתמשים ב-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

‫Chrome 44 ואילך

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

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

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

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

  • requestId

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

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

  • shiftKey

    ‫boolean אופציונלי

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

  • אחד מהאירועים 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

  • תשובה

    בוליאני

    הערך True אם הלחיצה על המקש טופלה, הערך False אם לא

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

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

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

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

    • contextID

      number

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

    • מודגש

      בוליאני

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

    • windowType

      ‫"undo"

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

החזרות

  • Promise<void>

    ‫Chrome 111 ואילך

setAssistiveWindowProperties()

‫Chrome 85 ואילך 
chrome.input.ime.setAssistiveWindowProperties(
  parameters: object,
): Promise<boolean>

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

פרמטרים

  • פרמטרים

    אובייקט

    • contextID

      number

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

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

החזרות

  • 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

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

      • התחלה

        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 הזה.

פרמטרים

החזרות

  • Promise<void>

    ‫Chrome 111 ואילך

updateMenuItems()

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

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

פרמטרים

החזרות

  • 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

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,
)

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

פרמטרים

onInputContextUpdate

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

האירוע הזה נשלח כשמאפייני 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 כוללת רק קבוצת משנה של טקסט מסביב למיקום הסמן, ולכן ההיסט מציין את המיקום המוחלט של התו הראשון של text.

      • text

        מחרוזת

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