docs to Mandarin Chinese (#5960)
* faq_general.md to Chinese faq_general.md to Chinese faq finished * custom_quantum_functions.md to Chinese custom_quantum_functions.md to Chinese * custom_quantum_functions.md fix custom_quantum_functions.md fix * custom_quantum_functions.md fix translate custom_quantum_functions.md fix translate * !ver.English! _summary.md bug fix _summary.md bug fix of English doc. add".md" behind "feature_combo" * !ver.English! custom_quantum_functions.md fix#5869 custom_quantum_functions.md in English : delete redundant "is" . issue#5869 * !ver.English! how_keyboards_work.md link fix change https://en.wikipedia.org/wiki/Unicode_input#Hexadecimal_code_input to https://en.wikipedia.org/wiki/Unicode_input#Hexadecimal_input "#Hexadecimal_code_input" not exist * !English! how_keyboards_work.md add missing "t" Tied to a specific OS a a time (need recompilation when changing OS); change to Tied to a specific OS at a time (need recompilation when changing OS); * _summary.md improve translation _summary.md improve translation * reference_glossary.md into Chinese reference_glossary.md into Chinese 术语表翻译，这个术语表英文版似乎不太全，应该补充英文版，并在中文版添加其他具有中国特色的术语。
This commit is contained in:
ymzcdg
MechMerlin
parent
e7711b3b66
commit
e0a0d80bd3
6 changed files with 715 additions and 36 deletions
|
|
@ -267,7 +267,7 @@ You should use this function if you need custom matrix scanning code. It can als
|
|||
|
||||
If the board supports it, it can be "idled", by stopping a number of functions. A good example of this is RGB lights or backlights. This can save on power consumption, or may be better behavior for your keyboard.
|
||||
|
||||
This is controlled by two functions: `suspend_power_down_*` and `suspend_wakeup_init_*`, which are called when the system is board is idled and when it wakes up, respectively.
|
||||
This is controlled by two functions: `suspend_power_down_*` and `suspend_wakeup_init_*`, which are called when the system board is idled and when it wakes up, respectively.
|
||||
|
||||
|
||||
### Example suspend_power_down_user() and suspend_wakeup_init_user() Implementation
|
||||
|
|
|
|||
|
|
@ -63,10 +63,10 @@ You may wonder why a keyboard layout containing all of Unicode is not devised th
|
|||
|
||||
## How to (Maybe) Enter Unicode Characters
|
||||
|
||||
You can have the firmware send *sequences of keys* to use the [software Unicode Input Method](https://en.wikipedia.org/wiki/Unicode_input#Hexadecimal_code_input) of the target operating system, thus effectively entering characters independently of the layout defined in the OS.
|
||||
You can have the firmware send *sequences of keys* to use the [software Unicode Input Method](https://en.wikipedia.org/wiki/Unicode_input#Hexadecimal_input) of the target operating system, thus effectively entering characters independently of the layout defined in the OS.
|
||||
|
||||
Yet, it does come with multiple disadvantages:
|
||||
|
||||
- Tied to a specific OS a a time (need recompilation when changing OS);
|
||||
- Tied to a specific OS at a time (need recompilation when changing OS);
|
||||
- Within a given OS, does not work in all software;
|
||||
- Limited to a subset of Unicode on some systems.
|
||||
|
|
|
|||
|
|
@ -7,27 +7,27 @@
|
|||
* [学习资源](newbs_learn_more_resources.md)
|
||||
|
||||
* [QMK基础](README.md)
|
||||
* [QMK 简介](getting_started_introduction.md)
|
||||
* [贡献 QMK](contributing.md)
|
||||
* [QMK简介](getting_started_introduction.md)
|
||||
* [向QMK贡献](contributing.md)
|
||||
* [如何使用Github](getting_started_github.md)
|
||||
* [获得帮助](getting_started_getting_help.md)
|
||||
|
||||
* [问题解答](faq.md)
|
||||
* [一般问题](faq_general.md)
|
||||
* [构建/编译QMK](faq_build.md)
|
||||
* [调试/故障排除 QMK](faq_debug.md)
|
||||
* [键盘布局](faq_keymap.md)
|
||||
* [构建/编译](faq_build.md)
|
||||
* [调试/故障排除](faq_debug.md)
|
||||
* [键盘映射](faq_keymap.md)
|
||||
|
||||
* 详细指南
|
||||
* [安装构建工具](getting_started_build_tools.md)
|
||||
* [流浪者指南](getting_started_vagrant.md)
|
||||
* [vagrant指南](getting_started_vagrant.md)
|
||||
* [构建/编译指令](getting_started_make_guide.md)
|
||||
* [刷新固件](flashing.md)
|
||||
* [定制功能](custom_quantum_functions.md)
|
||||
* [布局概述](keymap.md)
|
||||
* [映射概述](keymap.md)
|
||||
|
||||
* [硬件](hardware.md)
|
||||
* [AVR 处理器](hardware_avr.md)
|
||||
* [AVR处理器](hardware_avr.md)
|
||||
* [驱动](hardware_drivers.md)
|
||||
|
||||
* 参考
|
||||
|
|
@ -35,8 +35,8 @@
|
|||
* [配置选项](config_options.md)
|
||||
* [键码](keycodes.md)
|
||||
* [记录最佳实践](documentation_best_practices.md)
|
||||
* [文档指南](documentation_templates.md)
|
||||
* [词汇表](reference_glossary.md)
|
||||
* [文档模板](documentation_templates.md)
|
||||
* [术语表](reference_glossary.md)
|
||||
* [单元测试](unit_testing.md)
|
||||
* [有用的功能](ref_functions.md)
|
||||
* [配置器支持](reference_configurator_support.md)
|
||||
|
|
@ -44,35 +44,35 @@
|
|||
|
||||
* [特性](features.md)
|
||||
* [基本键码](keycodes_basic.md)
|
||||
* [US ANSI 控制键](keycodes_us_ansi_shifted.md)
|
||||
* [US ANSI控制码](keycodes_us_ansi_shifted.md)
|
||||
* [量子键码](quantum_keycodes.md)
|
||||
* [高级键码](feature_advanced_keycodes.md)
|
||||
* [音频](feature_audio.md)
|
||||
* [自动控制](feature_auto_shift.md)
|
||||
* [自动shift](feature_auto_shift.md)
|
||||
* [背光](feature_backlight.md)
|
||||
* [蓝牙](feature_bluetooth.md)
|
||||
* [Bootmagic](feature_bootmagic.md)
|
||||
* [热改键](feature_bootmagic.md)
|
||||
* [组合](feature_combo)
|
||||
* [命令](feature_command.md)
|
||||
* [动态宏指令](feature_dynamic_macros.md)
|
||||
* [编码器](feature_encoders.md)
|
||||
* [Grave Escape](feature_grave_esc.md)
|
||||
* [键锁](feature_key_lock.md)
|
||||
* [层](feature_layouts.md)
|
||||
* [引导键](feature_leader_key.md)
|
||||
* [LED 阵列](feature_led_matrix.md)
|
||||
* [重音号Esc复合键](feature_grave_esc.md)
|
||||
* [自锁键](feature_key_lock.md)
|
||||
* [布局](feature_layouts.md)
|
||||
* [前导键](feature_leader_key.md)
|
||||
* [LED阵列](feature_led_matrix.md)
|
||||
* [宏指令](feature_macros.md)
|
||||
* [鼠标键](feature_mouse_keys.md)
|
||||
* [一键功能](feature_advanced_keycodes.md#one-shot-keys)
|
||||
* [指针设备](feature_pointing_device.md)
|
||||
* [PS/2 鼠标](feature_ps2_mouse.md)
|
||||
* [RGB 光](feature_rgblight.md)
|
||||
* [RGB 矩阵](feature_rgb_matrix.md)
|
||||
* [PS/2鼠标](feature_ps2_mouse.md)
|
||||
* [RGB灯光](feature_rgblight.md)
|
||||
* [RGB矩阵](feature_rgb_matrix.md)
|
||||
* [空格候补换挡](feature_space_cadet_shift.md)
|
||||
* [空格候补换挡回车](feature_space_cadet_shift_enter.md)
|
||||
* [速录机](feature_stenography.md)
|
||||
* [换手](feature_swap_hands.md)
|
||||
* [踢踏舞](feature_tap_dance.md)
|
||||
* [多击键](feature_tap_dance.md)
|
||||
* [终端](feature_terminal.md)
|
||||
* [热敏打印机](feature_thermal_printer.md)
|
||||
* [Unicode](feature_unicode.md)
|
||||
|
|
@ -80,16 +80,16 @@
|
|||
* [速度键](feature_velocikey.md)
|
||||
|
||||
* 针对制造者和定制者
|
||||
* [飞线指南](hand_wire.md)
|
||||
* [ISP 刷新指南](isp_flashing_guide.md)
|
||||
* [ARM 调试指南](arm_debugging.md)
|
||||
* [I2C 驱动](i2c_driver.md)
|
||||
* [GPIO 控制器](internals_gpio_control.md)
|
||||
* [Proton C 转换](proton_c_conversion.md)
|
||||
* [手工连线指南](hand_wire.md)
|
||||
* [ISP刷新指南](isp_flashing_guide.md)
|
||||
* [ARM调试指南](arm_debugging.md)
|
||||
* [I2C驱动](i2c_driver.md)
|
||||
* [GPIO控制器](internals_gpio_control.md)
|
||||
* [Proton C转换](proton_c_conversion.md)
|
||||
|
||||
* 深入了解
|
||||
* [键盘如何工作](how_keyboards_work.md)
|
||||
* [理解 QMK](understanding_qmk.md)
|
||||
* [理解QMK](understanding_qmk.md)
|
||||
|
||||
* 其他话题
|
||||
* [使用Eclipse开发QMK](other_eclipse.md)
|
||||
|
|
@ -99,8 +99,8 @@
|
|||
* QMK 内构 (正在编写)
|
||||
* [定义](internals_defines.md)
|
||||
* [输入回调寄存器](internals_input_callback_reg.md)
|
||||
* [Midi 设备](internals_midi_device.md)
|
||||
* [Midi 设备设置过程](internals_midi_device_setup_process.md)
|
||||
* [Midi 工具库](internals_midi_util.md)
|
||||
* [Midi设备](internals_midi_device.md)
|
||||
* [Midi设备设置过程](internals_midi_device_setup_process.md)
|
||||
* [Midi工具库](internals_midi_util.md)
|
||||
* [发送函数](internals_send_functions.md)
|
||||
* [Sysex 工具](internals_sysex_tools.md)
|
||||
* [Sysex工具](internals_sysex_tools.md)
|
||||
|
|
|
|||
490
docs/zh-cn/custom_quantum_functions.md
Normal file
490
docs/zh-cn/custom_quantum_functions.md
Normal file
|
|
@ -0,0 +1,490 @@
|
|||
# 如何定制你键盘的功能
|
||||
|
||||
对于很多人来说客制化键盘可不只是向你的电脑发送你按了那个件这么简单。你肯定想实现比简单按键和宏更复杂的功能。QMK有能让你注入代码的钩子, 覆盖功能, 另外，还可以自定义键盘在不同情况下的行为。
|
||||
|
||||
本页不假定任何特殊的QMK知识，但阅读[理解QMK](understanding_qmk.md)将会在更基础的层面帮你理解发生了什么。
|
||||
|
||||
## A Word on Core vs 键盘 vs 布局
|
||||
|
||||
我们把qmk组织成一个层次结构：
|
||||
|
||||
* Core (`_quantum`)
|
||||
* Keyboard/Revision (`_kb`)
|
||||
* Keymap (`_user`)
|
||||
|
||||
下面描述的每一个函数都可以在定义上加一个`_kb()`或 `_user()` 后缀。 建议在键盘/修订层使用`_kb()`后缀，在布局层使用`_user()`后缀。
|
||||
|
||||
在键盘/修订层定义函数时，`_kb()`在执行任何代码前先调用`_user()`是必要的，不然布局层函数就不要被调用。
|
||||
<!-- 翻译问题：上面那句翻译的不太好-->
|
||||
# 自定义键码
|
||||
|
||||
到目前为止，最常见的任务是更改现有键码的行为或创建新的键码。从代码角度来看这些操作都很相似。
|
||||
|
||||
## 定义一个新键码
|
||||
|
||||
创建键码第一步，先枚举出它全部，也就是给键码起个名字并分配唯一数值。QMK没有直接限制最大键码值大小，而是提供了一个`SAFE_RANGE`宏。你可以在枚举时用`SAFE_RANGE`来保证你取得了唯一的键码值。
|
||||
|
||||
|
||||
这有枚举两个键码的例子。把这块加到`keymap.c`的话你就在布局中能用`FOO`和`BAR`了。
|
||||
|
||||
```c
|
||||
enum my_keycodes {
|
||||
FOO = SAFE_RANGE,
|
||||
BAR
|
||||
};
|
||||
```
|
||||
|
||||
## 为键码的行为编程
|
||||
|
||||
当你覆盖一个已存在按键的行为时，或将这个行为赋给新键时，你要用`process_record_kb()`和`process_record_user()`函数。这俩函数在键处理中真实键事件被处理前被QMK调用。如果这俩函数返回`true`，QMK将会用正常的方式处理键码。这样可以很方便的扩展键码的功能而不是替换它。如果函数返回`false` QMK会跳过正常键处理，然后发送键子抬起还是按下事件就由你决定了。
|
||||
|
||||
当某个键按下或释放时这俩函数会被调用。
|
||||
|
||||
### process_record_user()`函数示例实现
|
||||
|
||||
这个例子做了两个事。自定义了一个叫做`FOO`的键码的行为，并补充了在按下回车时播放音符。
|
||||
|
||||
```c
|
||||
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
|
||||
switch (keycode) {
|
||||
case FOO:
|
||||
if (record->event.pressed) {
|
||||
// 按下时做些什么
|
||||
} else {
|
||||
// 释放时做些什么
|
||||
}
|
||||
return false; // 跳过此键的所有进一步处理
|
||||
case KC_ENTER:
|
||||
// 当按下回车时播放音符
|
||||
if (record->event.pressed) {
|
||||
PLAY_NOTE_ARRAY(tone_qwerty);
|
||||
}
|
||||
return true; // 让QMK触发回车按下/释放事件
|
||||
default:
|
||||
return true; // 正常处理其他键码
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### `process_record_*` 函数文档
|
||||
|
||||
* 键盘/修订: `bool process_record_kb(uint16_t keycode, keyrecord_t *record)`
|
||||
* 布局: `bool process_record_user(uint16_t keycode, keyrecord_t *record)`
|
||||
|
||||
`keycode(键码)`参数是在布局上定义的，比如`MO(1)`, `KC_L`, 等等。 你要用 `switch...case` 块来处理这些事件。
|
||||
|
||||
`record`参数含有实际按键的信息：
|
||||
|
||||
```c
|
||||
keyrecord_t record {
|
||||
keyevent_t event {
|
||||
keypos_t key {
|
||||
uint8_t col
|
||||
uint8_t row
|
||||
}
|
||||
bool pressed
|
||||
uint16_t time
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
# LED控制
|
||||
|
||||
qmk提供了读取HID规范包含的5个LED的方法。:
|
||||
|
||||
* `USB_LED_NUM_LOCK`
|
||||
* `USB_LED_CAPS_LOCK`
|
||||
* `USB_LED_SCROLL_LOCK`
|
||||
* `USB_LED_COMPOSE`
|
||||
* `USB_LED_KANA`
|
||||
|
||||
这五个常量对应于主机LED状态的位置位。
|
||||
有两种方法可以获得主机LED状态：
|
||||
|
||||
* 通过执行 `led_set_user()`
|
||||
* 通过调用 `host_keyboard_leds()`
|
||||
|
||||
## `led_set_user()`
|
||||
|
||||
当5个LED中任何一个的状态需要改变时，此函数将被调用。此函数通过参数输入LED参数。
|
||||
使用`IS_LED_ON(usb_led, led_name)`和`IS_LED_OFF(usb_led, led_name)`这两个宏来检查LED状态。
|
||||
|
||||
!> `host_keyboard_leds()`可能会在`led_set_user()`被调用前返回新值。
|
||||
|
||||
### `led_set_user()`函数示例实现
|
||||
|
||||
```c
|
||||
void led_set_user(uint8_t usb_led) {
|
||||
if (IS_LED_ON(usb_led, USB_LED_NUM_LOCK)) {
|
||||
writePinLow(B0);
|
||||
} else {
|
||||
writePinHigh(B0);
|
||||
}
|
||||
if (IS_LED_ON(usb_led, USB_LED_CAPS_LOCK)) {
|
||||
writePinLow(B1);
|
||||
} else {
|
||||
writePinHigh(B1);
|
||||
}
|
||||
if (IS_LED_ON(usb_led, USB_LED_SCROLL_LOCK)) {
|
||||
writePinLow(B2);
|
||||
} else {
|
||||
writePinHigh(B2);
|
||||
}
|
||||
if (IS_LED_ON(usb_led, USB_LED_COMPOSE)) {
|
||||
writePinLow(B3);
|
||||
} else {
|
||||
writePinHigh(B3);
|
||||
}
|
||||
if (IS_LED_ON(usb_led, USB_LED_KANA)) {
|
||||
writePinLow(B4);
|
||||
} else {
|
||||
writePinHigh(B4);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### `led_set_*`函数文档
|
||||
|
||||
* 键盘/修订: `void led_set_kb(uint8_t usb_led)`
|
||||
* 布局: `void led_set_user(uint8_t usb_led)`
|
||||
|
||||
## `host_keyboard_leds()`
|
||||
|
||||
调用这个函数会返回最后收到的LED状态。这个函数在`led_set_*`之外读取LED状态时很有用，比如在[`matrix_scan_user()`](#矩阵扫描代码).
|
||||
为了便捷，你可以用`IS_HOST_LED_ON(led_name)`和`IS_HOST_LED_OFF(led_name)` 宏，而不直接调用和检查`host_keyboard_leds()`。
|
||||
|
||||
## 设置物理LED状态
|
||||
|
||||
一些键盘实现了为设置物理LED的状态提供了方便的方法。
|
||||
|
||||
### Ergodox Boards
|
||||
|
||||
Ergodox实现了提供`ergodox_right_led_1`/`2`/`3_on`/`off()`来让每个LED开或关, 也可以用 `ergodox_right_led_on`/`off(uint8_t led)` 按索引打开或关闭他们。
|
||||
|
||||
此外，还可以使用`ergodox_led_all_set(uint8_t n)`指定所有LED的亮度级别；针对每个LED用`ergodox_right_led_1`/`2`/`3_set(uint8_t n)`；使用索引的话用`ergodox_right_led_set(uint8_t led, uint8_t n)`。
|
||||
|
||||
Ergodox boards 同时定义了最低亮度级别`LED_BRIGHTNESS_LO`和最高亮度级别`LED_BRIGHTNESS_HI`(默认最高).
|
||||
|
||||
# 键盘初始化代码
|
||||
|
||||
键盘初始化过程有几个步骤。你是用那个函数取决于你想要做什么。
|
||||
|
||||
有三个主要初始化函数，按调用顺序列出。
|
||||
|
||||
* `keyboard_pre_init_*` - 会在大多数其他东西运行前运行。适用于哪些需要提前运行的硬件初始化。
|
||||
* `matrix_init_*` - 在固件启动过程中间被调用。此时硬件已初始化，功能尚未初始化。
|
||||
* `keyboard_post_init_*` - 在固件启动过程最后被调用。大多数情况下，你的“客制化”代码都可以放在这里。
|
||||
|
||||
!> 对于大多数人来说`keyboard_post_init_user`是你想要调用的函数。例如, 此时你可以设置RGB灯发光。
|
||||
|
||||
## 键盘预初始化代码
|
||||
|
||||
这代码极早运行，甚至都在USB初始化前运行。
|
||||
|
||||
在这之后不久矩阵就被初始化了。
|
||||
|
||||
对于大多数用户来说,这用不到，因为它主要是用于面向硬件的初始化。
|
||||
|
||||
但如果你有硬件初始化的话放在这里再好不过了(比如初始化LED引脚一类的).
|
||||
|
||||
### `keyboard_pre_init_user()`函数示例实现
|
||||
|
||||
本例中在键盘级别，设定 B0, B1, B2, B3, 和 B4 是LED引脚。
|
||||
|
||||
```c
|
||||
void keyboard_pre_init_user(void) {
|
||||
// 调用键盘预初始化代码
|
||||
|
||||
// 设置LED引脚为输出模式
|
||||
setPinOutput(B0);
|
||||
setPinOutput(B1);
|
||||
setPinOutput(B2);
|
||||
setPinOutput(B3);
|
||||
setPinOutput(B4);
|
||||
}
|
||||
```
|
||||
|
||||
### `keyboard_pre_init_*` 函数文档
|
||||
|
||||
* 键盘/修订: `void keyboard_pre_init_kb(void)`
|
||||
* 布局: `void keyboard_pre_init_user(void)`
|
||||
|
||||
## 矩阵初始化代码
|
||||
|
||||
这将会在矩阵初始化时被调用，在某些硬件设置好后，但在一些功能被初始化前。
|
||||
|
||||
这在你设置其他地方会用到的东西的时候会很有用，但与硬件无关，也不依赖于它的启动位置。
|
||||
|
||||
|
||||
### `matrix_init_*`函数文档
|
||||
|
||||
* 键盘/修订: `void matrix_init_kb(void)`
|
||||
* 布局: `void matrix_init_user(void)`
|
||||
|
||||
|
||||
## 键盘后初始化代码
|
||||
|
||||
这是键盘初始化过程中的最后一个任务。如果您想更改某些特性，这会很有用，因为此时应该对它们进行初始化。
|
||||
|
||||
|
||||
### `keyboard_post_init_user()`示例实现
|
||||
|
||||
本示例在所有初始化完成后运行，配置RGB灯。
|
||||
|
||||
```c
|
||||
void keyboard_post_init_user(void) {
|
||||
// 调用后初始化代码
|
||||
rgblight_enable_noeeprom(); // 使能Rgb，不保存设置
|
||||
rgblight_sethsv_noeeprom(180, 255, 255); // 将颜色设置到蓝绿色(青色)不保存
|
||||
rgblight_mode_noeeprom(RGBLIGHT_MODE_BREATHING + 3); // 设置快速呼吸模式不保存
|
||||
}
|
||||
```
|
||||
|
||||
### `keyboard_post_init_*` 函数文档
|
||||
|
||||
* 键盘/修订: `void keyboard_post_init_kb(void)`
|
||||
* 布局: `void keyboard_post_init_user(void)`
|
||||
|
||||
# 矩阵扫描代码
|
||||
|
||||
可能的话你要用`process_record_*()`自定义键盘，以这种方式连接到事件中，以确保代码不会对键盘产生负面的性能影响。然而，在极少数情况下，有必要进行矩阵扫描。在这些函数中要特别注意代码的性能，因为它每秒至少被调用10次。
|
||||
|
||||
### `matrix_scan_*`示例实现
|
||||
|
||||
这个例子被故意省略了。在hook这样一个对性能及其敏感的区域之前，您应该足够了解qmk的内部结构，以便在没有示例的情况下编写。如果你需要帮助，请[建立一个issue](https://github.com/qmk/qmk_firmware/issues/new)或[在Discord上与我们交流](https://discord.gg/Uq7gcHh).
|
||||
|
||||
### `matrix_scan_*` 函数文档
|
||||
|
||||
* 键盘/修订: `void matrix_scan_kb(void)`
|
||||
* 布局: `void matrix_scan_user(void)`
|
||||
|
||||
该函数在每次矩阵扫描时被调用，这基本与MCU处理能力上限相同。在这里写代码要谨慎，因为它会运行很多次。
|
||||
|
||||
你会在自定义矩阵扫描代码时用到这个函数。这也可以用作自定义状态输出(比如LED灯或者屏幕)或者其他即便用户不输入你也想定期运行的功能。
|
||||
|
||||
|
||||
# 键盘 空闲/唤醒 代码
|
||||
|
||||
如果键盘支持就可以通过停止一大票功能来达到"空闲"。RGB灯和背光就是很好的例子。这可以节约能耗，也可能让你键盘风味更佳。
|
||||
|
||||
用两个函数控制: `suspend_power_down_*`和`suspend_wakeup_init_*`, 分别在系统板空闲和唤醒时调用。
|
||||
|
||||
|
||||
### suspend_power_down_user()和suspend_wakeup_init_user()示例实现
|
||||
|
||||
|
||||
```c
|
||||
void suspend_power_down_user(void) {
|
||||
rgb_matrix_set_suspend_state(true);
|
||||
}
|
||||
|
||||
void suspend_wakeup_init_user(void) {
|
||||
rgb_matrix_set_suspend_state(false);
|
||||
}
|
||||
```
|
||||
|
||||
### 键盘 挂起/唤醒 函数文档
|
||||
|
||||
* 键盘/修订: `void suspend_power_down_kb(void)` 和`void suspend_wakeup_init_user(void)`
|
||||
* 布局: `void suspend_power_down_kb(void)` 和 `void suspend_wakeup_init_user(void)`
|
||||
|
||||
# 层改变代码
|
||||
|
||||
每当层改变这个就运行代码。这对于层指示或自定义层处理很有用。
|
||||
|
||||
### `layer_state_set_*` 示例实现
|
||||
|
||||
本例使用了Planck键盘示范了如何设置 [RGB背光灯](feature_rgblight.md)使之与层对应
|
||||
|
||||
```c
|
||||
uint32_t layer_state_set_user(uint32_t state) {
|
||||
switch (biton32(state)) {
|
||||
case _RAISE:
|
||||
rgblight_setrgb (0x00, 0x00, 0xFF);
|
||||
break;
|
||||
case _LOWER:
|
||||
rgblight_setrgb (0xFF, 0x00, 0x00);
|
||||
break;
|
||||
case _PLOVER:
|
||||
rgblight_setrgb (0x00, 0xFF, 0x00);
|
||||
break;
|
||||
case _ADJUST:
|
||||
rgblight_setrgb (0x7A, 0x00, 0xFF);
|
||||
break;
|
||||
default: // for any other layers, or the default layer
|
||||
rgblight_setrgb (0x00, 0xFF, 0xFF);
|
||||
break;
|
||||
}
|
||||
return state;
|
||||
}
|
||||
```
|
||||
### `layer_state_set_*` 函数文档
|
||||
|
||||
* 键盘/修订: `uint32_t layer_state_set_kb(uint32_t state)`
|
||||
* 布局: `uint32_t layer_state_set_user(uint32_t state)`
|
||||
|
||||
|
||||
该`状态`是活动层的bitmask, 详见[布局概述](keymap.md#布局的层状态)
|
||||
|
||||
|
||||
# 掉电保存配置 (EEPROM)
|
||||
|
||||
这会让你的配置长期的保存在键盘中。这些配置保存在你主控的EEPROM里，掉电不会消失。 设置可以用`eeconfig_read_kb`和`eeconfig_read_user`读取，可以用`eeconfig_update_kb`和`eeconfig_update_user`写入。这对于您希望能够切换的功能很有用(比如切换RGB层指示。此外，你可以用`eeconfig_init_kb`和`eeconfig_init_user`来设置EEPROM默认值。
|
||||
|
||||
最复杂的部分可能是，有很多方法可以通过EEPROM存储和访问数据，并且并没有用哪种方法是“政治正确”的。你每个功能只有一个双字(四字节)空间。
|
||||
|
||||
记住EEPROM是有写入寿命的。尽管写入寿命很高，但是并不是只有设置写道EEPROM中。如果你写入频繁，你的MCU寿命将会变短。
|
||||
|
||||
* 如果您不理解这个例子，那么您可能希望避免使用这个特性，因为它相当复杂。
|
||||
|
||||
### 示例实现
|
||||
|
||||
本例讲解了如何添加设置，并且读写。本里使用了用户布局。这是一个复杂的函数，有很多事情要做。实际上，它使用了很多上述函数来工作！
|
||||
|
||||
|
||||
在你的keymap.c文件中，将以下代码添加至顶部:
|
||||
```c
|
||||
typedef union {
|
||||
uint32_t raw;
|
||||
struct {
|
||||
bool rgb_layer_change :1;
|
||||
};
|
||||
} user_config_t;
|
||||
|
||||
user_config_t user_config;
|
||||
```
|
||||
|
||||
以上代码建立了一个结构体，该结构体可以存储设置并可用于写入EEPROM。如此这般将无需定义变量，因为在结构体中已然定义。要记住`bool` (布尔)值使用1位, `uint8_t`使用8位, `uint16_t`使用16位。你可以混合搭配使用，但是顺序记错可能会招致麻烦，因为那会改变写入写出的值。
|
||||
|
||||
`layer_state_set_*`函数中使用了`rgb_layer_change`，使用了`keyboard_post_init_user`和`process_record_user`来配置一切。
|
||||
|
||||
首先要使用`keyboard_post_init_user，你要加入`eeconfig_read_user()`来填充你刚刚创建的结构体。然后您可以立即使用这个结构来控制您的布局中的功能。就像这样：
|
||||
```c
|
||||
void keyboard_post_init_user(void) {
|
||||
// 调用布局级别的矩阵初始化
|
||||
|
||||
// 从EEPROM读用户配置
|
||||
user_config.raw = eeconfig_read_user();
|
||||
|
||||
// 如使能，设置默认层
|
||||
if (user_config.rgb_layer_change) {
|
||||
rgblight_enable_noeeprom();
|
||||
rgblight_sethsv_noeeprom_cyan();
|
||||
rgblight_mode_noeeprom(1);
|
||||
}
|
||||
}
|
||||
```
|
||||
以上函数会在读EEPROM配置后立即使用该设置来设置默认层RGB颜色。"raw"的值是从你上面基于"union"创建的结构体中转换来的。
|
||||
|
||||
```c
|
||||
uint32_t layer_state_set_user(uint32_t state) {
|
||||
switch (biton32(state)) {
|
||||
case _RAISE:
|
||||
if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_magenta(); rgblight_mode_noeeprom(1); }
|
||||
break;
|
||||
case _LOWER:
|
||||
if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_red(); rgblight_mode_noeeprom(1); }
|
||||
break;
|
||||
case _PLOVER:
|
||||
if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_green(); rgblight_mode_noeeprom(1); }
|
||||
break;
|
||||
case _ADJUST:
|
||||
if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_white(); rgblight_mode_noeeprom(1); }
|
||||
break;
|
||||
default: // 针对其他层或默认层
|
||||
if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_cyan(); rgblight_mode_noeeprom(1); }
|
||||
break;
|
||||
}
|
||||
return state;
|
||||
}
|
||||
```
|
||||
这样仅在值使能时会改变RGB背光灯。现在配置这个值, 为`process_record_user`创建一个新键码叫做`RGB_LYR`。我们要确保，如果使用正常的RGB代码，使用上面的示例将其关闭，请将其设置为：
|
||||
```c
|
||||
|
||||
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
|
||||
switch (keycode) {
|
||||
case FOO:
|
||||
if (record->event.pressed) {
|
||||
// 按下时做点什么
|
||||
} else {
|
||||
// 释放时做点什么
|
||||
}
|
||||
return false; // 跳过此键的进一步处理
|
||||
case KC_ENTER:
|
||||
// 在按下回车时播放音符
|
||||
if (record->event.pressed) {
|
||||
PLAY_NOTE_ARRAY(tone_qwerty);
|
||||
}
|
||||
return true; // 让QMK产生回车按下/释放事件
|
||||
case RGB_LYR: // 本句让underglow作为层指示，或正常使用。
|
||||
if (record->event.pressed) {
|
||||
user_config.rgb_layer_change ^= 1; // 切换状态
|
||||
eeconfig_update_user(user_config.raw); // 向EEPROM写入新状态
|
||||
if (user_config.rgb_layer_change) { // 如果层状态被使能
|
||||
layer_state_set(layer_state); // 那么立刻更新层颜色
|
||||
}
|
||||
}
|
||||
return false; break;
|
||||
case RGB_MODE_FORWARD ... RGB_MODE_GRADIENT: // 对于所有的RGB代码 (see quantum_keycodes.h, L400 可以参考)
|
||||
if (record->event.pressed) { //本句失能层指示，假设你改变了这个…你要把它禁用
|
||||
if (user_config.rgb_layer_change) { // 仅当使能时
|
||||
user_config.rgb_layer_change = false; // 失能，然后
|
||||
eeconfig_update_user(user_config.raw); // 向EEPROM写入设置
|
||||
}
|
||||
}
|
||||
return true; break;
|
||||
default:
|
||||
return true; // 按其他键正常
|
||||
}
|
||||
}
|
||||
```
|
||||
最后你要加入`eeconfig_init_user`函数，所以当EEPROM重置时，可以指定默认值, 甚至自定义操作。想强制重置EEPROM，请用`EEP_RST`键码或[Bootmagic](feature_bootmagic.md)函数。比如，如果要在默认情况下设置RGB层指示，并保存默认值
|
||||
|
||||
```c
|
||||
void eeconfig_init_user(void) { // EEPROM正被重置
|
||||
user_config.raw = 0;
|
||||
user_config.rgb_layer_change = true; // 我们想要默认使能
|
||||
eeconfig_update_user(user_config.raw); // 向EEPROM写入默认值
|
||||
|
||||
// use the non noeeprom versions, 还要向EEPROM写入这些值
|
||||
rgblight_enable(); // 默认使能RGB
|
||||
rgblight_sethsv_cyan(); // 默认设置青色
|
||||
rgblight_mode(1); // 默认设置长亮
|
||||
}
|
||||
```
|
||||
|
||||
然后就完事了。RGB层指示会在你想让它工作时工作。这个设置会一直保存，即便你拔下键盘。如果你使用其他RGB代码，层指示将失能，现在它可以做你所想了。
|
||||
|
||||
### 'EECONFIG' 函数文档
|
||||
|
||||
* 键盘/修订: `void eeconfig_init_kb(void)`, `uint32_t eeconfig_read_kb(void)`和`void eeconfig_update_kb(uint32_t val)`
|
||||
* 布局: `void eeconfig_init_user(void)`, `uint32_t eeconfig_read_user(void)`和`void eeconfig_update_user(uint32_t val)`
|
||||
|
||||
`val` 是你想写入EEPROM的值，`eeconfig_read_*`函数会从EEPROM返回一个32位(双字)的值。
|
||||
|
||||
# 自定义击键-长按临界值(TAPPING_TERM)
|
||||
默认情况下,击键-长按临界值是全球统一的，并且不能通过键进行配置。对于大多数用户来说这很好。但是在有些情况下，对于`LT`键来说按键延时对双功能键的提升更大，可能是因为有些键比其他的键更容易按住。为了不给每个都自定义键码，本功能可以为每个键定义`TAPPING_TERM`。
|
||||
|
||||
想使能这个功能的话, 要先在`config.h`加上`#define TAPPING_TERM_PER_KEY`。
|
||||
|
||||
|
||||
## `get_tapping_term`示例实现
|
||||
|
||||
想要修改基于键码的`TAPPING TERM`,你要向`keymap.c`文件添加如下代码:
|
||||
|
||||
```c
|
||||
uint16_t get_tapping_term(uint16_t keycode) {
|
||||
switch (keycode) {
|
||||
case SFT_T(KC_SPC):
|
||||
return TAPPING_TERM + 1250;
|
||||
case LT(1, KC_GRV):
|
||||
return 130;
|
||||
default:
|
||||
return TAPPING_TERM;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### `get_tapping_term` 函数文档
|
||||
|
||||
不像这篇的其他功能,这个不需要quantum或者键盘级别的函数，只要用户级函数即可。
|
||||
19
docs/zh-cn/faq_general.md
Normal file
19
docs/zh-cn/faq_general.md
Normal file
|
|
@ -0,0 +1,19 @@
|
|||
# 常见问题
|
||||
|
||||
## QMK是什么?
|
||||
|
||||
[QMK](https://github.com/qmk), 是量子机械键盘(Quantum Mechanical Keyboard)的缩写，是一群开源爱好者为定制键盘开发的工具。我们从[QMK固件](https://github.com/qmk/qmk_firmware)开始，这是[TMK](https://github.com/tmk/tmk_keyboard)的魔改分叉。
|
||||
|
||||
### 为什么叫量子(Quantum)?
|
||||
|
||||
<!-- 待修复 译者吐槽：文档作者竟然也不知道为啥。。。 -->
|
||||
|
||||
## QMK和TMK有什么区别?
|
||||
|
||||
TMK最初由[Jun Wako](https://github.com/tmk)设计和执行。QMK始于[Jack Humbert](https://github.com/jackhumbert)为Planck键盘创建的TMK分叉。一段时间后，Jack的分叉就和TMK相去甚远了，于是在2015年，Jack决定改名QMK。
|
||||
|
||||
从技术观点来讲，QMK是TMK添加一些新功能而成的。尤其是QMK扩展了可用的键码，使高级功能进一步丰富比如 `S()`, `LCTL()`, 和 `MO()`。全部键码见[键码](keycodes.md).
|
||||
|
||||
从工程的社区管理来讲TMK自己维护了所有官方支持的键盘，只有很小一部分社区支持。独立社区维护已存在分叉或为其他键盘创建的分叉。默认支持很少的键码，所以用户通常不会与他人分享布局。QMK鼓励通过集中管理仓库分享布局和键盘，我们会采纳所有符合质量标准的PR。这就极大的保证了社区维护，同时QMK小组也会在必要时给予帮助。
|
||||
|
||||
这两种方法都有其优点和缺点，并且代码在有意义时在TMK和QMK之间自由流动。
|
||||
170
docs/zh-cn/reference_glossary.md
Normal file
170
docs/zh-cn/reference_glossary.md
Normal file
|
|
@ -0,0 +1,170 @@
|
|||
# QMK术语表
|
||||
|
||||
## ARM
|
||||
多家公司生产的32位单片机系列，例如Atmel, Cypress, Kinetis, NXP, ST, 和 TI等公司。
|
||||
|
||||
## AVR
|
||||
[Atmel](http://www.microchip.com/)公司的单片机系列。 AVR是TMK的初始支持平台。
|
||||
|
||||
## AZERTY
|
||||
Français (法国)标准键盘布局。用键盘的前六个字母命名。
|
||||
|
||||
## Backlight(背光)
|
||||
键盘上照明的通称。背光通常是一组LED灯，通过键帽或者按轴发光，但也不总是这样。
|
||||
|
||||
## Bluetooth(蓝牙)
|
||||
一种短距离点对点无线协议。许多多无线键盘使用此协议。
|
||||
|
||||
## Bootloader(引导加载程序)
|
||||
一种写到你单片机的保护区的特殊的程序，该程序可以使单片机升级自己的固件，通常是通过USB来升级。
|
||||
|
||||
## Bootmagic(热改键)
|
||||
允许各种键盘行为动态变化的功能，如交换或禁用常用键。
|
||||
|
||||
## C
|
||||
一种适用于系统代码的低级编程语言。大多数qmk代码是用C编写的。
|
||||
|
||||
## Colemak
|
||||
一种流行的键盘布局。
|
||||
|
||||
## Compile(编译)
|
||||
把人可读的代码转换成你的单片机可以运行的机器代码的过程。
|
||||
|
||||
## Dvorak
|
||||
一个由August Dvorak博士在20世纪30年代创建的布局。Dvorak简化键盘(Dvorak Simplified Keyboard)的缩写。
|
||||
|
||||
## Dynamic Macro(动态宏)
|
||||
一种记录在键盘上的宏，当键盘拔出或计算机重新启动时，宏将丢失。
|
||||
|
||||
* [动态宏文档](feature_dynamic_macros.md)
|
||||
|
||||
## Eclipse
|
||||
是一种受C语言开发者追捧的集成开发环境(IDE)。
|
||||
|
||||
* [Eclipse安装说明](eclipse.md)
|
||||
|
||||
## Firmware(固件)
|
||||
用来控制单片机的软件。
|
||||
|
||||
## FLIP
|
||||
爱特梅尔(Atmel)提供的AVR器件刷写软件。我们一般推荐 [QMK刷写工具](https://github.com/qmk/qmk_flasher)，但是对于一些高级用例，需要FLIP。
|
||||
|
||||
## git
|
||||
命令行版本控制软件
|
||||
|
||||
## GitHub
|
||||
负责大多数QMK项目的网站。它是Git、问题跟踪和其他帮助我们运行qmk的功能的集成平台。
|
||||
|
||||
## ISP(在系统编程)
|
||||
在系统编程(In-system programming), 使用外部硬件和JTAG管脚对AVR芯片进行编程的一种方法。
|
||||
|
||||
## hid_listen
|
||||
从键盘接收调试消息的接口。 您可以使用[QMK Flasher](https://github.com/qmk/qmk_flasher)或[PJRC's hid_listen](https://www.pjrc.com/teensy/hid_listen.html)查看这些消息
|
||||
|
||||
## Keycode(键码)
|
||||
表示特定键的2字节数据。`0x00`-`0xFF`用于[基本键码](keycodes_basic.md)而`0x100`-`0xFFFF`用于[量子键码](quantum_keycodes.md).
|
||||
|
||||
## Key Down
|
||||
一个键按下尚未抬起时触发的事件。
|
||||
|
||||
## Key Up
|
||||
一个键抬起时触发的事件。
|
||||
|
||||
## Keymap(键映射)
|
||||
映射到物理键盘布局的一组键码，在按键和按键释放时进行处理。有时翻译为布局，意为软件上表示的布局，即映射。
|
||||
|
||||
## Layer(层)
|
||||
为了让一个键实现多个功能的抽象结构。最高活动层有限。
|
||||
|
||||
## Leader Key(前导键、设置菜单键)
|
||||
本功能允许您点击前导键，然后按顺序按1-3个键子来激活按键或其他量子功能。
|
||||
|
||||
* [前导键文档](feature_leader_key.md)
|
||||
|
||||
## LED
|
||||
发光二极管，键盘上最常用的指示灯装置。
|
||||
|
||||
## Make
|
||||
用于编译所有源文件的软件包。可以使用`make`命令和其他参数来编译你的固件。
|
||||
|
||||
## Matrix(矩阵)
|
||||
一种由列和行组成的接线模式，使单片机能够用较少的引脚检测按键。矩阵通常包含二极管，以达到全键无冲。
|
||||
|
||||
## Macro(宏)
|
||||
本功能可以在敲击单个键后发送多个按键事件(hid报告)。
|
||||
|
||||
* [宏文档](feature_macros.md)
|
||||
|
||||
## MCU(单片机、微控制单元)
|
||||
微控制单元，键盘的处理器。
|
||||
|
||||
## Modifier(修改键、修饰键、功能键)
|
||||
按住该键将会改变其他键的功能，修饰键包括 Ctrl, Alt, 和 Shift。
|
||||
|
||||
## Mousekeys(鼠标键)
|
||||
本功能在您敲击键盘时会控制鼠标光标。
|
||||
|
||||
* [鼠标键文档](feature_mouse_keys.md)
|
||||
|
||||
## N-Key Rollover (NKRO、全键无冲)
|
||||
一种术语，适用于能够同时报告任意数量按键的键盘。
|
||||
|
||||
## Oneshot Modifier(粘滞键)
|
||||
一种能让你的功能键一直保持按下，直到你按下其他键的功能。它叫做粘滞键或叫做粘连键，该功能由软件实现而非机械结构。
|
||||
|
||||
## ProMicro
|
||||
一种低成本AVR开发板。这种板子很容易在购物网站找到(价格不到20RMB)，但是据说刷写pro micro有点令人抓狂。
|
||||
|
||||
## Pull Request(拉请求、PR)
|
||||
向QMK请求提交代码。我们鼓励所有用户提交你们自己的键盘的代码。
|
||||
|
||||
## QWERTY
|
||||
标准英文键盘，通常也用于其他语言，例如中文。是用键盘前6个字母命名的。
|
||||
|
||||
## QWERTZ
|
||||
标准Deutsche(德语)键盘布局。使用前6个字母明名。
|
||||
|
||||
## Rollover(允许翻转、无冲形式)
|
||||
该术语表示在一个键已按下时按下另一个键。形式包括2KRO(双键无冲),6KRO(6键无冲),和NKRO(全键无冲)，无冲表示可同时按下而不产生冲突的键的数量。
|
||||
|
||||
## Scancode(扫描码)
|
||||
HID报告中的一个1字节的数字，表示一个键子。这些数字在下列文档中[HID Usage Tables](https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf)该文档发布于[USB-IF](http://www.usb.org/)。
|
||||
|
||||
## Space Cadet键盘的shift键
|
||||
一种特使的shift设置，能让你通过敲击左或右shift一次或多次键入不同的括号。
|
||||
|
||||
* [Space Cadet键盘文档](feature_space_cadet.md)
|
||||
|
||||
## Tap(敲击、单击)
|
||||
按下并释放一个键。在某些情况下您需要区分键按下和键抬起，但是单击把两个事件都包括了。
|
||||
|
||||
## Tap Dance(多击键)
|
||||
本功能允许向同一个键子分配多个键码，并根据按键次数区分。
|
||||
|
||||
* [多击键文档](feature_tap_dance.md)
|
||||
|
||||
## Teensy
|
||||
一种低成本AVR开发板<!--译者吐槽：我怎么感觉成本不低。好吧，我穷。 -->，通常用于手工连线键盘。这个teensy是有点小贵但是halfkay bootloader会让它刷写十分简单，所以也很常用。
|
||||
|
||||
## Underlight(背光)
|
||||
用于照亮电路板底面的LED的总称。这些LED通常从印刷电路板的底部向键盘所在的表面发光。
|
||||
|
||||
## Unicode
|
||||
在较大的计算机世界中，Unicode是一组编码方案，用于表示任何语言中的字符。 与qmk相关的是，它意味着使用各种操作系统方案来发送Unicode代码点，而不是扫描码。
|
||||
|
||||
* [Unicode文档](feature_unicode.md)
|
||||
|
||||
## Unit Testing(单元测试)
|
||||
针对qmk的自动运行测试框架。单元测试帮助我们确信我们的更改不会破坏任何东西。
|
||||
|
||||
* [单元测试文档](unit_testing.md)
|
||||
|
||||
## USB
|
||||
通用串行总线，键盘最常见的有线接口。
|
||||
|
||||
## USB 主机 (或简易主机)
|
||||
USB诸暨市你的电脑，或者你的键盘所插的任何设备。
|
||||
|
||||
# 并没有找到你想找到的术语?
|
||||
|
||||
[建立一个issue](https://github.com/qmk/qmk_firmware/issues) ，想好你的问题，或许你所问的术语就会添加到这里。创建一个PR帮我们添加需要添加的术语当然坠吼了:)
|
||||
Loading…
Reference in a new issue