diff options
| author | IskandarMa <epiciskandar@gmail.com> | 2022-01-19 02:24:02 +0800 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2022-01-18 18:24:02 +0000 |
| commit | f6a7f4d4aca4a1808850e2dcd8cc223ae5202062 (patch) | |
| tree | fefc9beff20ea6438e9c1927d83319ed4c85a6b0 /docs/zh-cn | |
| parent | 8a3dfe2246c4a6182cf18349e9c4d0d28cae4ec5 (diff) | |
update the Chinese translation based on the latest English version (#14924)
Co-authored-by: peepeetee <43021794+peepeetee@users.noreply.github.com>
Co-authored-by: Joy Lee <chang.li@westberrytech.com>
Co-authored-by: LitoMore <LitoMore@users.noreply.github.com>
Co-authored-by: Dasky <32983009+daskygit@users.noreply.github.com>
Diffstat (limited to 'docs/zh-cn')
47 files changed, 3932 insertions, 1348 deletions
diff --git a/docs/zh-cn/README.md b/docs/zh-cn/README.md index b42818d582..93dfbf1eef 100644 --- a/docs/zh-cn/README.md +++ b/docs/zh-cn/README.md @@ -1,31 +1,42 @@ -# QMK机械键盘固件 +# Quantum Mechanical Keyboard固件 -[](https://github.com/qmk/qmk_firmware/tags) -[](https://discord.gg/Uq7gcHh) -[](https://docs.qmk.fm) -[](https://github.com/qmk/qmk_firmware/pulse/monthly) -[](https://github.com/qmk/qmk_firmware/) +<!--- + original document: 0.15.12:docs/README.md + git diff 0.15.12 HEAD -- docs/README.md | cat +--> ## 什么是 QMK 固件? -QMK (*Quantum Mechanical Keyboard*) 是一个社区维护的开源软件，包括 QMK 固件, QMK 工具箱, qmk.fm网站, 和这些文档。QMK 固件是一个基于[tmk\_keyboard](https://github.com/tmk/tmk_keyboard)的键盘固件，它在爱特梅尔AVR微控制器实现一些有用的功能,确切地说, 是在 [OLKB product line](https://olkb.com), 在 [ErgoDox EZ](https://www.ergodox-ez.com) 键盘, 和 [Clueboard product line](https://clueboard.co/). 上。它被移植到使用ChibiOS的ARM芯片上. 它可以在飞线键盘或定制PCB键盘中发挥功能. +QMK (*Quantum Mechanical Keyboard*) 是一个社区维护的用于开发计算机输入设备的开源软件。社区专注像键盘，鼠标，MIDI设备的各种电子输入设备。社区内的核心小组成员维护[QMK固件](https://github.com/qmk/qmk_firmware)，[QMK配置器](https://config.qmk.fm)（QMK Configurator），[QMK工具箱](https://github.com/qmk/qmk_toolbox)（QMK Toolbox），[qmk.fm](https://qmk.fm)，并与各位社区成员维护这份文档。 -## 如何得到它 +## 如何入门 -如果你打算贡献布局, 键盘, 或者其他QMK特性, 一下是最简单的方法：[从GitHub获得repo分支](https://github.com/qmk/qmk_firmware#fork-destination-box), 并克隆你的repo到本地进行编辑，推送，然后从你的分支打开 [Pull Request](https://github.com/qmk/qmk_firmware/pulls). +<div class="flex-container"> -此外, 你也可以直接下载 ([zip](https://github.com/qmk/qmk_firmware/zipball/master), [tar](https://github.com/qmk/qmk_firmware/tarball/master)), 或者从git克隆 (`git@github.com:qmk/qmk_firmware.git`), 或 https (`https://github.com/qmk/qmk_firmware.git`). +?> **基础方式** [QMK配置器](zh-cn/newbs_building_firmware_configurator.md) <br> +用户友好的图形界面工具，无需具备编程知识基础。 -## 如何编译 +?> **进阶方式** [基于源代码](zh-cn/newbs.md) <br> +功能更强大，但门槛较高。 -在你能编译之前, 你需要[部署环境](zh-cn/getting_started_build_tools.md) 用于 AVR or/and ARM 开发。完成后, 你可以使用 `make` 命令来编译一个键盘和布局使用以下命令: +</div> - make planck/rev4:default +## 个性化定制 -这将建立 `planck`的`rev4` 修订版本并使用 `default`布局。并非所有键盘都有修订版本 (也叫做子项目或文件夹)，在此情况下，修订版本可以省略，如下: +QMK提供了很多功能，对应着很多可供浏览的配套文档。大部分功能都是通过修改[键映射](zh-cn/keymap.md)及[键码](zh-cn/keycodes.md)实现的。 - make preonic:default +## 需要帮助？ -## 如何定制 +请查阅[寻求帮助页面](zh-cn/support.md)以了解如何获取QMK使用方法的帮助。 -QMK 有许多 [特性](zh-cn/features.md)来探索，也有很多 [参考文档](https://docs.qmk.fm) 供您发掘。你可以通过修改 [布局](zh-cn/keymap.md)和[键码](zh-cn/keycodes.md)来利用许多特性。 +## 回馈社区 + +有多种回馈社区的方法，最简单的方法是开始使用QMK并向你的朋友们推荐它。 + +* 可以在我们的论坛及聊天室进行互助： + * [/r/olkb](https://www.reddit.com/r/olkb/) + * [Discord服务器](https://discord.gg/Uq7gcHh) +* 点击页面下方的“Edit This Page”，可以对文档提供贡献。 +* [将这份文档翻译为你的语言](zh-cn/translating.md) +* [上报bug](https://github.com/qmk/qmk_firmware/issues/new/choose) +* [发起Pull Request](zh-cn/contributing.md) diff --git a/docs/zh-cn/_summary.md b/docs/zh-cn/_summary.md index cedcfbd525..8a710a9ec1 100644 --- a/docs/zh-cn/_summary.md +++ b/docs/zh-cn/_summary.md @@ -1,133 +1,193 @@ -* [完全菜鸟指南](zh-cn/newbs.md) +<!--for translators, see first: zh-cn/reference_glossary.md#terms-of-zh-cn-translate --> +* 新手教程 + * [介绍](zh-cn/newbs.md) * [入门](zh-cn/newbs_getting_started.md) - * [构建你的第一个固件](zh-cn/newbs_building_firmware.md) - * [刷新固件](zh-cn/newbs_flashing.md) - * [测试和调试](zh-cn/newbs_testing_debugging.md) - * [Git最佳实践](zh-cn/newbs_git_best_practices.md) - * [使用你分叉(fork)的主分支(master)](zh-cn/newbs_git_using_your_master_branch.md) - * [解决合并冲突](zh-cn/newbs_git_resolving_merge_conflicts.md) - * [重新同步一个分支](zh-cn/newbs_git_resynchronize_a_branch.md) - * [学习资源](zh-cn/newbs_learn_more_resources.md) - -* [QMK基础](zh-cn/README.md) - * [QMK简介](zh-cn/getting_started_introduction.md) - * [QMK命令行工具](zh-cn/cli.md) - * [QMK命令行工具配置](zh-cn/cli_configuration.md) - * [向QMK贡献代码](zh-cn/contributing.md) - * [如何使用GitHub](zh-cn/getting_started_github.md) - * [获得帮助](zh-cn/getting_started_getting_help.md) - -* [非兼容性修改](zh-cn/breaking_changes.md) - * [我的PR已经被标记为非兼容性修改](zh-cn/breaking_changes_instructions.md) - * [2019年8月30日](zh-cn/ChangeLog/20190830.md) - -* [问题与解答](zh-cn/faq.md) - * [一般问题](zh-cn/faq_general.md) - * [构建/编译](zh-cn/faq_build.md) - * [调试/故障排除](zh-cn/faq_debug.md) - * [布局](zh-cn/faq_keymap.md) - * [Zadig驱动安装](zh-cn/driver_installation_zadig.md) - -* 详细指南 - * [安装构建工具](zh-cn/getting_started_build_tools.md) - * [vagrant指南](zh-cn/getting_started_vagrant.md) - * [构建/编译指南](zh-cn/getting_started_make_guide.md) - * [刷新固件](zh-cn/flashing.md) - * [定制功能](zh-cn/custom_quantum_functions.md) - * [布局概述](zh-cn/keymap.md) - -* [硬件](zh-cn/hardware.md) - * [兼容的单片机](zh-cn/compatible_microcontrollers.md) - * [AVR处理器](zh-cn/hardware_avr.md) - * [驱动](zh-cn/hardware_drivers.md) - -* 参考 - * [键盘指南](zh-cn/hardware_keyboard_guidelines.md) - * [配置选项](zh-cn/config_options.md) - * [键码](zh-cn/keycodes.md) - * [代码书写规范 - C](zh-cn/coding_conventions_c.md) - * [代码书写规范 - Python](zh-cn/coding_conventions_python.md) - * [文档书写规范](zh-cn/documentation_best_practices.md) - * [文档模板](zh-cn/documentation_templates.md) + * [构建第一个固件](zh-cn/newbs_building_firmware.md) + * [刷写固件](zh-cn/newbs_flashing.md) + * [寻求帮助](zh-cn/support.md) + * [其它资源](zh-cn/newbs_learn_more_resources.md) + * [QMK大纲](zh-cn/syllabus.md) + +* FAQ + * [常规FAQ](zh-cn/faq_general.md) + * [构建/编译QMK](zh-cn/faq_build.md) + * [QMK问题排查](zh-cn/faq_misc.md) + * [调试QMK](zh-cn/faq_debug.md) + * [键映射FAQ](zh-cn/faq_keymap.md) + * [充分利用AVR的存储空间](zh-cn/squeezing_avr.md) * [术语表](zh-cn/reference_glossary.md) - * [单元测试](zh-cn/unit_testing.md) - * [实用函数](zh-cn/ref_functions.md) - * [配置器支持](zh-cn/reference_configurator_support.md) - * [info.json 格式](zh-cn/reference_info_json.md) - * [Python 命令行开发](zh-cn/cli_development.md) - -* [特性](zh-cn/features.md) - * [基本键码](zh-cn/keycodes_basic.md) - * [US ANSI控制码](zh-cn/keycodes_us_ansi_shifted.md) - * [量子键码](zh-cn/quantum_keycodes.md) - * [高级键码](zh-cn/feature_advanced_keycodes.md) - * [音频](zh-cn/feature_audio.md) - * [自动shift](zh-cn/feature_auto_shift.md) - * [背光](zh-cn/feature_backlight.md) - * [蓝牙](zh-cn/feature_bluetooth.md) - * [热改键](zh-cn/feature_bootmagic.md) - * [组合](zh-cn/feature_combo) - * [命令](zh-cn/feature_command.md) - * [消抖 API](zh-cn/feature_debounce_type.md) - * [拨动开关](zh-cn/feature_dip_switch.md) - * [动态宏指令](zh-cn/feature_dynamic_macros.md) - * [编码器](zh-cn/feature_encoders.md) - * [重音号Esc复合键](zh-cn/feature_grave_esc.md) - * [触摸反馈](zh-cn/feature_haptic_feedback.md) - * [HD44780 LCD控制器](zh-cn/feature_hd44780.md) - * [自锁键](zh-cn/feature_key_lock.md) - * [布局](zh-cn/feature_layouts.md) - * [前导键](zh-cn/feature_leader_key.md) - * [LED阵列](zh-cn/feature_led_matrix.md) - * [宏指令](zh-cn/feature_macros.md) - * [鼠标键](zh-cn/feature_mouse_keys.md) - * [OLED驱动](zh-cn/feature_oled_driver.md) - * [一键功能](zh-cn/one_shot_keys.md) - * [指针设备](zh-cn/feature_pointing_device.md) - * [PS/2鼠标](zh-cn/feature_ps2_mouse.md) - * [RGB灯光](zh-cn/feature_rgblight.md) - * [RGB矩阵](zh-cn/feature_rgb_matrix.md) - * [空格候补换挡](zh-cn/feature_space_cadet.md) - * [分体键盘](zh-cn/feature_split_keyboard.md) - * [速录机](zh-cn/feature_stenography.md) - * [换手](zh-cn/feature_swap_hands.md) - * [多击键](zh-cn/feature_tap_dance.md) - * [终端](zh-cn/feature_terminal.md) - * [热敏打印机](zh-cn/feature_thermal_printer.md) - * [Unicode](zh-cn/feature_unicode.md) - * [用户空间](zh-cn/feature_userspace.md) - * [速度键](zh-cn/feature_velocikey.md) - -* 制造和定制者指南 - * [手工连线指南](zh-cn/hand_wire.md) - * [ISP刷新指南](zh-cn/isp_flashing_guide.md) - * [ARM调试指南](zh-cn/arm_debugging.md) - * [ADC设备](zh-cn/adc_driver.md) - * [I2C设备](zh-cn/i2c_driver.md) - * [SPI设备](zh-cn/spi_driver.md) - * [WS2812设备](zh-cn/ws2812_driver.md) - * [EEPROM设备](zh-cn/eeprom_driver.md) - * [GPIO控制](zh-cn/internals_gpio_control.md) - * [自定义键盘矩阵](zh-cn/custom_matrix.md) - * [Proton C转换](zh-cn/proton_c_conversion.md) - -* 深入了解 - * [键盘工作原理](zh-cn/how_keyboards_work.md) - * [深入了解QMK](zh-cn/understanding_qmk.md) - -* 其他话题 - * [使用Eclipse开发QMK](zh-cn/other_eclipse.md) - * [使用VSCode开发QMK](zh-cn/other_vscode.md) - * [支持](zh-cn/getting_started_getting_help.md) - * [翻译QMK文档](zh-cn/translating.md) - -* QMK 内构 (正在编写) - * [定义](zh-cn/internals_defines.md) - * [输入回调寄存器](zh-cn/internals_input_callback_reg.md) - * [Midi设备](zh-cn/internals_midi_device.md) - * [Midi设备配置过程](zh-cn/internals_midi_device_setup_process.md) - * [Midi工具库](zh-cn/internals_midi_util.md) - * [发送函数](zh-cn/internals_send_functions.md) - * [Sysex工具](zh-cn/internals_sysex_tools.md) -<!--fromen:20200126-6:03AM(GMT+8)--> -<!--cn:20200211-11:04AM(GMT+8)--> + +* 配置器(Configurator) + * [总览](zh-cn/newbs_building_firmware_configurator.md) + * [入门](zh-cn/configurator_step_by_step.md) + * [问题排查](zh-cn/configurator_troubleshooting.md) + * [框架](zh-cn/configurator_architecture.md) + * QMK API + * [总览](zh-cn/api_overview.md) + * [API文档](zh-cn/api_docs.md) + * [键盘支持](zh-cn/reference_configurator_support.md) + * [添加默认键映射](zh-cn/configurator_default_keymaps.md) + +* CLI + * [总览](zh-cn/cli.md) + * [配置](zh-cn/cli_configuration.md) + * [命令](zh-cn/cli_commands.md) + * [Tab补全](zh-cn/cli_tab_complete.md) + +* 使用QMK + * 导览 + * [功能定制](zh-cn/custom_quantum_functions.md) + * [利用Zadig安装驱动](zh-cn/driver_installation_zadig.md) + * [极简式制作](zh-cn/easy_maker.md) + * [键映射总览](zh-cn/keymap.md) + * 开发环境 + * [Docker指南](zh-cn/getting_started_docker.md) + * [Vagrant指南](zh-cn/getting_started_vagrant.md) + * 刷写(Flashing) + * [刷写](zh-cn/flashing.md) + * [刷写ATmega32A (ps2avrgb)](zh-cn/flashing_bootloadhid.md) + * IDE + * [在Eclipse中使用QMK](zh-cn/other_eclipse.md) + * [在VSCode中使用QMK](zh-cn/other_vscode.md) + * Git最佳实践 + * [介绍](zh-cn/newbs_git_best_practices.md) + * [你自己的副本](zh-cn/newbs_git_using_your_master_branch.md) + * [冲突合并](zh-cn/newbs_git_resolving_merge_conflicts.md) + * [基于你的分支修复](zh-cn/newbs_git_resynchronize_a_branch.md) + * 键盘组装 + * [飞线指南](zh-cn/hand_wire.md) + * [ISP刷写指南](zh-cn/isp_flashing_guide.md) + + * 键码入门 + * [键码汇总](zh-cn/keycodes.md) + * [基础键码](zh-cn/keycodes_basic.md) + * [语言特定的键码](zh-cn/reference_keymap_extras.md) + * [修饰键](zh-cn/feature_advanced_keycodes.md) + * [原子键码](zh-cn/quantum_keycodes.md) + * [Magic键码](zh-cn/keycodes_magic.md) + + * 键码进阶 + * [指令](zh-cn/feature_command.md) + * [动态宏](zh-cn/feature_dynamic_macros.md) + * [Grave Escape](zh-cn/feature_grave_esc.md) + * [前导键](zh-cn/feature_leader_key.md) + * [Mod-Tap](zh-cn/mod_tap.md) + * [宏](zh-cn/feature_macros.md) + * [鼠标键](zh-cn/feature_mouse_keys.md) + * [Space Cadet Shift](zh-cn/feature_space_cadet.md) + * [US ANSI上档键值](zh-cn/keycodes_us_ansi_shifted.md) + + * 软件特性 + * [自动Shift](zh-cn/feature_auto_shift.md) + * [组合键](zh-cn/feature_combo.md) + * [防抖API](zh-cn/feature_debounce_type.md) + * [按键锁定](zh-cn/feature_key_lock.md) + * [按键重定义](zh-cn/feature_key_overrides.md) + * [层](zh-cn/feature_layers.md) + * [粘滞键](zh-cn/one_shot_keys.md) + * [光标设备](zh-cn/feature_pointing_device.md) + * [原生HID](zh-cn/feature_rawhid.md) + * [Sequencer](zh-cn/feature_sequencer.md) + * [换手](zh-cn/feature_swap_hands.md) + * [一键多用](zh-cn/feature_tap_dance.md) + * [点按配置](zh-cn/tap_hold.md) + * [终端](zh-cn/feature_terminal.md) + * [Unicode](zh-cn/feature_unicode.md) + * [用户空间](zh-cn/feature_userspace.md) + * [WPM计算](zh-cn/feature_wpm.md) + + * 硬件特性 + * 显示 + * [HD44780 LCD控制器](zh-cn/feature_hd44780.md) + * [ST7565 LCD驱动](zh-cn/feature_st7565.md) + * [OLED驱动](zh-cn/feature_oled_driver.md) + * 灯效 + * [背光](zh-cn/feature_backlight.md) + * [LED矩阵](zh-cn/feature_led_matrix.md) + * [RGB灯光](zh-cn/feature_rgblight.md) + * [RGB矩阵](zh-cn/feature_rgb_matrix.md) + * [音频](zh-cn/feature_audio.md) + * [蓝牙](zh-cn/feature_bluetooth.md) + * [Bootmagic Lite](zh-cn/feature_bootmagic.md) + * [自定义矩阵](zh-cn/custom_matrix.md) + * [Digitizer](zh-cn/feature_digitizer.md) + * [拨动开关（DIP Switch）](zh-cn/feature_dip_switch.md) + * [编码器（旋钮）](zh-cn/feature_encoders.md) + * [触摸反馈](zh-cn/feature_haptic_feedback.md) + * [摇杆](zh-cn/feature_joystick.md) + * [LED指示](zh-cn/feature_led_indicators.md) + * [MIDI](zh-cn/feature_midi.md) + * [Proton C转换](zh-cn/proton_c_conversion.md) + * [PS/2鼠标](zh-cn/feature_ps2_mouse.md) + * [分体式键盘](zh-cn/feature_split_keyboard.md) + * [速记](zh-cn/feature_stenography.md) + * [热敏打印机](zh-cn/feature_thermal_printer.md) + * [Velocikey](zh-cn/feature_velocikey.md) + +* QMK开发 + * [PR Checklist](zh-cn/pr_checklist.md) + * 打破兼容的改动 + * [总览](zh-cn/breaking_changes.md) + * [我的PR已打上标记](zh-cn/breaking_changes_instructions.md) + * [近期的变更日志(Changelog)](zh-cn/ChangeLog/20210529.md "QMK v0.13.0 - 2021 May 29") + * [更早期的不兼容改动](zh-cn/breaking_changes_history.md) + + * C语言开发 + * [ARM调试指引](zh-cn/arm_debugging.md) + * [AVR处理器](zh-cn/hardware_avr.md) + * [C编码规范](zh-cn/coding_conventions_c.md) + * [兼容的微处理器](zh-cn/compatible_microcontrollers.md) + * [驱动](zh-cn/hardware_drivers.md) + * [ADC驱动](zh-cn/adc_driver.md) + * [Audio驱动](zh-cn/audio_driver.md) + * [I2C驱动](zh-cn/i2c_driver.md) + * [SPI驱动](zh-cn/spi_driver.md) + * [WS2812驱动](zh-cn/ws2812_driver.md) + * [EEPROM驱动](zh-cn/eeprom_driver.md) + * [串口驱动](zh-cn/serial_driver.md) + * [UART驱动](zh-cn/uart_driver.md) + * [操控GPIO](zh-cn/internals_gpio_control.md) + * [键盘开发指引](zh-cn/hardware_keyboard_guidelines.md) + + * Python开发 + * [编码规范](zh-cn/coding_conventions_python.md) + * [QMK CLI开发](zh-cn/cli_development.md) + + * 配置器开发 + * QMK API + * [开发环境](zh-cn/api_development_environment.md) + * [架构总览](zh-cn/api_development_overview.md) + + * 硬件平台开发 + * Arm/ChibiOS + * [选择MCU](zh-cn/platformdev_selecting_arm_mcu.md) + * [启动引导](zh-cn/platformdev_chibios_earlyinit.md) + + * QMK参考信息 + * [参与到QMK](zh-cn/contributing.md) + * [翻译QMK文档](zh-cn/translating.md)<!--but should we translate this? currently keep it fallback--> + * [配置](zh-cn/config_options.md) + * [数据驱动配置](zh-cn/data_driven_config.md) + * [Make指引](zh-cn/getting_started_make_guide.md) + * [编写文档的最佳实践](zh-cn/documentation_best_practices.md) + * [文档模板](zh-cn/documentation_templates.md) + * [贡献配列到社区](zh-cn/feature_layouts.md) + * [单元测试](zh-cn/unit_testing.md) + * [常用函数](zh-cn/ref_functions.md) + * [info.json参考资料](zh-cn/reference_info_json.md) + + * 深入了解 + * [键盘工作原理](zh-cn/how_keyboards_work.md) + * [键盘矩阵原理](zh-cn/how_a_matrix_works.md) + * [了解QMK](zh-cn/understanding_qmk.md) + + * QMK内部细节 (编辑中) + * [定义](zh-cn/internals_defines.md) + * [输入回调的注册](zh-cn/internals_input_callback_reg.md) + * [Midi设备](zh-cn/internals_midi_device.md) + * [Midi设备驱动流程](zh-cn/internals_midi_device_setup_process.md) + * [Midi辅助功能](zh-cn/internals_midi_util.md) + * [发送函数](zh-cn/internals_send_functions.md) + * [Sysex工具](zh-cn/internals_sysex_tools.md) + +<!--fromen:20211014-12:00(GMT+8) commit 04cf161aa01fd433b5dae69d9fd31569ed5dca59--> diff --git a/docs/zh-cn/api_docs.md b/docs/zh-cn/api_docs.md new file mode 100644 index 0000000000..a2df9ec20a --- /dev/null +++ b/docs/zh-cn/api_docs.md @@ -0,0 +1,73 @@ +# QMK API + +<!--- + original document: 0.15.12:docs/api_docs.md + git diff 0.15.12 HEAD -- docs/api_docs.md | cat +--> + +本章节详述了QMK API的使用方法，若您是应用开发者，使用这套API可以实现[QMK](https://qmk.fm)键盘固件的编译支持。 + +## 总览 + +本服务提供了一套用于编译自定义键映射的异步API，通过POST方式发送JSON参数到API，定期检查执行状态，待固件编译完成后，即可下载生成的固件文件和固件的源文件（如果需要的话）。 + +#### 荷载JSON参数示例： + +```json +{ + "keyboard": "clueboard/66/rev2", + "keymap": "my_awesome_keymap", + "layout": "LAYOUT_all", + "layers": [ + ["KC_GRV","KC_1","KC_2","KC_3","KC_4","KC_5","KC_6","KC_7","KC_8","KC_9","KC_0","KC_MINS","KC_EQL","KC_GRV","KC_BSPC","KC_PGUP","KC_TAB","KC_Q","KC_W","KC_E","KC_R","KC_T","KC_Y","KC_U","KC_I","KC_O","KC_P","KC_LBRC","KC_RBRC","KC_BSLS","KC_PGDN","KC_CAPS","KC_A","KC_S","KC_D","KC_F","KC_G","KC_H","KC_J","KC_K","KC_L","KC_SCLN","KC_QUOT","KC_NUHS","KC_ENT","KC_LSFT","KC_NUBS","KC_Z","KC_X","KC_C","KC_V","KC_B","KC_N","KC_M","KC_COMM","KC_DOT","KC_SLSH","KC_RO","KC_RSFT","KC_UP","KC_LCTL","KC_LGUI","KC_LALT","KC_MHEN","KC_SPC","KC_SPC","KC_HENK","KC_RALT","KC_RCTL","MO(1)","KC_LEFT","KC_DOWN","KC_RIGHT"], + ["KC_ESC","KC_F1","KC_F2","KC_F3","KC_F4","KC_F5","KC_F6","KC_F7","KC_F8","KC_F9","KC_F10","KC_F11","KC_F12","KC_TRNS","KC_DEL","BL_STEP","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","_______","KC_TRNS","KC_PSCR","KC_SLCK","KC_PAUS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(2)","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_PGUP","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(1)","KC_LEFT","KC_PGDN","KC_RGHT"], + ["KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","RESET","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(2)","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(1)","KC_TRNS","KC_TRNS","KC_TRNS"] + ] +} +``` + +如上可见，荷载参数里有用于生成固件文件的所有键盘信息。每一个层定义都包含了与键盘 `LAYOUT` 宏定义一致的QMK键码列表数据，若该键盘有多个支持的 `LAYOUT` 宏定义，也可以指定使用的是哪一个。 + +## 提交一个编译job + +若要将键映射配置编译成固件文件，仅需将JSON参数通过POST发送至 `/v1/compile` 节点。下面的示例中我们假设JSON荷载参数已存放在 `json_data` 文件中。 + +``` +$ curl -H "Content-Type: application/json" -X POST -d "$(< json_data)" https://api.qmk.fm/v1/compile +{ + "enqueued": true, + "job_id": "ea1514b3-bdfc-4a7b-9b5c-08752684f7f6" +} +``` + +## 检查状态 + +键映射配置提交后，可以简单地通过 HTTP GET 请求来查询job状态： + +``` +$ curl https://api.qmk.fm/v1/compile/ea1514b3-bdfc-4a7b-9b5c-08752684f7f6 +{ + "created_at": "Sat, 19 Aug 2017 21:39:12 GMT", + "enqueued_at": "Sat, 19 Aug 2017 21:39:12 GMT", + "id": "f5f9b992-73b4-479b-8236-df1deb37c163", + "status": "running", + "result": null +} +``` + +这份信息告诉我们编译job已经提交到队列中且正在执行。job的状态有5种： + +* **failed（失败）**: 编译服务出现问题。 +* **finished（完成）**: 编译已完成，`result` 字段中保存了编译结果。 +* **queued（排队中）**: 键映射job在等待可用的编译服务器。 +* **running（执行中）**: 编译进行中，应当很快就会结束。 +* **unknown（未知）**: 出现了较严重的错误，请给我们[提交一个bug](https://github.com/qmk/qmk_compiler/issues). + +## 确认编译产出 + +编译job完成后请查看 `result` 字段，该字段下保存了如下信息项的哈希表数据： + +* `firmware_binary_url`: 用于刷写的固件文件URL列表 +* `firmware_keymap_url`: `keymap.c` 文件URL列表 +* `firmware_source_url`: 完整的固件源代码URL列表 +* `output`: 编译job的stdout及stderr输出信息，所有错误信息都会在这里。 diff --git a/docs/zh-cn/api_overview.md b/docs/zh-cn/api_overview.md new file mode 100644 index 0000000000..a07cfb7427 --- /dev/null +++ b/docs/zh-cn/api_overview.md @@ -0,0 +1,20 @@ +# QMK API + +<!--- + original document: 0.15.12:docs/api_overview.md + git diff 0.15.12 HEAD -- docs/api_overview.md | cat +--> + +QMK API提供了一套可用于Web及GUI工具可用的异步API，用于实现将任何[QMK](https://qmk.fm/)支持的键盘的键映射方案进行编译。已有的键映射模板支持所有的QMK键码并且不需要额外的C代码需求。键盘的维护团队可以提供新的模板来启用更多功能的支持。 + +## App开发者 + +若您是一位意愿将这套API引入您的程序中的移动端App开发者，请参阅[API使用指引](zh-cn/api_docs.md)。 + +## 键盘维护团队 + +若您希望强化您维护的键盘方案在QMK编译API中的支持，请参阅[键盘支持](zh-cn/reference_configurator_support.md)。 + +## 后端开发者 + +若您对这套API系统本身感兴趣，请参阅[开发环境](zh-cn/api_development_environment.md)搭建环境并继续深入探索[架构总览](zh-cn/api_development_overview.md)。 diff --git a/docs/zh-cn/cli.md b/docs/zh-cn/cli.md new file mode 100644 index 0000000000..22c2db92c8 --- /dev/null +++ b/docs/zh-cn/cli.md @@ -0,0 +1,43 @@ +# QMK CLI :id=qmk-cli + +<!--- + original document: 0.15.12:docs/cli.md + git diff 0.15.12 HEAD -- docs/cli.md | cat +--> + +## 总览 :id=overview + +QMK CLI可以让构建QMK键盘的过程更轻松一些，我们已提供的一批指令可用于简化及流式化地处理一些常见工作，如获取并编译QMK固件，创建新的键映射等。 + +### 依赖项 :id=requirements + +QMK依赖Python 3.6或更高版本。我们已经尽力缩减依赖项，但在[`requirements.txt`](https://github.com/qmk/qmk_firmware/blob/master/requirements.txt)中的依赖项是需安装的包。在安装QMK CLI时这些依赖项也会自动完成安装。 + +### 通过 Homebrew 安装(macOS 及部分 Linux) :id=install-using-homebrew + +若已安装[Homebrew](https://brew.sh)，可以按如下方法安装QMK: + +``` +brew install qmk/qmk/qmk +export QMK_HOME='~/qmk_firmware' # 可选，指定 `qmk_firmware` 的路径 +qmk setup # 拉取 `qmk/qmk_firmware` 并选择性地配置构建环境 +``` + +### 通过 pip 安装 :id=install-using-easy_install-or-pip + +未在以上列出的操作系统可以手动安装QMK。首先确认已安装Python 3.6（或更高版本）及 pip，然后通过如下指令安装QMK： + +``` +python3 -m pip install qmk +export QMK_HOME='~/qmk_firmware' # 可选，指定 `qmk_firmware` 的路径 +qmk setup # 拉取 `qmk/qmk_firmware` 并选择性地配置构建环境 +``` + +### 其它操作系统的安装包 :id=packaging-for-other-operating-systems + +我们正在寻求可以制作维护更多操作系统下可用的 `qmk` 安装包的开发者，若您愿意为您的操作系统制作安装包，请遵循如下指引： + +* 当该系统下的最佳实践与本指引冲突时，请遵循系统的最佳实践方案 + * 但请在注释中列明此处违反这份指引的原因 +* 在 virtualenv 下安装 +* 指引用户去设置 `QMK_HOME` 环境变量，使 |