├── README.md └── guides ├── advanced ├── configuration.md ├── keymaps.md ├── serialization.md └── view-system.md ├── contributing.md ├── converting-a-text-mate-bundle.md ├── converting-a-text-mate-theme.md ├── creating-a-package.md ├── creating-a-theme.md ├── customizing-atom.md ├── getting-started.md └── publishing-a-package.md /README.md: -------------------------------------------------------------------------------- 1 | ![atom](https://atom.io/assets/logo-9624cbf4ef800b9827861e67259e1f5c.png) 2 | --- 3 | 4 | Atom，属于 21 世纪的代码编辑器。 5 | 6 | **译者**：[@郭宇](http://weibo.com/turingou) 7 | **译自**：[Atom.io](http://atom.io) 8 | 9 | ### 目录 10 | 11 | Atom 基础入门： 12 | - [快速指引](./guides/getting-started.md) 13 | - [编辑器配置](./guides/customizing-atom.md) 14 | - [编写插件](./guides/creating-a-package.md) 15 | - [主题设计](./guides/creating-a-theme.md) 16 | - [发布插件](./guides/publishing-a-package.md) 17 | - [转换 TextMate 插件](./guides/converting-a-text-mate-bundle.md) 18 | - [转换 TextMate 主题](./guides/converting-a-text-mate-theme.md) 19 | - [贡献代码](./guides/contributing.md) 20 | 21 | Atom 进阶指引： 22 | - [配置文件](./guides/advanced/configuration.md) 23 | - [快捷键映射](./guides/advanced/keymaps.md) 24 | - [初始序列化](./guides/advanced/serialization.md) 25 | - [视图系统](./guides/advanced/view-system.md) 26 | 27 | ### 前言 28 | 29 | 在 Github，我们一直在构建一款理想的代码编辑器，这款编辑器无所不能，无微不至，既可以随心所欲的定制，又可以信手拈来，开箱即用。 30 | Atom 就是这款现代、亲切又高度定制的编辑器，我们迫不及待地想看看大家能使用它构建出什么好东西。 31 | 32 | ### Web 原生支持 33 | 34 | Atom 是一款基于 Web 技术开发的桌面应用，这意味着它不仅有自己的应用图标，原生菜单与编辑框，控制文件系统的权力，更内置了一个浏览器开发者工具。 35 | 这使得在 Atom 上开发基于 CSS 的主题，或调试 Javascript 都将变得更加得心应手。 36 | 37 | ### 整合 Node.js 38 | 39 | 正因为有了 Node.js 的支持，Atom 得以访问文件系统，运行子进程，甚至在编辑器中启动一个 Web 服务器。 40 | 担心模块不够用？没关系，你可以在 NPM 超过 5 万个模块中任意挑选，随心所欲的构建 Atom Package，这一切依赖于 Atom 与 Node.js 的无缝整合， 41 | 无论是调试 API 接口，处理本地文件，或者进行 DOM 操作，一个函数统统搞掂。 42 | 43 | ### 模块为先 44 | 45 | Atom 由 50 多个开源模块组成，这些模块围绕着 Atom 编辑器的内核模块工作。我们的目标是构建一个高度模块化的系统，模糊使用者与开发者的边接。 46 | 用不惯 Atom 的某个模块？自己写一个更好的，然后上传到 Atom.io 的模块仓库，让全世界的开发者共同受益。 47 | 48 | ### 开箱即用 49 | 50 | 没人希望浪费宝贵的时间配置编辑器，Atom 真正做到了开箱即用，包含所有现代代码编辑器的好用功能： 51 | 52 | 1. 文件浏览器 53 | 2. 快速文件查找工具 54 | 3. 快速字符查找和替换工具 55 | 4. 多光标、多选择支持 56 | 5. 多 Tab 支持 57 | 6. 代码片段提示支持 58 | 7. 代码缩进支持 59 | 8. 简洁好用的 UI 60 | 9. 支持导入 TextMate 主题与插件 61 | 62 | ### 加入 Atom 社区 63 | - Github: [@atom](https://github.com/atom) 64 | - Twitter: [@AtomEditor](http://twitter.com/atomeditor) 65 | - 讨论区: [http://discuss.atom.io](http://discuss.atom.io) 66 | -------------------------------------------------------------------------------- /guides/advanced/configuration.md: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/guo-yu/atom-guide/8bf79f6b342946a978636561f249b9cb4260a733/guides/advanced/configuration.md -------------------------------------------------------------------------------- /guides/advanced/keymaps.md: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/guo-yu/atom-guide/8bf79f6b342946a978636561f249b9cb4260a733/guides/advanced/keymaps.md -------------------------------------------------------------------------------- /guides/advanced/serialization.md: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/guo-yu/atom-guide/8bf79f6b342946a978636561f249b9cb4260a733/guides/advanced/serialization.md -------------------------------------------------------------------------------- /guides/advanced/view-system.md: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/guo-yu/atom-guide/8bf79f6b342946a978636561f249b9cb4260a733/guides/advanced/view-system.md -------------------------------------------------------------------------------- /guides/contributing.md: -------------------------------------------------------------------------------- 1 | 贡献代码 2 | --- 3 | 4 | The following is a set of guidelines for contributing to Atom packages, which are hosted in the Atom Organization on GitHub. If you're unsure which package is causing your problem or if you're having an issue with Atom core, please use the feedback form in the application or email atom@github.com. 5 | 6 | ### 提交 issue 7 | 8 | - Include screenshots and animated GIFs whenever possible; they are immensely helpful. 9 | - Include the behavior you expected and other places you've seen that behavior such as Emacs, vi, Xcode, etc. 10 | - Check the dev tools (alt-cmd-i) for errors and stack traces to include. 11 | - Check Console.app for stack traces to include if reporting a crash. 12 | - Perform a cursory search to see if a similar issue has already been submitted. 13 | 14 | ### Hacking on Packages 15 | 16 | #### Cloning 17 | 18 | The first step is creating your own clone. You can of course do this manually with git, or you can use the apm develop command to create a clone based on the package's repository field in the package.json. 19 | 20 | For example, if you want to make changes to the tree-view package, run the following command: 21 | 22 | ``` 23 | > apm develop tree-view 24 | Cloning https://github.com/atom/tree-view ✓ 25 | Installing modules ✓ 26 | ~/.atom/dev/packages/tree-view -> ~/github/tree-view 27 | ``` 28 | 29 | This clones the tree-view repository to ~/github. If you prefer a different path, specify it via the ATOM_REPOS_HOME environment variable. 30 | 31 | #### Running in Development Mode 32 | 33 | Editing a package in Atom is a bit of a circular experience: you're using Atom to modify itself. What happens if you temporarily break something? You don't want the version of Atom you're using to edit to become useless in the process. For this reason, you'll only want to load packages in development mode while you are working on them. You'll perform your editing in stable mode, only switching to development mode to test your changes. 34 | 35 | To open a development mode window, use the "Application: Open Dev" command, which is normally bound to cmd-shift-o. You can also run dev mode from the command line with atom --dev. 36 | 37 | To load your package in development mode, create a symlink to it in ~/.atom/dev/packages. This occurs automatically when you clone the package with apm develop. You can also run apm link --dev and apm unlink --dev from the package directory to create and remove dev-mode symlinks. 38 | 39 | #### Installing Dependencies 40 | 41 | Finally, you need to install the cloned package's dependencies by running apm install within the package directory. This step is also performed automatically the first time you run apm develop, but you'll want to keep dependencies up to date by running apm update after pulling upstream changes. 42 | 43 | ### 提交 Pull Requests 44 | 45 | #### Code Guidelines 46 | 47 | - Include screenshots and animated GIFs in your pull request whenever possible. 48 | - Follow the CoffeeScript, JavaScript, and CSS styleguides. 49 | - Include thoughtfully-worded, well-structured Jasmine specs. 50 | - Document new code based on the Documentation Styleguide 51 | - End files with a newline. 52 | - Place requires in the following order: 53 | * Built in Node Modules (such as path) 54 | * Built in Atom and Atom Shell Modules (such as atom, shell) 55 | * Local Modules (using relative paths) 56 | - Place class properties in the following order: 57 | * Class methods and properties (methods starting with a @) 58 | * Instance methods and properties 59 | - Avoid platform-dependent code: 60 | * Use require('atom').fs.getHomeDirectory() to get the home directory. 61 | * Use path.join() to concatenate filenames. 62 | * Use os.tmpdir() rather than /tmp when you need to reference the temporary directory. 63 | 64 | #### Commit Message Guidelines 65 | 66 | - Use the present tense ("Add feature" not "Added feature") 67 | - Use the imperative mood ("Move cursor to..." not "Moves cursor to...") 68 | - Limit the first line to 72 characters or less 69 | - Reference issues and pull requests liberally 70 | - Consider starting the commit message with an applicable emoji: 71 | * :lipstick: when improving the format/structure of the code 72 | * :racehorse: when improving performance 73 | * :non-potable_water: when plugging memory leaks 74 | * :memo: when writing docs 75 | * :bulb: Check out the Emoji Cheat Sheet for more ideas. 76 | 77 | #### CoffeeScript Styleguide 78 | 79 | - Use parentheses if it improves code clarity. 80 | - Prefer alphabetic keywords to symbolic keywords: 81 | * a is b instead of a == b 82 | - Avoid spaces inside the curly-braces of hash literals: 83 | * {a: 1, b: 2} instead of { a: 1, b: 2 } 84 | - Set parameter defaults without spaces around the equal sign: 85 | * clear = (count=1) -> instead of clear = (count = 1) -> 86 | - Include a single line of whitespace between methods. 87 | 88 | #### Documentation Styleguide 89 | 90 | - Use TomDoc. 91 | - Use Markdown. 92 | - Reference methods and classes in markdown with the custom {} notation: 93 | * Reference classes with {ClassName} 94 | * Reference instance methods with {ClassName::methodName} 95 | * Reference class methods with {ClassName.methodName} 96 | 97 | ##### Example 98 | 99 | ``` 100 | # Public: Disable the package with the given name. 101 | # 102 | # This method emits multiple events: 103 | # 104 | # * `package-will-be-disabled` - before the package is disabled. 105 | # * `package-disabled` - after the package is disabled. 106 | # 107 | # name - The {String} name of the package to disable. 108 | # options - The {Object} with disable options (default: {}): 109 | # :trackTime - `true` to track the amount of time disabling took. 110 | # :ignoreErrors - `true` to catch and ignore errors thrown. 111 | # callback - The {Function} to call after the package has been disabled. 112 | # 113 | # Returns `undefined`. 114 | disablePackage: (name, options, callback) -> 115 | ``` 116 | -------------------------------------------------------------------------------- /guides/converting-a-text-mate-bundle.md: -------------------------------------------------------------------------------- 1 | 转换 TextMate 插件 2 | --- 3 | 4 | This guide will show you how to convert a TextMate bundle to an Atom package. 5 | 6 | Converting a TextMate bundle will allow you to use its editor preferences, snippets, and colorization inside Atom. 7 | 8 | ### 安装 apm 9 | 10 | The apm command line utility that ships with Atom supports converting a TextMate bundle to an Atom package. 11 | 12 | Check that you have apm installed by running the following command in your terminal: 13 | 14 | ``` 15 | apm help init 16 | ``` 17 | 18 | You should see a message print out with details about the apm init command. 19 | 20 | If you do not, launch Atom and run the Atom > Install Shell Commmands menu to install the apm and atom commands. 21 | 22 | ### 开始转换 23 | 24 | Let's convert the TextMate bundle for the R programming language. You can find other existing TextMate bundles here. 25 | 26 | You can convert the R bundle with the following command: 27 | 28 | ``` 29 | apm init --package ~/.atom/packages/language-r \ 30 | --convert https://github.com/textmate/r.tmbundle 31 | ``` 32 | You can now browse to ~/.atom/packages/language-r to see the converted bundle. 33 | 34 | :tada: Your new package is now ready to use, launch Atom and open a .r file in the editor to see it in action! 35 | 36 | ### 延伸阅读 37 | 38 | Check out Publishing a Package for more information on publishing the package you just created to atom.io. 39 | -------------------------------------------------------------------------------- /guides/converting-a-text-mate-theme.md: -------------------------------------------------------------------------------- 1 | 转换 TextMate 插件 2 | --- 3 | 4 | This guide will show you how to convert a TextMate theme to an Atom theme. 5 | 6 | ### 与原生主题的区别 7 | 8 | TextMate themes use plist files while Atom themes use CSS or LESS to style the UI and syntax in the editor. 9 | 10 | The utility that converts the theme first parses the theme's plist file and then creates comparable CSS rules and properties that will style Atom similarly. 11 | 12 | ### 安装 apm 13 | 14 | The apm command line utility that ships with Atom supports converting a TextMate theme to an Atom theme. 15 | 16 | Check that you have apm installed by running the following command in your terminal: 17 | 18 | ``` 19 | apm help init 20 | ``` 21 | 22 | You should see a message print out with details about the apm init command. 23 | 24 | If you do not, launch Atom and run the Atom > Install Shell Commmands menu to install the apm and atom commands. 25 | 26 | You can now run apm help init to see all the options for initializing new packages and themes. 27 | 28 | ### 开始转换 29 | 30 | Download the theme you wish to convert, you can browse existing TextMate themes here. 31 | 32 | Now, let's say you've downloaded the theme to ~/Downloads/MyTheme.tmTheme, you can convert the theme with the following command: 33 | 34 | ``` 35 | apm init --theme ~/.atom/packages/my-theme \ 36 | --convert ~/Downloads/MyTheme.tmTheme 37 | ``` 38 | You can browse to ~/.atom/packages/my-theme to see the converted theme. 39 | 40 | ### 激活主题 41 | 42 | Now that your theme is installed to ~/.atom/packages you can enable it by launching Atom and selecting the Atom > Preferences... menu. 43 | 44 | Select the Themes link on the left side and choose My Theme from the Syntax Theme dropdown menu to enable your new theme. 45 | 46 | :tada: Your theme is now enabled, open an editor to see it in action! 47 | 48 | ### 延伸阅读 49 | 50 | Check out Publishing a Package for more information on publishing the theme you just created to atom.io. 51 | -------------------------------------------------------------------------------- /guides/creating-a-package.md: -------------------------------------------------------------------------------- 1 | 编写插件 2 | --- 3 | 4 | 插件系统是 Atom 的核心组成部分，几乎所有不属于编辑器内核的功能，在 Atom 中，我们都使用插件的方式来进行组织。这些我们默认提供的插件，包括文件树，状态栏，语法高亮等等模块。 5 | 6 | 插件可以包括很多种改变编辑器行为的资源，一个基本的插件结构应如下所示： 7 | 8 | ``` 9 | my-package/ 10 | grammars/ 11 | keymaps/ 12 | lib/ 13 | menus/ 14 | spec/ 15 | snippets/ 16 | stylesheets/ 17 | index.coffee 18 | package.json 19 | ``` 20 | 21 | 当然，并不是所有的插件都包括（或者需要）这些目录和文件。 22 | 23 | Atom 提供了一个 [简单的教程](#) 引导你创建自己的第一个插件。 24 | 25 | 这里也有一些其他的教程关于如何转换 TextMate 插件和主题到 Atom 平台。 26 | 27 | ### package.json 28 | 29 | 和 npm 模块相似， Atom 插件在根目录也包括一个主描述文件 `package.json`。这个文件定义了插件的元数据，比如主文件路径，模块依赖，或者插件中资源文件的加载顺序等等。 30 | 31 | 除了 npm 模块描述中定义的配置项之外，Atom 还提供这些配置项： 32 | 33 | - main (必要): 插件的入口文件，即对外暴露接口的文件 34 | - stylesheets (可选): 一个定义了样式表先后加载顺序的文件数组，如果没有填写这个配置项，Atom 会默认加载 stylesheets 文件夹中的样式表，并按照字母表排序。 35 | - keymaps(可选): 一个定义了快捷键映射先后加载顺序的文件数组，如果没有填写这个配置项，Atom 会默认加载 keymaps 文件夹中的快捷键映射，并按照字母表排序。 36 | - menus(可选): 一个定义了菜单映射先后加载顺序的文件数组，如果没有填写这个配置项，Atom 会默认加载 menus 文件夹中的菜单映射，并按照字母表排序。 37 | - snippets (可选): 一个定义了代码片段先后加载顺序的文件数组，如果没有填写这个配置项，Atom 会默认加载 snippets 文件夹中的代码片段，并按照字母表排序。 38 | - activationEvents (可选): 一个激活插件的事件数组。你可以在这里定义何时你的插件被激活或者触发。 39 | 40 | ### 插件源码 41 | 42 | 如果你想定义 Atom 的行为，插件的主入口文件必须包括并暴露一个顶级模块。注意，插件的主入口文件可能是 index.coffee，也可以是在 package.json 中定义的 main 文件，我们建议把插件的源码放置在插件的 lib 目录，并在主入口文件引用。 43 | 44 | 插件的顶级模块是一个单体对象 (singleton object)，这个对象管理插件的生命周期，也就是说，甚至你的插件生成了十个不同的视图，并将他们 append 到 DOM 的不用部分，这些试图也是由这个对象进行管理。 45 | 46 | 这个对象必须包括这些方法： 47 | 48 | - activate(state): 这个必要的方法会在插件激活时被触发。Atom 会将上次编辑器初始化并执行 serialize() 后的状态传入这个函数。这个函数适合进行某些初始化操作，比如初始化 DOM 元素或者绑定插件中的事件。 49 | 50 | - serialize(): 这个可选的方法在编辑器关闭时被执行，如果它返回一个 JSON 表述此时模块的状态，在编辑器下次打开时，这些数据会被传入该插件的 activate 函数中，使得插件重新返回当时的状态或视图变得可能。 51 | 52 | - deactivate(): 这个可选的方法在编辑器窗口关闭时被执行。如果你的插件在处理某些外部资源或者监听文件的变动，应当在此时销毁这些函数或者监视器。 53 | 如果只是对当前编辑床可起作用，则无需进行处理，Atom 将自动回收 54 | 55 | ### 范例插件 56 | 57 | 范例插件的文件结构可能如下所示： 58 | 59 | ``` 60 | my-package/ 61 | package.json 62 | index.coffee 63 | lib/ 64 | my-package.coffee 65 | ``` 66 | index.coffee 可能像这样： 67 | 68 | ``` 69 | module.exports = require "./lib/my-package" 70 | ``` 71 | my-package/my-package.coffee 可能是这样： 72 | 73 | ``` 74 | module.exports = 75 | activate: (state) -> # ... 76 | deactivate: -> # ... 77 | serialize: -> # ... 78 | ``` 79 | 80 | 除了插件的基本结构，插件代码都有使用 Atom API 的权限，开发者需要注意，Atom 的 API 还在早期开发阶段，这意味着 API 可能有计划中的更新，比如区分公共 API 和 私有 API 等等。如果你需要一个现在暂时没有的 API 用于开发，欢迎给 Atom 贡献代码。我们的目标是建立一套开发者真正需要的 API 的体系。 81 | 82 | ### 插件样式表 83 | 84 | Stylesheets for your package should be placed in the stylesheets directory. Any stylesheets in this directory will be loaded and attached to the DOM when your package is activated. Stylesheets can be written as CSS or LESS. 85 | 86 | Ideally, you won't need much in the way of styling. We've provided a standard set of components which define both the colors and UI elements for any package that fits into Atom seamlessly. You can view all of Atom's UI components by opening the styleguide: open the command palette (cmd-shift-P) and search for styleguide, or just type cmd-ctrl-G. 87 | 88 | If you do need special styling, try to keep only structural styles in the package stylesheets. If you must specify colors and sizing, these should be taken from the active theme's ui-variables.less. For more information, see the theme variables docs. If you follow this guideline, your package will look good out of the box with any theme! 89 | 90 | An optional stylesheets array in your package.json can list the stylesheets by name to specify a loading order; otherwise, stylesheets are loaded alphabetically. 91 | 92 | ### 插件快捷键 93 | 94 | It's recommended that you provide key bindings for commonly used actions for your extension, especially if you're also adding a new command: 95 | 96 | ``` 97 | '.tree-view-scroller': 98 | 'ctrl-V': 'changer:magic' 99 | ``` 100 | Keymaps are placed in the keymaps subdirectory. By default, all keymaps are loaded in alphabetical order. An optional keymaps array in your package.json can specify which keymaps to load and in what order. 101 | 102 | Keybindings are executed by determining which element the keypress occurred on. In the example above, changer:magic command is executed when pressing ctrl-V on the .tree-view-scroller element. 103 | 104 | See the main keymaps documentation for more detailed information on how keymaps work. 105 | 106 | ### 插件菜单 107 | 108 | Menus are placed in the menus subdirectory. By default, all menus are loaded in alphabetical order. An optional menus array in your package.json can specify which menus to load and in what order. 109 | 110 | #### 应用菜单 111 | 112 | It's recommended that you create an application menu item for common actions with your package that aren't tied to a specific element: 113 | 114 | ``` 115 | 'menu': [ 116 | { 117 | 'label': 'Packages' 118 | 'submenu': [ 119 | { 120 | 'label': 'My Package' 121 | 'submenu': [ 122 | { 123 | 'label': 'Toggle' 124 | 'command': 'my-package:toggle' 125 | } 126 | ] 127 | } 128 | ] 129 | } 130 | ] 131 | ``` 132 | 133 | To add your own item to the application menu, simply create a top level menu key in any menu configuration file in menus. This can be a JSON or CSON file. 134 | 135 | The menu templates you specify are merged with all other templates provided by other packages in the order which they were loaded. 136 | 137 | ### 上下文菜单 138 | 139 | It's recommended to specify a context menu item for commands that are linked to specific parts of the interface, like adding a file in the tree-view: 140 | 141 | ``` 142 | 'context-menu': 143 | '.tree-view': 144 | 'Add file': 'tree-view:add-file' 145 | '.workspace': 146 | 'Inspect Element': 'core:inspect' 147 | ``` 148 | 149 | To add your own item to the application menu simply create a top level context-menu key in any menu configuration file in menus. This can be a JSON or CSON file. 150 | 151 | Context menus are created by determining which element was selected and then adding all of the menu items whose selectors match that element (in the order which they were loaded). The process is then repeated for the elements until reaching the top of the DOM tree. 152 | 153 | In the example above, the Add file item will only appear when the focused item or one of its parents has the tree-view class applied to it. 154 | 155 | ### 代码片段 156 | 157 | An extension can supply language snippets in the snippets directory which allows the user to enter repetitive text quickly: 158 | 159 | ``` 160 | ".source.coffee .specs": 161 | "Expect": 162 | prefix: "ex" 163 | body: "expect($1).to$2" 164 | "Describe": 165 | prefix: "de" 166 | body: """ 167 | describe "${1:description}", -> 168 | ${2:body} 169 | """ 170 | ``` 171 | 172 | A snippets file contains scope selectors at its top level (.source.coffee .spec). Each scope selector contains a hash of snippets keyed by their name (Expect, Describe). Each snippet also specifies a prefix and a body key. The prefix represents the first few letters to type before hitting the tab key to autocomplete. The body defines the autofilled text. You can use placeholders like $1, $2, to indicate regions in the body the user can navigate to every time they hit tab. 173 | 174 | All files in the directory are automatically loaded, unless the package.json supplies a snippets key. As with all scoped items, snippets loaded later take precedence over earlier snippets when two snippets match a scope with the same specificity. 175 | 176 | ### 语法分析 177 | 178 | If you're developing a new language grammar, you'll want to place your file in the grammars directory. Each grammar is a pairing of two keys, match and captures. match is a regular expression identifying the pattern to highlight, while captures is an object representing what to do with each matching group. 179 | 180 | For example: 181 | 182 | ``` 183 | { 184 | 'match': '(?:^|\\s)(__[^_]+__)' 185 | 'captures': 186 | '1': 'name': 'markup.bold.gfm' 187 | } 188 | ``` 189 | 190 | This indicates that the first matching capture ((__[^_]+__)) should have the markup.bold.gfm token applied to it. 191 | 192 | To capture a single group, simply use the name key instead: 193 | 194 | ``` 195 | { 196 | 'match': '^#{1,6}\\s+.+$' 197 | 'name': 'markup.heading.gfm' 198 | } 199 | ``` 200 | This indicates that Markdown header lines (#, ##, ###) should be applied with the markup.heading.gfm token. 201 | 202 | More information about the significance of these tokens can be found in section 12.4 of the TextMate Manual. 203 | 204 | Your grammar should also include a filetypes array, which is a list of file extensions your grammar supports: 205 | 206 | ``` 207 | 'fileTypes': [ 208 | 'markdown' 209 | 'md' 210 | 'mkd' 211 | 'mkdown' 212 | 'ron' 213 | ] 214 | ``` 215 | ### 外部资源 216 | 217 | It's common to ship external resources like images and fonts in the package, to make it easy to reference the resources in HTML or CSS, you can use the atom protocol URLs to load resources in the package. 218 | 219 | The URLs should be in the format of atom://package-name/relative-path-to-package-of-resource, for example, the atom://image-view/images/transparent-background.gif would be equivalent to ~/.atom/packages/image-view/images/transparent-background.gif. 220 | 221 | You can also use the atom protocol URLs in themes. 222 | 223 | ### 编写插件测试 224 | 225 | Your package should have tests, and if they're placed in the spec directory, they can be run by Atom. 226 | 227 | Under the hood, Jasmine executes your tests, so you can assume that any DSL available there is also available to your package. 228 | 229 | ### 运行插件测试 230 | 231 | Once you've got your test suite written, you can run it by pressing cmd-alt-ctrl-p or via the Developer > Run Package Specs menu. 232 | 233 | You can also use the apm test command to run them from the command line. It prints the test output and results to the console and returns the proper status code depending on whether the tests passed or failed. 234 | 235 | ### 发布插件 236 | 237 | Atom bundles a command line utility called apm which can be used to publish Atom packages to the public registry. 238 | 239 | Once your package is written and ready for distribution you can run the following to publish your package: 240 | 241 | ``` 242 | cd my-package 243 | apm publish minor 244 | ``` 245 | 246 | This will update your package.json to have a new minor version, commit the change, create a new Git tag, and then upload the package to the registry. 247 | 248 | Run apm help publish to see all the available options and apm help to see all the other available commands. 249 | -------------------------------------------------------------------------------- /guides/creating-a-theme.md: -------------------------------------------------------------------------------- 1 | 主题设计 2 | --- 3 | 4 | Atom's interface is rendered using HTML, and it's styled via LESS. Don't worry if you haven't heard of LESS before; it's just like CSS, but with a few handy extensions. 5 | 6 | Atom supports two types of themes: UI and syntax. UI themes style elements such as the tree view, the tabs, drop-down lists, and the status bar. Syntax themes style the code inside the editor. 7 | 8 | Themes can be installed and changed from the settings view which you can open by selecting the Atom > Preferences... menu and navigating to the Themes section on the left hand side. 9 | 10 | ### 设计主题前的准备 11 | 12 | Themes are pretty straightforward but it's still helpful to be familiar with a few things before starting: 13 | 14 | - LESS is a superset of CSS, but it has some really handy features like variables. If you aren't familiar with its syntax, take a few minutes to familiarize yourself. 15 | - You may also want to review the concept of a package.json, too. This file is used to help distribute your theme to Atom users. 16 | - Your theme's package.json must contain a "theme" key with a value of "ui" or "syntax" for Atom to recognize and load it as a theme. 17 | - You can find existing themes to install or fork on atom.io. 18 | 19 | ### 编写语法高亮主题 20 | 21 | Let's create your first theme. 22 | 23 | To get started, hit cmd-shift-P, and start typing "Generate Syntax Theme" to generate a new theme package. Select "Generate Syntax Theme," and you'll be asked for the path where your theme will be created. Let's call ours motif-syntax. Tip: syntax themes should end with -syntax. 24 | 25 | Atom will pop open a new window, showing the motif-syntax theme, with a default set of folders and files created for us. If you open the settings view (cmd-,) and navigate to the Themes section on the left, you'll see the Motif theme listed in the Syntax Theme drop-down. Select it from the menu to activate it, now when you open an editor you should see that your new motif-syntax theme in action. 26 | 27 | Open up stylesheets/colors.less to change the various colors variables which have been already been defined. For example, turn @red into #f4c2c1. 28 | 29 | Then open stylesheets/base.less and modify the various selectors that have been already been defined. These selectors style different parts of code in the editor such as comments, strings and the line numbers in the gutter. 30 | 31 | As an example, let's make the .gutter background-color into @red. 32 | 33 | Reload Atom by pressing cmd-alt-option-L to see the changes you made reflected in your Atom window. Pretty neat! 34 | 35 | Tip: You can avoid reloading to see changes you make by opening an atom window in dev mode. To open a Dev Mode Atom window run atom --dev . in the terminal, use cmd-shift-o or use the View > Developer > Open in Dev Mode menu. When you edit your theme, changes will instantly be reflected! 36 | 37 | 38 | ### 编写主题界面 39 | 40 | Interface themes must provide a ui-variables.less file which contains all of the variables provided by the core themes. 41 | 42 | To create an interface UI theme, do the following: 43 | 44 | 1. Fork one of the following repositories: 45 | - atom-dark-ui 46 | - atom-light-ui 47 | 2. Clone the forked repository to the local filesystem 48 | 3. Open a terminal in the forked theme's directory 49 | 4. Open your new theme in a Dev Mode Atom window run atom --dev . in the terminal or use the View > Developer > Open in Dev Mode menu 50 | 5. Change the name of the theme in the theme's package.json file 51 | 6. Name your theme end with a -ui. i.e. super-white-ui 52 | 7. Run apm link to symlink your repository to ~/.atom/packages 53 | 8. Reload Atom using cmd-alt-ctrl-L 54 | 9. Enable the theme via UI Theme drop-down in the Themes section of the settings view 55 | 10. Make changes! Since you opened the theme in a Dev Mode window, changes will be instantly reflected in the editor without having to reload 56 | 57 | ### 主题开发工作流 58 | 59 | There are a few of tools to help make theme development faster and easier. 60 | 61 | #### Live Reload 62 | 63 | Reloading by hitting cmd-alt-ctrl-L after you make changes to your theme is less than ideal. Atom supports live updating of styles on Dev Mode Atom windows. 64 | 65 | To enable a Dev Mode window: 66 | 67 | 1. Open your theme directory in a dev window by either going to the View > Developer > Open in Dev Mode menu or by hitting the cmd-shift-o shortcut 68 | 69 | 2. Make a change to your theme file and save it. Your change should be immediately applied! 70 | 71 | If you'd like to reload all the styles at any time, you can use the shortcut cmd-ctrl-shift-r. 72 | 73 | #### 开发者工具 74 | 75 | Atom is based on the Chrome browser, and supports Chrome's Developer Tools. You can open them by selecting the View > Toggle Developer Tools menu, or by using the cmd-alt-i shortcut. 76 | 77 | The dev tools allow you to inspect elements and take a look at their CSS properties. 78 | 79 | ![](https://f.cloud.github.com/assets/69169/1347391/2d51f91c-36af-11e3-806f-f7b334af43e9.png) 80 | 81 | Check out Google's extensive tutorial for a short introduction. 82 | 83 | #### 设计风格指导 84 | 85 | If you are creating an interface theme, you'll want a way to see how your theme changes affect all the components in the system. The styleguide is a page that renders every component Atom supports. 86 | 87 | To open the styleguide, open the command palette (cmd-shift-P) and search for styleguide, or use the shortcut cmd-ctrl-shift-g. 88 | 89 | ![](https://f.cloud.github.com/assets/69169/1347390/2d431d98-36af-11e3-8f8e-3f4ce1e67adb.png) 90 | -------------------------------------------------------------------------------- /guides/customizing-atom.md: -------------------------------------------------------------------------------- 1 | 编辑器配置 2 | --- 3 | 4 | 变更编辑器设定，更换主题，或者安装插件都可以通过快捷键 `cmd-,` 打开 Atom 配置页面。 5 | 6 | ### 切换主题 7 | 8 | Atom 自带两套主题和语法主题。当然我们鼓励大家编写更适合自己的主题。 9 | 10 | 更换或者激活想要使用的主题也可以通过快捷键打开 Atom 配置页面，选择左侧的主题面板，即可看到相关操作说明。在这个面板，不仅可以管理现有的主题， 11 | 还可以在主题市场搜索可用的主题并一键安装到本地。 12 | 13 | ### 安装插件 14 | 15 | 配置页面左侧的插件面板也可以快速安装新插件。在这里显示的插件都是注册并发布到 Atom.io 插件市场的模块。 16 | 除了使用管理面板管理和安装插件，你也可以使用 `apm` 命令行工具，使用命令行工具之前，确认是否安装了 `apm`： 17 | 18 | ``` 19 | apm help install 20 | ``` 21 | 22 | 如果你看到了一行关于 apm install 操作的帮助提示，说明你已经成功了安装了 apm。 23 | 如果你并没有看到有效输出，那么打开 Atom ，在顶部左侧的 Atom 菜单中寻找到 Install Shell Commmands 菜单，点击安装 apm 24 | 25 | 使用 apm 按照如下的方式安装插件： 26 | 27 | - apm install 安装某个插件的最新版本 28 | - apm install @ 安装某个插件的指定版本 29 | 30 | 比如，我们需要安装 emmet 插件的 0.1.5 版本，则需要运行命令 `apm install emmet@0.1.5`，插件会被安装到这个地址 `~/.atom/packages`。 31 | 32 | 还有其他的命令帮助你使用 apm 搜索符合某个关键词的插件或者查询某个插件的详细信息： 33 | 34 | - apm search coffee 搜索与 coffee 关键词相关的插件 35 | - apm view emmet 查询 emmet 插件的详细信息 36 | 37 | ### 定义快捷键 38 | 39 | Atom 快捷键映射表看起来就像样式表。这意味着编写快捷键映射也需要有一个选择符，以匹配相应的事件、行为或者指定上下文。 40 | 这里有一个简单的快捷键映射例子： 41 | 42 | ``` 43 | '.editor': 44 | 'enter': 'editor:newline' 45 | 46 | '.mini.editor input': 47 | 'enter': 'core:confirm' 48 | ``` 49 | 50 | 这个快捷键 map 定义了 回车 (enter) 在两种不同场景下的行为。在普遍的模式下，回车触发一个 换行 (editor:newline) 事件，导致编辑器开启新的一行。但如果在已选择一个列表的时候触发回车，编辑器就会触发 core:confirm 事件。(But if the same keystroke occurs inside of a select list's mini-editor, it instead emits the core:confirm event based on the binding in the more-specific selector.) 51 | 52 | 默认的快捷键映射表是 `~/.atom/keymap.cson`，这个文件会在 Atom 启动的时候最晚被加载，以确保用户修改这个文件的映射会覆盖 Atom 默认的配置以及第三方插件的快捷键配置。 53 | 54 | 当然，如果你不想通过其他方式打开，也可以在顶部菜单 `Atom > Open Your Keymap menu` 中直接打开。 55 | 56 | 打开配置面板的快捷键映射面板，你可以看到所有可用的快捷键，以方便自定义属于自己的快捷键。 57 | 58 | ### 进阶配置 59 | 60 | Atom 的主配置文件在 `~/.atom/config.cson`，CSON 是一种 CoffeeScript-style JSON，看起来像这样： 61 | 62 | ``` 63 | 'core': 64 | 'excludeVcsIgnoredPaths': true 65 | 'editor': 66 | 'fontSize': 18 67 | ``` 68 | 配置文件由包名称进行分组，当然，也包括两个缺省的类别，那就是 核心配置(core) 和 编辑器(editor) 配置。 69 | 也可以在顶部菜单中找到 Atom > Open Your Config 打开配置文件。 70 | 71 | ### 配置项清单 72 | 73 | - core 74 | - editor 75 | - fuzzyFinder 76 | - whitespace 77 | - wrap-guide 78 | 79 | ### 快速定义指引 80 | 81 | #### init.coffee 82 | 83 | 当 Atom 本身加载完毕时，它会首先运行 `~/.atom/init.coffee` 文件，以便于用户可以快速的进行某些配置项的自定义，而不用修改配置文件。 84 | 并且，这个文件有访问所有 Atom API 的权限。如果你在这个文件里编写了太多的配置，我们还是建议您为这些配置单独新建一个模块。 85 | 86 | 也可以通过访问菜单 Atom > Open Your Init Script 打开这个文件。 87 | 88 | 举个例子，如果我们希望在 Atom 加载完毕后「哔」一声提示用户，我们可以在 `~/.atom/init.coffee` 加入这段代码： 89 | 90 | ``` 91 | atom.beep() 92 | ``` 93 | 另外，如果你不喜欢编写 CoffeeScript，也可以将这个配置文件命名为 init.js 并编写原生 JavaScript 代码。 94 | 95 | #### styles.less 96 | 97 | 同样的，如果你想要编写一些简单而粗暴的自定义样式表，而非新建一整个主题，也可以通过编辑配置文件 `~/.atom/styles.less` 来完成。 98 | 99 | 也可以通过访问菜单 Atom > Open Your Stylesheet 打开这个文件 100 | 101 | 举个例子，如果需要改变光标的颜色，你可以在 ~/.atom/styles.less 文件中加入这行代码： 102 | 103 | ``` 104 | .editor .cursor { 105 | border-color: pink; 106 | } 107 | ``` 108 | 109 | 如果你不熟悉 LESS，可以在[这里](#)查阅到更多关于它的信息。 110 | 111 | 另外，如果你不喜欢编写 LESS，也可以将这个配置文件命名为 styles.css 并编写 css。 112 | -------------------------------------------------------------------------------- /guides/getting-started.md: -------------------------------------------------------------------------------- 1 | 快速指引 2 | --- 3 | 4 | 欢迎来到 Atom！本指南提供一份入门简介，以便你能尽快上手。其中包括 Atom 的配置、主题以及扩展的介绍。 5 | 6 | ### 命令面板 7 | 8 | 在 Atom 中，如果只有一个快捷键你需要记住，那就是 `cmd-shift-P`。你可以随时按 `cmd-shift-P` 来调出一些和当前界面元素有关的命令列表（和它们的快捷键）。这是一个探索系统的极好方式，还能互动的学习快捷键。如需添加或更改快捷键的绑定信息，请参阅[自定义快捷键](https://github.com/turingou/atom-guide/blob/master/guides/customizing-atom.md)部分。 9 | 10 | ### Atom 基础 11 | 12 | #### 使用文件 13 | 14 | 一个 Atom 窗口只能打开磁盘上的一个目录。如果你是用 `atom` 命令在命令行启动的它，并且没有指定目录，则 Atom 默认会在窗口中打开当前目录。当前目录中的所有文件都会在左边的树状视图中显示，你可以对它进行一系列相关的文件操作。 15 | 16 | ##### 查找文件 17 | 18 | 用模糊搜索是查找文件的最快方式。只需按 `cmd-t`，然后输入你要找的文件名就行。如果你想找的文件已经打开，你可以按 `cmd-b` 在已打开文件列表中搜索。如果你正使用 Git，你可以用 `cmd-shift-b` 来搜寻你库中的任意文件。 19 | 20 | 你还可以利用左面的树状视图找寻你所要的文件。弹出和隐藏树状视图按 `cmd-\`，切换焦点到树状视图按 `ctrl-0`。 21 | 22 | ##### 新建、移动、删除文件 23 | 24 | 新建，移动，删除文件有两种方式，一种是右击树状视图弹出菜单，选择相应的选项。另一种是在树状视图中选中文件，按 `a` 新建文件，按 `m` 移动文件，按 `delete` 来删除。 25 | 26 | #### 搜索 27 | 28 | ##### 查找和替换 29 | 30 | 文件内查找用 `cmd-f`，项目中跨文件查找用 `cmd-shift-f`。 31 | 32 | ##### 符号跳转 33 | 34 | 你可以按 `cmd-r` 跳转到当前文件中某个函数的定义。使用方式和 `cmd-t` 类似，区别在于 `cmd-r` 提取的是当前文件中的函数列表。 35 | 36 | 如果你要在整个项目中查找标签文件，用 `cmd-shift-r`。首先你得确定项目中有你所要查找的标签文件。你可以通过安装 [ctags](http://ctags.sourceforge.net/)，然后在项目根目录下执行 `ctags -R src/` 来生成标签。想用 [Homebrew](http://brew.sh/)？只需执行 `brew install ctags`。 37 | 38 | 你还可以通过修改 `.ctags` 文件来自己定义标签的生成方式。这里有个[很好的范例](https://github.com/atom/symbols-view/blob/master/lib/.ctags)以供参考。 39 | 40 | #### 拆分窗口 41 | 42 | 你可以在编辑器的任意窗口中分别用 `cmd-k right` 或 `cmd-k down` 来水平或垂直地拆分窗口。一旦你有一个拆分窗口，你就可以通过 `cmd-k cmd-right` 或 `cmd-k cmd-down` 来切换。要关闭一个拆分窗口，你可以按一次 `meta-w`，关闭多个就需要按多次 `meta-w`。你还可以在设置界面里，将拆分窗口设置成内容为空时自动关闭。 43 | 44 | #### 折叠代码 45 | 46 | 你可以单击行数栏中出现的小箭头来折叠和打开代码。当然还可以通过快捷键 `alt-cmd-[` 和 `alt-cmd-]`。如果你想把代码全部折叠，按 `alt-cmd-shift-{`。全部打开，按 `alt-cmd-shift-}`。你还可以用 `cmd-k cmd-N` 打开特定的层级，其中 N 是你要打开的第几层。 47 | 48 | #### 自动换行 49 | 50 | 如果你想切换为自动换行，按 `cmd-shift-P` 调出命令面板，输入 "wrap" 找到正确的命令。Atom 默认是根据编辑器宽度自动换行，如果你想给它指定一个自动换行的宽度，可以在设置中找到 "Wrap at preferred line length" 来修改。 51 | 52 | ### 基本 Atom 配置 53 | 54 | 按 `cmd-,`打开设置视图。这是更改设置，安装软件包，并更改主题的地方。 55 | 56 | 对于更高级的配置请参见[定制指南](https://github.com/turingou/atom-guide/blob/master/guides/customizing-atom.md)。 57 | -------------------------------------------------------------------------------- /guides/publishing-a-package.md: -------------------------------------------------------------------------------- 1 | 发布插件 2 | --- 3 | 4 | This guide will show you how to publish a package or theme to the atom.io package registry. 5 | 6 | Publishing a package allows other people to install it and use it in Atom. It is a great way to share what you've made and get feedback and contributions from others. 7 | 8 | This guide assumes your package's name is my-package and but you should pick a better name. 9 | 10 | ### 安装 apm 11 | 12 | The apm command line utility that ships with Atom supports publishing packages to the atom.io registry. 13 | 14 | Check that you have apm installed by running the following command in your terminal: 15 | 16 | ``` 17 | apm help publish 18 | ``` 19 | You should see a message print out with details about the apm publish command. 20 | 21 | If you do not, launch Atom and run the Atom > Install Shell Commmands menu to install the apm and atom commands. 22 | 23 | ### 发布准备 24 | 25 | If you've followed the steps in the your first package doc then you should be ready to publish and you can skip to the next step. 26 | 27 | If not, there are a few things you should check before publishing: 28 | 29 | - Your package.json file has name, description, and repository fields. 30 | - Your package.json file has a version field with a value of "0.0.0". 31 | - Your package.json file has an engines field that contains an entry for Atom such as: "engines": {"atom": ">=0.50.0"}. 32 | - Your package has a README.md file at the root. 33 | - Your package is in a Git repository that has been pushed to GitHub. Follow this guide if your package isn't already on GitHub. 34 | 35 | ### 发布插件 36 | 37 | Before you publish a package it is a good idea to check ahead of time if a package with the same name has already been published to atom.io. You can do that by visiting http://atom.io/packages/my-package to see if the package already exists. If it does, update your package's name to something that is available before proceeding. 38 | 39 | Now let's review what the apm publish command does: 40 | 41 | - Registers the package name on atom.io if it is being published for the first time. 42 | - Updates the version field in the package.json file and commits it. 43 | - Creates a new Git tag for the version being published. 44 | - Pushes the tag and current branch up to GitHub. 45 | - Updates atom.io with the new version being published. 46 | 47 | Now run the following commands to publish your package: 48 | 49 | ``` 50 | cd ~/github/my-package 51 | apm publish minor 52 | ``` 53 | 54 | If this is the first package you are publishing, the apm publish command may prompt you for your GitHub username and password. This is required to publish and you only need to enter this information the first time you publish. The credentials are stored securely in your keychain once you login. 55 | 56 | :tada: Your package is now published and available on atom.io. Head on over to http://atom.io/packages/my-package to see your package's page. 57 | 58 | The minor option to the publish command tells apm to increment the second digit of the version before publishing so the published version will be 0.1.0 and the Git tag created will be v0.1.0. 59 | 60 | In the future you can run apm publish major to publish the 1.0.0 version but since this was the first version being published it is a good idead to start with a minor release. 61 | 62 | ### 延伸阅读 63 | 64 | Check out [semantic versioning](http://semver.org/) to learn more about versioning your package releases. 65 | --------------------------------------------------------------------------------