From 5d092731e509e4fd8ad50f7922e4f59fbfd6533d Mon Sep 17 00:00:00 2001 From: Maizify Date: Sat, 4 Jun 2016 21:25:15 +0800 Subject: [PATCH] add CN docs --- README.md | 6 +- README_CN.md | 115 ++++---------------- doc/a_doc_index.md | 14 +++ doc/a_doc_index_CN.md | 14 +++ doc/plugin_building_a_plugin.md | 18 ++-- doc/plugin_building_a_plugin_CN.md | 111 +++++++++++++++++++ doc/plugin_event_list.md | 2 +- doc/plugin_event_list_CN.md | 165 +++++++++++++++++++++++++++++ doc/plugin_getting_started.md | 5 +- doc/plugin_getting_started_CN.md | 24 +++++ doc/tutorial.md | 2 + doc/tutorial_CN.md | 104 ++++++++++++++++++ 12 files changed, 476 insertions(+), 104 deletions(-) create mode 100644 doc/a_doc_index.md create mode 100644 doc/a_doc_index_CN.md create mode 100644 doc/plugin_building_a_plugin_CN.md create mode 100644 doc/plugin_event_list_CN.md create mode 100644 doc/plugin_getting_started_CN.md create mode 100644 doc/tutorial_CN.md diff --git a/README.md b/README.md index 9a163d22..c37c2d7b 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,7 @@ A lightweight, extendable front-end developer tool for mobile web page. ``` @@ -38,7 +39,10 @@ See [Tutorial](./doc/tutorial.md) for more details. ## Documentation - + - [Tutorial](./doc/tutorial.md) + - [Plugin: Getting Started](./doc/plugin_getting_started.md) + - [Plugin: Building a Plugin](./doc/plugin_building_a_plugin.md) + - [Plugin: Event List](./doc/plugin_event_list.md) ## Changelog diff --git a/README_CN.md b/README_CN.md index cd616de7..31a5e555 100644 --- a/README_CN.md +++ b/README_CN.md @@ -4,118 +4,47 @@ vConsole ============================== [![npm version](https://badge.fury.io/js/vconsole.svg)](https://badge.fury.io/js/vconsole) -一个针对手机网页的前端 console 调试面板。 +一个轻量、可拓展、针对手机网页的前端开发者调试面板。 -## 简介 +## 特性 -vConsole 是一个网页前端调试面板，专为手机 web 页面量身设计，帮助开发者更为便捷地进行开发调试工作。 +- 查看 console 日志 +- 查看网络请求 +- 手动执行 JS 命令行 +- 自定义插件 -## 手机预览 - -![](./example/snapshot/qrcode.png) - -[http://wechatfe.github.io/vconsole/demo.html](http://wechatfe.github.io/vconsole/demo.html) - -![](./example/snapshot/log_panel.png) - - -## 安装 - -### 1.下载模块 - -下载文件 `dist/vconsole.min.js` 到本地。 - -或者使用 `npm` 安装： - -``` -npm install vconsole -``` - -### 2.引入模块 - -(1) 如果未使用 AMD/CMD 规范，可直接在 HTML 中引入 vConsole 模块。为了便于后续扩展，建议在 `` 中引入： +## 上手 ```html - - - -``` - -(2) 如果使用了 AMD/CMD 规范，可在 module 内使用 `require()` 引入模块： - -```javascript -var vConsole = require('path/to/vconsole.min.js'); + + ``` +详细使用方法请参阅[使用教程](./doc/tutorial_CN.md)。 -## 使用方法 -(1) 与 PC 端打印 log 一致，可直接使用 `console.log()` 等方法直接打印日志： - -```javascript -console.log('Hello World'); -``` - -未加载 vConsole 模块时，`console.log()` 会直接打印到原生控制台中；加载 vConsole 后，日志会打印到页面前端+原生控制台。 - -(2) 支持 5 种不同类型的日志，会以不同的颜色输出到前端面板： - -```javascript -console.log('foo'); // 白底黑字 -console.info('bar'); // 白底紫字 -console.debug('oh'); // 白底黄字 -console.warn('foo'); // 黄底黄字 -console.error('bar'); // 红底红字 -``` - -(3) 支持打印 Object 或 Array 变量，会以结构化 JSON 形式输出（并折叠）： - -```javascript -var obj = {}; -obj.foo = 'bar'; -console.log(obj); -/* -Object -{ - foo: "bar" -} -*/ -``` - -(4) 支持传入多个参数，会以空格隔开： - -```javascript -var uid = 233; -console.log('UserID:', uid); // 打印出 UserID: 233 -``` - -(5) 支持使用 `[default|system|...]` 的格式将 log 输出到指定面板： +## 手机预览 -```javascript -// [xxx] 须写在 log 的最开始 -console.log('[system]', 'foo'); -console.log('[system] bar'); -// 系统面板将打印出两行，分别为 foo 和 bar -``` +![](./example/snapshot/qrcode.png) -目前支持的面板有： +[http://wechatfe.github.io/vconsole/demo.html](http://wechatfe.github.io/vconsole/demo.html) -``` -[default] Log 日志（默认） -[system] System 系统 -[network] Network 网络 -``` +![](./example/snapshot/log_panel.png) -## 注意事项 -(1) 引入 vConsole 模块后，页面前端将会在右下角出现 vConsole 的悬停按钮，可展开/收起面板。 +## 文档 -若不希望普通用户看到面板，请不要在生产环境中引入 vConsole 模块。动态引入模块的方法可参考 `example/demo2.php` 示例。 + - [使用教程](./doc/tutorial_CN.md) + - [插件：入门](./doc/plugin_getting_started_CN.md) + - [插件：编写插件](./doc/plugin_building_a_plugin_CN.md) + - [插件：Event 事件列表](./doc/plugin_event_list_CN.md) -(2) 从 v1.2.0 开始，弃用 `vConsole.ready()` 接口。引入 vConsole 后，无须等待即可立即使用 `console.log()` 等方法输出日志。 ## 更新记录 diff --git a/doc/a_doc_index.md b/doc/a_doc_index.md new file mode 100644 index 00000000..c37e451b --- /dev/null +++ b/doc/a_doc_index.md @@ -0,0 +1,14 @@ +Documentation Index +============================== + + +## vConsole + + - [Tutorial](./tutorial.md) + + +## Plugin + + - [Plugin: Getting Started](./plugin_getting_started.md) + - [Plugin: Building a Plugin](./plugin_building_a_plugin.md) + - [Plugin: Event List](./plugin_event_list.md) \ No newline at end of file diff --git a/doc/a_doc_index_CN.md b/doc/a_doc_index_CN.md new file mode 100644 index 00000000..57ee457e --- /dev/null +++ b/doc/a_doc_index_CN.md @@ -0,0 +1,14 @@ +文档索引 +============================== + + +## vConsole 本体 + + - [使用教程](./tutorial_CN.md) + + +## Plugin 插件 + + - [插件：入门](./plugin_getting_started_CN.md) + - [插件：编写插件](./plugin_building_a_plugin_CN.md) + - [插件：Event 事件列表](./plugin_event_list_CN.md) \ No newline at end of file diff --git a/doc/plugin_building_a_plugin.md b/doc/plugin_building_a_plugin.md index e325f4f0..6c21e821 100644 --- a/doc/plugin_building_a_plugin.md +++ b/doc/plugin_building_a_plugin.md @@ -12,12 +12,12 @@ Plugin: Building a Plugin Make sure you have imported vConsole, then simply `new` an instance of class `VConsolePlugin`: -``` +```javascript vConsole.VConsolePlugin(id, name) ``` -`id` (required) is an unique string. -`name` (optional) is a string used for tab's display name. +- `id` (required) is an unique string. +- `name` (optional) is a string used for tab's display name. @@ -34,12 +34,12 @@ While installing and running a plugin, vConsole will trigger some events to allo use `.on()` to bind an event: -``` +```javascript on(eventName, callback) ``` -`eventName` (required) is a string. -`callback` (required) is a callback function when an event is triggered. +- `eventName` (required) is a string. +- `callback` (required) is a callback function when an event is triggered. @@ -82,14 +82,14 @@ myPlugin.on('addTool', function(callback) { }); ``` -Again, `addTool` will be triggered during initialized, after `renderTab`. It's `callback` receives an array of tool button list. We make a button which can reload the current page. +Again, `addTool` will be triggered during initialized, after `renderTab`. It's `callback` receives an `array` of tool button list. We make a button which can reload the current page. ## 3. Add to vConsole The final step is add your new plugin to vConsole: -``` +```javascript vConsole.addPlugin(pluginObject) ``` @@ -103,3 +103,5 @@ vConsole.addPlugin(myPlugin); Make sure you have finish binding all necessary events to your plugin before adding to vConsole. Some events (related to initialization) would not be trigger for second time after adding. + +[Back to Index](./a_doc_index.md) \ No newline at end of file diff --git a/doc/plugin_building_a_plugin_CN.md b/doc/plugin_building_a_plugin_CN.md new file mode 100644 index 00000000..1846d091 --- /dev/null +++ b/doc/plugin_building_a_plugin_CN.md @@ -0,0 +1,111 @@ +插件：编写插件 +============================== + +3 步即可编写一个 vConsole 插件： + +- 实例化 vConsole 插件 +- 绑定事件到插件 +- 将插件添加到 vConsole + + +## 1. 实例化插件 + +插件原型挂载在 `vConsole.VConsolePlugin` 中： + +```javascript +vConsole.VConsolePlugin(id, name) +``` + +- `id` (必填) 字符串，插件的 id，必须保证唯一，不能与其他插件冲突。 +- `name` (选填) 字符串，展示为 tab 面板的名字。 + +所以这一步只需将插件 `new` 出来即可： + +```javascript +var myPlugin = new vConsole.VConsolePlugin('my_plugin', 'My Plugin'); +``` + + + +## 2. 绑定插件事件 + +在初始化插件、后续运行时，vConsole 会对插件触发一些事件（event）。插件须通过这些事件来完成自定义功能。 + +使用 `.on()` 方法来绑定一个事件： + +```javascript +on(eventName, callback) +``` + +- `eventName` (必填) 字符串，事件的名字。 +- `callback` (必填) 回调函数，事件被触发时执行。 + + + +例子： + +```javascript +myPlugin.on('init', function() { + console.log('My plugin init'); +}); +``` + +关于每个事件的具体功效，请查阅[Event 事件列表](./plugin_event_list_CN.md)。 + + + +在本教程中，我们准备编写一个既有 tab 面板，又有 tool 按钮（位于面板底部）的插件。 + +添加新 tab 面板，需要绑定 `renderTab` 事件： + +```javascript +myPlugin.on('renderTab', function(callback) { + var html = '
Click the tool button below!
'; + callback(html); +}); +``` + +插件初始化过程中，就会触发 `renderTab` 事件。在这里我们简单地回传了一个 HTML 字符串给 `callback`，然后这段 HTML 就会被选染成新 tab 面板的主体部分。这个新 tab 的名字就是刚才实例化时的 `name`。 + +此外，若不绑定 `renderTab`，那么 vConsole 就不会添加新 tab。 + + + +接下来要添加一个底部的 tool 按钮，需要绑定 `addTool` 事件： + +```javascript +myPlugin.on('addTool', function(callback) { + var button = { + name: 'Reload', + onClick: function(event) { + location.reload(); + } + }; + callback([button]); +}); +``` + +同样地，`addTool` 会在插件初始化过程中触发，且在 `renderTab` 之后。回调函数 `callback` 的参数接收一个 `array` 数组，数组元素是用于配置按钮的 `object` 对象。本例中，点击这个按钮会重新加载当前网页。 + + + +## 3. 添加到 vConsole + +最后一步，就是将写好的插件添加到 vConsole 中： + +```javascript +vConsole.addPlugin(pluginObject) +``` + +`pluginObject` (必填) 必须为 `VConsolePlugin` 实例化的对象。 + +例子： + +```javascript +vConsole.addPlugin(myPlugin); +``` + +在添加到 vConsole 之前，请确保已经绑定完所有需要用到的事件。一些初始化相关的事件只会在插件被添加时触发一次，并不会在其他时机被触发。 + + +[返回索引](./a_doc_index_CN.md) \ No newline at end of file diff --git a/doc/plugin_event_list.md b/doc/plugin_event_list.md index 42318036..91366041 100644 --- a/doc/plugin_event_list.md +++ b/doc/plugin_event_list.md @@ -156,4 +156,4 @@ myPlugin.on('hideConsole', function() { ``` - +[Back to Index](./a_doc_index.md) \ No newline at end of file diff --git a/doc/plugin_event_list_CN.md b/doc/plugin_event_list_CN.md new file mode 100644 index 00000000..b63a20fc --- /dev/null +++ b/doc/plugin_event_list_CN.md @@ -0,0 +1,165 @@ +插件：Event 事件列表 +============================== + +插件的所有事件（event）都是可选的，不强制绑定。但一些特性（比如添加 tool 按钮）依赖于指定的事件，所以若要实现那些特性，就必须绑定指定的事件。 + +每个事件都会有一个 callback 回调函数，当事件被触发时，就会执行 callback。一些 callback 可能会带有参数。 + + + +## init + +当插件开始初始化时触发。这个事件触发时，代表 vConsole 开始安装此插件，开发者可以在此时初始化一些配置。 +这个事件只会触发一次。 +注意，此时插件的 DOM 仍未就绪，插件还未被渲染到页面中。 + +##### Callback 参数： +- 无 + +##### 例子： +```javascript +myPlugin.on('init', function() { + // 在这里可以初始化一些自用的配置 + this.list = []; // `this` == `myPlugin` +}); +``` + + +## renderTab + +当 vConsole 尝试为此插件渲染新 tab 时触发。这个事件只会触发一次。 +绑定此事件后，vConsole 会认为此插件需要创建新 tab，并会将 callback 中获取的 HTML 用于渲染 tab。因此，只要绑定了此事件，新 tab 肯定会被渲染到页面中，无论 callback 传入的 HTML 是否为空。如果不需要添加新 tab，请不要绑定此事件。 + +##### Callback 参数 +- (必填) function(html): 回调函数，接收一个 HTML 参数用于渲染 tab。`html` 可以为 HTML 字符串，或者 `DOMElement` 对象。 + +##### 例子： + +```javascript +myPlugin.on('renderTab', function(callback) { + var html = '
Hello
'; + callback(html); +}); +``` + + +## addTool + +当 vConsole 尝试为此插件添加新的 tool 按钮时触发。这个事件只会触发一次。 + +##### Callback 参数： + +- (必填) function(toolList): 回调函数，接收一个带有按钮配置信息的 `array` 数组。 + +tool 按钮的参数为： + +Property | | | | +------- | ------- | ------- | ------- +name | string | 必填 | 按钮展示的名字。 +global | boolean | 选填，默认 `false` | `false` 时，当切换到别的 tab 后，按钮就会被隐藏；`true` 时，按钮变成全局可见。 +onClick | function(event) | 必填 | 点击按钮时的回调函数。 + +##### 例子： + +```javascript +myPlugin.on('addTool', function(callback) { + var toolList = []; + toolList.push({ + name: 'Reload', + global: false, + onClick: function(e) { + location.reload(); + } + }); + callback(toolList); +}); +``` + + +## ready + +当插件初始化结束后触发。这个事件只会触发一次。 +此时插件已经成功安装并已渲染到页面。 + +##### Callback 参数： + +- 无 + +##### 例子： + +```javascript +myPlugin.on('ready', function() { + // do something... +}); +``` + + +## show + +当插件的 tab 被显示时触发。只有绑定了 `renderTab` 事件的插件才会收到此事件。 + +##### Callback 参数： + +- 无 + +##### 例子： + +```javascript +myPlugin.on('show', function() { + // do something +}); +``` + + +## Hide + +当插件的 tab 被隐藏时触发。只有绑定了 `renderTab` 事件的插件才会收到此事件。 + +##### Callback 参数： + +- 无 + +##### 例子： + +```javascript +myPlugin.on('hide', function() { + // do something +}); +``` + + +## showConsole + +当 vConsole 被显示时触发。 + +##### Callback 参数： + +- 无 + +##### 例子: + +```javascript +myPlugin.on('showConsole', function() { + // do something +}); +``` + + +## hideConsole + +当 vConsole 被隐藏时触发。 + +##### Callback 参数： + +- 无 + +##### 例子: + +```javascript +myPlugin.on('hideConsole', function() { + // do something +}); +``` + + +[返回索引](./a_doc_index_CN.md) \ No newline at end of file diff --git a/doc/plugin_getting_started.md b/doc/plugin_getting_started.md index 48446bc8..1393e529 100644 --- a/doc/plugin_getting_started.md +++ b/doc/plugin_getting_started.md @@ -18,4 +18,7 @@ var myPlugin = new VConsolePlugin('my_plugin', 'My Plugin'); vConsole.addPlugin(myPlugin); ``` -The above plugin has no function. See [Building a Plugin](./plugin_building_a_plugin.md) for more details. \ No newline at end of file +The above plugin has no function. See [Building a Plugin](./plugin_building_a_plugin.md) for more details. + + +[Back to Index](./a_doc_index.md) \ No newline at end of file diff --git a/doc/plugin_getting_started_CN.md b/doc/plugin_getting_started_CN.md new file mode 100644 index 00000000..aa0063e3 --- /dev/null +++ b/doc/plugin_getting_started_CN.md @@ -0,0 +1,24 @@ +插件：入门 +============================== + +通过插件，你可以： + +- 添加一个新的 tab 面板 +- 添加一个或多个 tool 按钮（位于面板底部） + +在 tab 和 tool 按钮中，即可添加自定义功能，以满足个性化开发的需要。 + + +## 快速上手 + +两行创建一个 vConsole 插件： + +```javascript +var myPlugin = new VConsolePlugin('my_plugin', 'My Plugin'); +vConsole.addPlugin(myPlugin); +``` + +当然，上面的插件并无任何功能。请继续阅读[编写插件](./plugin_building_a_plugin_CN.md)来了解细节。 + + +[返回索引](./a_doc_index_CN.md) \ No newline at end of file diff --git a/doc/tutorial.md b/doc/tutorial.md index e736b3f1..dde2be39 100644 --- a/doc/tutorial.md +++ b/doc/tutorial.md @@ -101,3 +101,5 @@ Supported tabs: [system] System tab ``` + +[Goto: Documentation Index](./a_doc_index.md) \ No newline at end of file diff --git a/doc/tutorial_CN.md b/doc/tutorial_CN.md new file mode 100644 index 00000000..5e6bc378 --- /dev/null +++ b/doc/tutorial_CN.md @@ -0,0 +1,104 @@ +使用教程 +============================== + +## 安装 + +### 1.下载模块 + +下载文件 `dist/vconsole.min.js` 到本地。 + +或者使用 `npm` 安装： + +``` +npm install vconsole +``` + +### 2.引入模块 + +(1) 如果未使用 AMD/CMD 规范，可直接在 HTML 中引入 vConsole 模块。为了便于后续扩展，建议在 `` 中引入： + +```html + + + +``` + +(2) 如果使用了 AMD/CMD 规范，可在 module 内使用 `require()` 引入模块： + +```javascript +var vConsole = require('path/to/vconsole.min.js'); +``` + + +## 使用方法 + + +### 打印日志 + +与 PC 端打印 log 一致，可直接使用 `console.log()` 等方法直接打印日志： + +```javascript +console.log('Hello World'); +``` + +未加载 vConsole 模块时，`console.log()` 会直接打印到原生控制台中；加载 vConsole 后，日志会打印到页面前端+原生控制台。 + + +### 日志类型 + +支持 5 种不同类型的日志，会以不同的颜色输出到前端面板： + +```javascript +console.log('foo'); // 白底黑字 +console.info('bar'); // 白底紫字 +console.debug('oh'); // 白底黄字 +console.warn('foo'); // 黄底黄字 +console.error('bar'); // 红底红字 +``` + + +### Object/Array 结构化展示 + +支持打印 Object 或 Array 变量，会以结构化 JSON 形式输出（并折叠）： + +```javascript +var obj = {}; +obj.foo = 'bar'; +console.log(obj); +/* +Object +{ + foo: "bar" +} +*/ +``` + +### 多态 + +支持传入多个参数，会以空格隔开： + +```javascript +var uid = 233; +console.log('UserID:', uid); // 打印出 UserID: 233 +``` + +### 特殊格式 + +支持使用 `[default|system|...]` 的格式将 log 输出到指定 tab 面板： + +```javascript +// [xxx] 须写在 log 的最开始 +console.log('[system]', 'foo'); +console.log('[system] bar'); +// System 面板将打印出两行，分别为 foo 和 bar +``` + +目前支持的 tab 面板有： + +``` +[default] Log 日志（默认） +[system] System 系统 +``` + + +[前往：文档索引](./a_doc_index_CN.md) \ No newline at end of file