Merge pull request #1655 from alibaba/doc/iceworks

docs: 补充 iceworks 文档
alibaba · Mar 25, 2019 · 1cebb6d · 1cebb6d
2 parents 47c5497 + 38ee341
commit 1cebb6d
Show file tree

Hide file tree

Showing 15 changed files with 330 additions and 33 deletions.
diff --git a/docs/iceworks/marterial-block.md b/docs/iceworks/marterial-block.md
@@ -0,0 +1,20 @@
+---
+title: 物料-区块面板
+category: Iceworks
+order: 4
+---
+
+Iceworks 提供了丰富的区块供用户进行选择用以新建页面。如果我们提供的区块不能满足你的需求，我们还提供了能力帮助你快速创建自定义区块。
+
+## 区块市场
+
+在区块市场中，你可以：
+
+- 根据**物料源**查看区块列表；
+- 根据**分类**筛选区块列表；
+- 点击「刷新」获取最新区块；
+- 点击「预览效果图」查看区块预览图；
+- 点击「在线预览」在线预览区块；
+- 点击「源码」查看区块源码 —— 你可以发起 Pull Request 帮助我们完善区块。
+
+![区块市场](https://img.alicdn.com/tfs/TB1fa9rM5rpK1RjSZFhXXXSdXXa-1425-818.gif)
diff --git a/docs/iceworks/marterial-component.md b/docs/iceworks/marterial-component.md
@@ -0,0 +1,20 @@
+---
+title: 物料-组件面板
+category: Iceworks
+order: 5
+---
+
+Iceworks 提供了丰富的组件供用户进行选择用以开发页面。
+
+## 组件市场
+
+在组件市场中，你可以：
+
+- 根据**物料源**查看组件列表；
+- 根据**分类**筛选组件列表；
+- 审视依赖了哪些组件；
+- 点击「刷新」获取最新组件；
+- 点击「复制引用代码」复制代码；
+- 点击「文档」查看如何使用组件；
+
+![区块市场](https://img.alicdn.com/tfs/TB1T1y8M4naK1RjSZFtXXbC2VXa-1425-645.gif)
diff --git a/docs/iceworks/custom-project-template.md → docs/iceworks/marterial-scaffold.md b/docs/iceworks/custom-project-template.md → docs/iceworks/marterial-scaffold.md
@@ -1,18 +1,25 @@
 ---
-title: 自定义项目模板
-
-order: 4
+title: 物料-模板面板
+category: Iceworks
+order: 3
 ---
 
-在 Iceworks 2.2.0 之前的版本，可以通过 `新建页面` 时选择默认提供的 4 套布局去替换已有项目的布局，也可以通过布局列表的`自定义布局`功能进行自定义，然后添加到项目。
+Iceworks 提供了海量的模板供用户进行选择用以新建项目。如果我们提供的模板不能满足你的需求，我们还提供了能力帮助你快速自定义模板。
 
-![iceworks](https://img.alicdn.com/tfs/TB1ecZexQyWBuNjy0FpXXassXXa-1909-1368.png)
+## 模板市场
 
-然而，这些都是基于已经生成好的项目添加新的布局。那有没有一种可能，完全从零开始去自定义一个模板，答案是有的，你可以先从自定义布局开始初始化一个项目，甚至是自定义布局之后，在自定义选择 Router，Eslint，Redux，Mbox 等等，这都是有可能的。我们还是脚踏实地，先从第一步开始，来了解下 Iceworks 全新的自定义布局功能，如何从自定义布局开始初始化一个模板。
+在模板市场中，你可以：
 
-![](https://img.alicdn.com/tfs/TB17Virx_tYBeNjy1XdXXXXyVXa-862-572.gif)
+- 根据**物料源**查看模板列表；
+- 根据**分类**筛选模板列表；
+- 点击「刷新」获取最新模板；
+- 点击「预览」在线预览模板。
+
+![模板市场](https://img.alicdn.com/tfs/TB1timqM3HqK1RjSZFgXXa7JXXa-1425-818.gif)
 
-## 自定义创建流程
+## 自定义模板
+
+![](https://img.alicdn.com/tfs/TB17Virx_tYBeNjy1XdXXXXyVXa-862-572.gif)
 
 在 `模板` 界面选择 `自定义模板`，点击新建弹窗如下，左边是属性配置面板，右边是配置的实时效果图，目前自定义主要包含以下四部分配置：
 

diff --git a/docs/iceworks/plubins-alioss.md b/docs/iceworks/plubins-alioss.md
@@ -1,7 +1,7 @@
 ---
 title: 插件-阿里云 OSS
-
-order: 1
+category: Iceworks
+order: 7
 ---
 
 阿里云 OSS 插件可以一键将构建结果上传到您的 OSS bucket 中。

diff --git a/docs/iceworks/plugins-build.md b/docs/iceworks/plugins-build.md
@@ -0,0 +1,15 @@
+---
+title: 插件-构建结果
+category: Iceworks
+order: 8
+---
+
+通常来说，项目的构建结果将会上传到远程服务端作为网站的静态资源进行使用 ，你可以通过构建结果插件来审视这些将要上传的文件。
+
+以下示例演示了「构建结果」插件面板的相关功能：
+
+1. 未构建时，构建结果面板无数据；
+2. 进行构建，构建成功后面板显示有：JS/CSS/PNG/JPG/HTML 类型的文件；
+3. 删除一个页面，构建结果中删除了 JPG 文件。
+
+![插件-构建结果](https://img.alicdn.com/tfs/TB1S5TbM4naK1RjSZFBXXcW7VXa-868-571.gif)
diff --git a/docs/iceworks/plugins-dependencies.md b/docs/iceworks/plugins-dependencies.md
@@ -0,0 +1,17 @@
+---
+title: 插件-依赖管理
+category: Iceworks
+order: 9
+---
+
+项目中的依赖需要严格管理，Iceworks 提供了依赖管理插件，你可以：
+
+- 查看项目的依赖；
+- 升级项目的依赖；
+- 添加项目的依赖。
+
+以下示例显示了项目初始化后未安装依赖时、重安装依赖后、添加依赖后的依赖管理面板信息变化情况：
+
+![依赖管理](https://img.alicdn.com/tfs/TB1v2qTMZbpK1RjSZFyXXX_qFXa-868-571.gif)
+
+![添加依赖](https://img.alicdn.com/tfs/TB1_tSIM3TqK1RjSZPhXXXfOFXa-868-571.gif)
diff --git a/docs/iceworks/plugins-git.md b/docs/iceworks/plugins-git.md
@@ -0,0 +1,23 @@
+---
+title: 插件-Git 面板
+category: Iceworks
+order: 10
+---
+
+Iceworks 提供了 Git 仓库管理的能力。
+
+1. 关联仓库：
+
+    ![关联仓库](https://img.alicdn.com/tfs/TB1LIaYM6TpK1RjSZKPXXa3UpXa-1424-696.gif)
+2. 初始化仓库：
+
+    ![初始化仓库](https://img.alicdn.com/tfs/TB1l6OTM9zqK1RjSZFHXXb3CpXa-1424-696.gif)
+3. 提交变更：
+
+    ![提交变更](https://img.alicdn.com/tfs/TB1obKQMYPpK1RjSZFFXXa5PpXa-869-576.gif)
+4. 新建分支：
+
+    ![新建分支](https://img.alicdn.com/tfs/TB1cqOOM9zqK1RjSZFLXXcn2XXa-869-576.gif)
+5. 切换分支：
+
+    ![切换分支](https://img.alicdn.com/tfs/TB14ty6M4jaK1RjSZFAXXbdLFXa-869-576.gif)
diff --git a/docs/iceworks/plugins-layout_page.md b/docs/iceworks/plugins-layout_page.md
@@ -0,0 +1,12 @@
+---
+title: 插件-布局列表和页面列表
+category: Iceworks
+order: 11
+---
+
+布局列表和页面列表是两个单独的插件，用于审视项目中的布局和页面。
+
+- 通过布局列表插件，你可以清晰地了解到当前项目中有哪些布局；
+- 通过页面布局插件，你可以看到项目中的所有页面，也可新增或删除页面。
+
+![布局列表和页面列表](https://img.alicdn.com/tfs/TB11xS1MW6qK1RjSZFmXXX0PFXa-869-576.gif)
diff --git a/docs/iceworks/plugins-proxy.md b/docs/iceworks/plugins-proxy.md
@@ -1,7 +1,7 @@
 ---
 title: 插件-代理配置
-
-order: 2
+category: Iceworks
+order: 13
 ---
 
 在使用代理功能时，请先明确一下问题：

diff --git a/docs/iceworks/plugins-todo.md b/docs/iceworks/plugins-todo.md
@@ -0,0 +1,9 @@
+---
+title: 插件-TODO
+category: Iceworks
+order: 14
+---
+
+项目中的 TODO 注释需要被重视，Iceworks 提供了 TODO 插件用于审视项目中的所有 TODO。
+
+![TODO](https://img.alicdn.com/tfs/TB1kF57M3HqK1RjSZFkXXX.WFXa-1018-746.gif)
diff --git a/docs/iceworks/project-Integrated-environment.md b/docs/iceworks/project-Integrated-environment.md
@@ -0,0 +1,49 @@
+---
+title: 项目管理-集成环境
+category: Iceworks
+order: 2
+---
+
+Iceworks 提供了项目管理中的集成环境，点击项目面板，进入到项目的集成环境。
+
+## 工程管理
+
+调试服务：点击「启动调试服务」，Iceworks 将启动调试服务并使用浏览器打开调试页面。同时你可以在 Iceworks 项目面板上点击 URL 打开调试页面。点击「停止调试服务」将停止服务。
+
+![启动调试服务](https://img.alicdn.com/tfs/TB1MaamM9zqK1RjSZFjXXblCFXa-1425-818.gif)
+
+![停止调试服务](https://img.alicdn.com/tfs/TB1PiuoM7zoK1RjSZFlXXai4VXa-1425-818.gif)
+
+执行构建：点击「构建项目」即可执行本地构建。
+
+![执行构建](https://img.alicdn.com/tfs/TB1VOSyM4jaK1RjSZFAXXbdLFXa-871-580.gif)
+
+## 依赖管理
+
+重装依赖：点击「重装依赖」即可是重新安装项目依赖。
+
+![重装依赖](https://img.alicdn.com/tfs/TB118iwM3HqK1RjSZFkXXX.WFXa-871-580.gif)
+
+添加依赖：点击「添加依赖」，输入 npm 包名和包的版本号，即可安装依赖。
+
+![添加依赖](https://img.alicdn.com/tfs/TB1l8isM3HqK1RjSZJnXXbNLpXa-871-580.gif)
+
+## 调用外部工具
+
+打开编辑器：
+
+![打开编辑器](https://img.alicdn.com/tfs/TB1ZoGiM9zqK1RjSZFLXXcn2XXa-1423-818.gif)
+
+打开终端：
+
+![打开终端](https://img.alicdn.com/tfs/TB1U4uqM3HqK1RjSZFPXXcwapXa-1423-818.gif)
+
+打开文件夹：
+
+![打开文件夹](https://img.alicdn.com/tfs/TB13UGiM9zqK1RjSZFLXXcn2XXa-1423-818.gif)
+
+## 终端日志
+
+在执行工程管理相关操作时，可点击「运行日志」查看执行日志。例如，构建项目时：
+
+![终端日志](https://img.alicdn.com/tfs/TB1ZvinMY2pK1RjSZFsXXaNlXXa-875-580.gif)
diff --git a/docs/iceworks/project-new-page.md b/docs/iceworks/project-new-page.md
@@ -0,0 +1,38 @@
+---
+title: 项目管理-新建页面
+category: Iceworks
+order: 1
+---
+
+Iceworks 提供了项目管理中新建页面能力，点击项目面板，点击「新建页面」开始新建一个页面。
+
+选择布局：当项目中有多个布局时，你需要先选择布局。
+
+![选择布局](https://img.alicdn.com/tfs/TB1ZFG9MZfpK1RjSZFOXXa6nFXa-869-576.gif)
+
+选择区块进行排列：
+
+- 从最新中筛选；
+- 从分类中筛选；
+- 搜索关键字进行筛选；
+- 点击区块即添加到页面中；
+- 调整区块位置。
+
+![选择区块](https://img.alicdn.com/tfs/TB1KmSMM4naK1RjSZFtXXbC2VXa-871-599.gif)
+
+![调整区块](https://img.alicdn.com/tfs/TB1b0iGM3DqK1RjSZSyXXaxEVXa-868-571.gif)
+
+点击「预览页面」可先进行预览：
+
+- 切换窗口类型（手机屏幕、Pad 屏幕、电脑屏幕）进行预览；
+- 点击左上角二维码可使用外部设备扫码预览。
+
+![预览页面](https://img.alicdn.com/tfs/TB1MLyOM4naK1RjSZFtXXbC2VXa-1263-779.gif)
+
+点击「生成页面」完成新建流程：
+
+- 填写必要信息；
+- Iceworks 将新建页面并执行「热更新」；
+- 「热更新」完成，调试页面将自动刷新：可以看到左侧导航中已新增了“Nav4”。
+
+![生成页面](https://img.alicdn.com/tfs/TB1UG1fM3DqK1RjSZSyXXaxEVXa-1425-818.gif) 
diff --git a/docs/iceworks/import-exists-projet.md → docs/iceworks/project-new.md b/docs/iceworks/import-exists-projet.md → docs/iceworks/project-new.md
@@ -1,10 +1,16 @@
 ---
-title: 已有项目接入 Iceworks
-
-order: 3
+title: 项目管理-新建项目
+category: Iceworks
+order: 0
 ---
 
-将已有项目接入到 Icewokrs 中，需要增加对应信息的项目描述
+Iceworks 提供了两种方式开始你的项目管理。
+
+## 从已有的项目中导入
+
+![从已有的项目中打开](https://img.alicdn.com/tfs/TB1TPiuMVzqK1RjSZFCXXbbxVXa-875-580.gif)
+
+将已有项目接入到 Icewokrs 中，需要增加对应信息的项目描述。
 
 ## 1. 描述项目可被 Iceworks 识别
 
@@ -48,3 +54,11 @@ order: 3
   }
 }
 ```
+
+## 使用模板创建
+
+在项目面板点击「项目选项卡」，点击「创建项目」，选择一个模板创建项目（如果没有合适的模板，你也可以[自定义模板](./marterial-scaffold)）。
+
+创建项目成功后将提示你是否自动安装依赖，请选择「是」。
+
+![使用模板创建项目](https://img.alicdn.com/tfs/TB13eWtM3HqK1RjSZFEXXcGMXXa-875-580.gif)
diff --git a/docs/iceworks/settings.md b/docs/iceworks/settings.md
@@ -0,0 +1,79 @@
+---
+title: 设置
+category: Iceworks
+order: 15
+---
+
+通过设置面板开启、关闭或配置 Iceworks 相关功能。
+
+## 插件管理
+
+插件管理提供让用户开启或关闭插件面板的能力。
+
+示例：关闭 TODO 插件。
+
+![插件管理](https://img.alicdn.com/tfs/TB1hTqUM3DqK1RjSZSyXXaxEVXa-870-579.gif)
+
+## 物料源管理
+
+物料源管理可以让用户开启或关闭物料源的能力。
+
+示例：关闭小程序物料。
+
+![物料源管理](https://img.alicdn.com/tfs/TB1hKi6M7voK1RjSZFNXXcxMVXa-870-579.gif)
+
+## 通用
+
+### 终端
+
+终端配置用于指定「打开终端」时调用的终端。目前提供了 Terminal/iTerm2 终端用于选择。
+
+### 编辑器
+
+编辑器配置用于指定「打开编辑器」时调用的编辑器。
+
+Iceworks 默认内置了 VSCode、SublimeText、Atom、WebStorm 等编辑器。
+
+Iceworks 没法覆盖所有用户的编辑器选择，或者安装是绿色版的编辑器，Iceworks 无法查找到的，也可通过自设置自定义编辑器启动脚本。
+
+1. 首先系统环境中存在对应的编辑器启动脚本
+
+    可以通过命令行唤起编辑器。
+
+    - Sublime Text 设置方法：https://www.sublimetext.com/docs/3/osx_command_line.html
+    - VSCode 设置方法： https://code.visualstudio.com/docs/editor/command-line
+
+        mac `command+shift+p` win `ctrl+shift+p` 命令面板中输入 `command` 选中回车即可
+
+        ![](https://img.alicdn.com/tfs/TB1FOXsb3HqK1RjSZFgXXa7JXXa-608-354.png)
+     - 其他编辑器请自行搜索配置方法
+
+    配置完成后，能在系统命令行内启动。以为 VSCode 为例：
+
+    ```bash
+    cd home/project
+    code ./
+    ```
+
+    能打开编辑器后，则表示配置成功。
+
+2. 修改 Iceworks 里的设置
+
+    1. 进入 设置 -> 通用 -> 编辑器 选择【自定义编辑器启动脚本】
+    2. 输入启动脚本 `code ${cwd}`
+
+        ![](https://img.alicdn.com/tfs/TB13f8Xv_mWBKNjSZFBXXXxUFXa-627-271.png)
+
+        `${cwd}` 表示项目路径，在启动时会替换掉。
+        同理如果是 Sublime Text 则设置为  `subl ${cwd}`
+        如果你的启动脚本带有参数例如： `myeditor --project ./`， 则脚本为 `myeditor --project ${cwd}`
+
+### NPM 源
+
+NPM 源的配置将决定 Iceworks 在安装依赖时的数据源。Iceworks 默认提供了 npm/cnpm/tnpm 等源，亦可通过自定义的方式指定源 URL。
+
+![自定义 NPM 源](https://img.alicdn.com/tfs/TB1UJe4M5rpK1RjSZFhXXXSdXXa-1740-1200.jpg)
+
+### 登录
+
+对于阿里内部用户，Iceworks 提供了登录功能。一些在阿里内部需要身份验证的功能需要登录后才能使用。