自 2025 年 3 月 27 日起,我們建議您使用 android-latest-release
而非 aosp-main
建構及貢獻 AOSP。詳情請參閱「Android 開放原始碼計畫變更」。
輸入裝置設定檔
透過集合功能整理內容
你可以依據偏好儲存及分類內容。
輸入裝置設定檔 (.idc
檔案) 包含裝置專屬的設定屬性,這些屬性會影響輸入裝置的行為。
對於 HID 鍵盤和滑鼠等標準周邊裝置,輸入裝置設定檔通常不是必要的,因為預設的系統行為通常可確保這些裝置可立即使用。另一方面,內建嵌入式裝置 (尤其是觸控螢幕) 幾乎總是需要輸入裝置設定檔來指定行為。
原因
Android 會根據相關聯的 Linux 核心輸入裝置驅動程式回報的事件類型和屬性,自動偵測及設定大部分的輸入裝置功能。
舉例來說,如果輸入裝置支援 EV_REL
事件類型,並且程式碼為 REL_X
和 REL_Y
,以及 EV_KEY
事件類型和 BTN_MOUSE
,那麼 Android 就會將輸入裝置歸類為滑鼠。滑鼠的預設行為是顯示螢幕上的游標,以追蹤滑鼠的移動,並模擬滑鼠點擊時的觸碰動作。雖然滑鼠可以設定不同的設定,但對於標準滑鼠周邊裝置來說,預設行為通常就足夠了。
某些類別的輸入裝置則較為模糊。舉例來說,多點觸控螢幕和觸控板都支援 EV_ABS
事件類型,並且至少支援 ABS_MT_POSITION_X
和 ABS_MT_POSITION_Y
程式碼。不過,這些裝置的預期用途截然不同,因此無法一律自動判斷。此外,您還需要額外資訊,才能解讀觸控裝置回報的壓力和大小資訊。因此,觸控裝置 (尤其是內建觸控螢幕) 通常需要 IDC 檔案。
位置
輸入裝置設定檔會依 USB 供應商、產品 (和選版本) ID 或輸入裝置名稱來定位。
系統會依序查詢下列路徑。
/product/usr/idc/Vendor_XXXX_Product_XXXX_Version_XXXX.idc
/system_ext/usr/idc/Vendor_XXXX_Product_XXXX_Version_XXXX.idc
/odm/usr/idc/Vendor_XXXX_Product_XXXX_Version_XXXX.idc
/vendor/usr/idc/Vendor_XXXX_Product_XXXX_Version_XXXX.idc
/system/usr/idc/Vendor_XXXX_Product_XXXX_Version_XXXX.idc
/data/system/devices/idc/Vendor_XXXX_Product_XXXX_Version_XXXX.idc
/product/usr/idc/Vendor_XXXX_Product_XXXX.idc
/system_ext/usr/idc/Vendor_XXXX_Product_XXXX.idc
/odm/usr/idc/Vendor_XXXX_Product_XXXX.idc
/vendor/usr/idc/Vendor_XXXX_Product_XXXX.idc
/system/usr/idc/Vendor_XXXX_Product_XXXX.idc
/data/system/devices/idc/Vendor_XXXX_Product_XXXX.idc
/product/usr/idc/device-name.idc
/system_ext/usr/idc/device-name.idc
/odm/usr/idc/device-name.idc
/vendor/usr/idc/device-name.idc
/system/usr/idc/device-name.idc
/data/system/devices/idc/device-name.idc
建構含有裝置名稱的檔案路徑時,除了 '0'-'9'、'a'-'z'、'A'-'Z'、'-' 或 '_' 之外,裝置名稱中的所有字元都會替換為 '_'。
語法
輸入裝置設定檔是純文字檔案,內含屬性指派和註解。
屬性
屬性指派項目各包含屬性名稱、=
、屬性值和新行。如下所示:
property = value
屬性名稱是指空白文字常值。不得包含空白。輸入系統的每個元件都會定義一組用於設定其功能的屬性。
屬性值為非空白字串文字常值、整數或浮點數。不得包含空白字元或保留字元 \
或 "
。
屬性名稱和值會區分大小寫。
註解行以 '#' 開頭,並延伸至行尾。如下所示:
# A comment!
系統會忽略空行。
範例
# This is an example of an input device configuration file.
# It might be used to describe the characteristics of a built-in touch screen.
# This is an internal device, not an external peripheral attached to the USB
# or Bluetooth bus.
device.internal = 1
# The device should behave as a touch screen, which uses the same orientation
# as the built-in display.
touch.deviceType = touchScreen
touch.orientationAware = 1
# Additional calibration properties...
# etc...
常見屬性
下列屬性適用於所有輸入裝置類別。
請參閱各輸入裝置類別的說明文件,瞭解各類別使用的特殊屬性。
device.internal
定義: device.internal
= 0
| 1
指定輸入裝置是內建元件,還是外接 (最有可能是可移除) 外接裝置。
這個屬性會決定喚醒事件的預設政策決定。
除非在按鍵版面配置檔案或硬式編碼政策規則中明確設定,否則內部輸入裝置通常不會喚醒螢幕。這項區別可避免按鍵按壓和觸控動作在手機放在口袋時誤觸喚醒手機。通常只會定義少數幾個喚醒鍵。
相反地,外部輸入裝置通常會更積極地喚醒裝置,因為系統會假設這些裝置在運送期間已關閉或未插入。舉例來說,按下外接鍵盤上的任何按鍵,就是使用者希望喚醒裝置並回應的最佳指標。
請務必確認所有內部輸入裝置的 device.internal
屬性值皆正確設定。
驗證
請務必使用驗證鍵盤配置工具驗證輸入裝置設定檔。
這個頁面中的內容和程式碼範例均受《內容授權》中的授權所規範。Java 與 OpenJDK 是 Oracle 和/或其關係企業的商標或註冊商標。
上次更新時間:2025-07-27 (世界標準時間)。
[[["容易理解","easyToUnderstand","thumb-up"],["確實解決了我的問題","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["缺少我需要的資訊","missingTheInformationINeed","thumb-down"],["過於複雜/步驟過多","tooComplicatedTooManySteps","thumb-down"],["過時","outOfDate","thumb-down"],["翻譯問題","translationIssue","thumb-down"],["示例/程式碼問題","samplesCodeIssue","thumb-down"],["其他","otherDown","thumb-down"]],["上次更新時間:2025-07-27 (世界標準時間)。"],[],[],null,["# Input device configuration files (`.idc` files) contain device-specific\nconfiguration properties that affect the behavior of input devices.\n\nInput device configuration files are typically not necessary for standard\nperipherals such as HID keyboards and mice since the default system behavior\nusually ensures that they will work out of the box. On the other hand,\nbuilt-in embedded devices, particularly touch screens, almost always\nrequire input device configuration files to specify their behavior.\n\nRationale\n---------\n\nAndroid automatically detects and configures most input device capabilities\nbased on the event types and properties that are reported by the associated\nLinux kernel input device driver.\n\nFor example, if an input device supports the `EV_REL` event type and codes\n`REL_X` and `REL_Y` as well as the `EV_KEY` event type and `BTN_MOUSE`,\nthen Android will classify the input device as a mouse. The default behavior\nfor a mouse is to present an on-screen cursor which tracks the mouse's movements\nand simulates touches when the mouse is clicked. Although the mouse can\nbe configured differently, the default behavior is usually sufficient for\nstandard mouse peripherals.\n\nCertain classes of input devices are more ambiguous. For example, multi-touch\ntouch screens and touch pads both support the `EV_ABS` event type and codes\n`ABS_MT_POSITION_X` and `ABS_MT_POSITION_Y` at a minimum. However, the intended\nuses of these devices are quite different and cannot always be determined\nautomatically. Also, additional information is required to make sense of the\npressure and size information reported by touch devices. Hence touch devices,\nespecially built-in touch screens, usually need IDC files.\n\nLocation\n--------\n\nInput device configuration files are located by USB vendor, product (and\noptionally version) ID or by input device name.\n\nThe following paths are consulted in order.\n\n- `/product/usr/idc/Vendor_XXXX_Product_XXXX_Version_XXXX.idc`\n- `/system_ext/usr/idc/Vendor_XXXX_Product_XXXX_Version_XXXX.idc`\n- `/odm/usr/idc/Vendor_XXXX_Product_XXXX_Version_XXXX.idc`\n- `/vendor/usr/idc/Vendor_XXXX_Product_XXXX_Version_XXXX.idc`\n- `/system/usr/idc/Vendor_XXXX_Product_XXXX_Version_XXXX.idc`\n- `/data/system/devices/idc/Vendor_XXXX_Product_XXXX_Version_XXXX.idc`\n- `/product/usr/idc/Vendor_XXXX_Product_XXXX.idc`\n- `/system_ext/usr/idc/Vendor_XXXX_Product_XXXX.idc`\n- `/odm/usr/idc/Vendor_XXXX_Product_XXXX.idc`\n- `/vendor/usr/idc/Vendor_XXXX_Product_XXXX.idc`\n- `/system/usr/idc/Vendor_XXXX_Product_XXXX.idc`\n- `/data/system/devices/idc/Vendor_XXXX_Product_XXXX.idc`\n- `/product/usr/idc/`\u003cvar translate=\"no\"\u003edevice-name\u003c/var\u003e`.idc`\n- `/system_ext/usr/idc/`\u003cvar translate=\"no\"\u003edevice-name\u003c/var\u003e`.idc`\n- `/odm/usr/idc/`\u003cvar translate=\"no\"\u003edevice-name\u003c/var\u003e`.idc`\n- `/vendor/usr/idc/`\u003cvar translate=\"no\"\u003edevice-name\u003c/var\u003e`.idc`\n- `/system/usr/idc/`\u003cvar translate=\"no\"\u003edevice-name\u003c/var\u003e`.idc`\n- `/data/system/devices/idc/`\u003cvar translate=\"no\"\u003edevice-name\u003c/var\u003e`.idc`\n\nWhen constructing a file path that contains the device name, all characters\nin the device name other than '0'-'9', 'a'-'z', 'A'-'Z', '-' or '_' are replaced by '_'.\n\nSyntax\n------\n\nAn input device configuration file is a plain text file consisting of property\nassignments and comments.\n\n### Properties\n\nProperty assignments each consist of a property name, an `=`, a property value,\nand a new line. Like this: \n\n```\nproperty = value\n```\n\nProperty names are non-empty literal text identifiers. They must not contain\nwhitespace. Each components of the input system defines a set of properties\nthat are used to configure its function.\n\nProperty values are non-empty string literals, integers or floating point numbers.\nThey must not contain whitespace or the reserved characters `\\` or `\"`.\n\nProperty names and values are case-sensitive.\n\n### Comments\n\nComment lines begin with '#' and continue to the end of the line. Like this: \n\n```\n# A comment!\n```\n\nBlank lines are ignored.\n\n### Example\n\n```\n# This is an example of an input device configuration file.\n# It might be used to describe the characteristics of a built-in touch screen.\n\n# This is an internal device, not an external peripheral attached to the USB\n# or Bluetooth bus.\ndevice.internal = 1\n\n# The device should behave as a touch screen, which uses the same orientation\n# as the built-in display.\ntouch.deviceType = touchScreen\ntouch.orientationAware = 1\n\n# Additional calibration properties...\n# etc...\n```\n\nCommon properties\n-----------------\n\nThe following property is common to all input device classes.\n\nRefer to the documentation of each input device class for information about the\nspecial properties used by each class.\n\n#### `device.internal`\n\n*Definition:* `device.internal` = `0` \\| `1`\n\nSpecifies whether the input device is an internal built-in component as opposed to an\nexternally attached (most likely removable) peripheral.\n\n- If the value is `0`, the device is external.\n\n- If the value is `1`, the device is internal.\n\n- If the value is not specified, the default value is `0` for all devices on the\n USB (BUS_USB) or Bluetooth (BUS_BLUETOOTH) bus, `1` otherwise.\n\nThis property determines default policy decisions regarding wake events.\n\nInternal input devices generally do not wake the display from sleep unless explicitly\nconfigured to do so in the key layout file or in a hardcoded policy rule. This\ndistinction prevents key presses and touches from spuriously waking up your phone\nwhen it is in your pocket. Usually there are only a small handful of wake keys defined.\n\nConversely, external input devices usually wake the device more aggressively because\nthey are assumed to be turned off or not plugged in during transport. For example,\npressing any key on an external keyboard is a good indicator that the user wants the\ndevice to wake up and respond.\n\nIt is important to ensure that the value of the `device.internal` property is set\ncorrectly for all internal input devices.\n\nValidation\n----------\n\nMake sure to validate your input device configuration files using the\n[Validate Keymaps](/docs/core/interaction/input/validate-keymaps) tool."]]