add CN docs

zonghuaj · Jun 4, 2016 · 5d09273 · 5d09273
1 parent d54c4f4
commit 5d09273
Show file tree

Hide file tree

Showing 12 changed files with 476 additions and 104 deletions.
diff --git a/README.md b/README.md
@@ -21,6 +21,7 @@ A lightweight, extendable front-end developer tool for mobile web page.
 <script src="path/to/vconsole.min.js"></script>
 <script>
 console.log('Hello world');
+// then tap vConsole button to see the log
 </script>
 ```
 
@@ -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
@@ -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 模块。为了便于后续扩展，建议在 `<head>` 中引入：
+## 上手
 
 ```html
-<head>
-	<script src="path/to/vconsole.min.js"></script>
-</head>
-```
-
-(2) 如果使用了 AMD/CMD 规范，可在 module 内使用 `require()` 引入模块：
-
-```javascript
-var vConsole = require('path/to/vconsole.min.js');
+<script src="path/to/vconsole.min.js"></script>
+<script>
+console.log('Hello world');
+// 然后点击右下角 vConsole 按钮即可查看到 log
+</script>
 ```
 
+详细使用方法请参阅[使用教程](./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
@@ -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)
diff --git a/doc/a_doc_index_CN.md 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)
diff --git 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)
diff --git a/doc/plugin_building_a_plugin_CN.md 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 = '<div>Click the tool button below!</div>';
+	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)
diff --git 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)
Original file line number	Diff line number	Diff line change
Expand Up		@@ -156,4 +156,4 @@ myPlugin.on('hideConsole', function() {
		```



		[Back to Index](./a_doc_index.md)