feat: update docs

antvis · Nov 21, 2019 · eee43fc · eee43fc
1 parent eb4711d
commit eee43fc
Show file tree

Hide file tree

Showing 6 changed files with 145 additions and 29 deletions.
diff --git a/packages/graphin-components/.npmignore b/packages/graphin-components/.npmignore
@@ -0,0 +1,55 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log
+.DS_Store
+
+# Coverage directory used by tools like istanbul
+coverage
+
+# Dependency directories
+node_modules
+**/node_modules
+**/lib
+**/es
+jspm_packages/
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Output of 'npm pack'
+*.tgz
+
+
+# dotenv environment variables file
+.env
+
+# IDE
+.idea
+
+# build
+lib
+build
+
+# lock
+package-lock.json
+
+
+# yarn-lock
+yarn.lock
+
+
+# ignore dist files
+.vscode/
+src
+jest.config.js
+.fatherrc.js
+__mock__
+public
+tsconfig.json
diff --git a/packages/graphin-site/docs/api/extend.zh.md b/packages/graphin-site/docs/api/extend.zh.md
@@ -10,7 +10,7 @@ order: 3
 | layout    | (graphin: [Graphin](), prevProps: [GraphinProps](/zh/docs/api/graphin#props)) => [ExendLayout](#extendlayout)[ ]  | 否       | 自定义布局 |
 | nodeShape | (node: [Node](/zh/docs/api/graphin#node)) => [ExtendNodeShape](#extendnodeshape)[ ] | 否       | 自定义节点 |
 | marker    | ( ) => [ExtendMarker](#extendmarker)[ ]         | 否       | 自定义图标 |
-
+| icon   | ( ) => [ExtendIcon](#extendicon)[ ]         | 否       | 自定义图标（iconfont 形式） |
 
 ### ExendLayout
 
@@ -48,3 +48,15 @@ order: 3
 | -------- | --------------------- | -------- | ------------- |
 | name    | string       | **是** | icon 类型      |
 | path | string     | **是**       | svg 路径数据      |
+
+
+### ExtendIcon
+
+自定义 Icon 配置
+
+|   属性   | 类型                  | 是否必选 | 说明          |
+| -------- | --------------------- | -------- | ------------- |
+| fontFamily    | string       | **是** | 字体名称      |
+| map | { font\_class: string; unicode\_decimal: number; }[ ]     | **是**       | iconfont 的 class name 和 unicode decimal 的映射集合      |
+
+
diff --git a/packages/graphin-site/docs/api/graphin.zh.md b/packages/graphin-site/docs/api/graphin.zh.md
@@ -22,8 +22,8 @@ order: 1
 
 |   属性 | 类型                   | 是否必选 | 说明       |
 | ------ | ---------------------- | -------- | ---------- |
-| nodes  | [Node[]](#node) | 是       | 节点的集合 |
-| edges  | [Edge[]](#edge) | 是       | 边的集合   |
+| nodes  | [Node[ ]](#node) | 是       | 节点的集合 |
+| edges  | [Edge[ ]](#edge) | 是       | 边的集合   |
 
 ### Node
 
@@ -34,10 +34,10 @@ order: 1
 | id             | string                              | **是** | 唯一标示 id                              |
 | data           | [NodeData](#nodedata)                 | **是** | 节点附带的 key-value 数据 |
 | shape          | string                              | 否       | 节点的图形类型（NodeShape）。默认值为内置的 `CircleNode`。可以通过 extend 对 NodeShape 进行扩展  |
-| style          | [NodeDefaultStyle](#nodedefaultstyle) | 否       | 和 NodeShape 相对应的样式信息                     |
+| style          | [NodeStyle](#nodestyle) | 否       | 和 NodeShape 相对应的样式信息                     |
 | x              | number                              | 否       | 节点的位置信息：X 坐标（在保存下来的图数据中会有位置信息）                            |
 | y              | number                              | 否       | 节点的位置信息：Y 坐标（在保存下来的图数据中会有位置信息）                           |
-| layout         | NodeLayoutType                    | 否       | 内置的某些布局在节点上附加的属性                                 |
+| layout         | [NodeLayoutType](#nodelayouttype)                    | 否       | 内置的某些布局在节点上附加的属性                                 |
 | `[key:string]` | any                                 | 否       | 其余用户自定义的属性，也是支持挂载的              |
 |                |
 
@@ -52,9 +52,11 @@ order: 1
 | properties     | any[]    | 否       | 节点的属性，任意的 key-value              |
 | `[key:string]` | any    | 否       | 其余任意属性                |
 
-### NodeDefaultStyle
+### NodeStyle
 
-和 NodeShape 相对应的样式信息
+和 NodeShape 相对应的样式信息。任意的 key-value 都可以。
+
+这是 Graphin 内置 NodeShape 支持的 NodeStyle 类型：
 
 |   属性       | 默认值    | 说明           |
 | ------------ | --------- | -------------- |
@@ -63,6 +65,22 @@ order: 1
 | fontSize     | 12        | 文本的字体大小 |
 | fontColor    | #3b3b3b | 文本的字体颜色 |
 | dark         | #eee    | 置灰状态下颜色      |
+| icon         | company    | iconfont 的 class name      |
+| fontFamily         | 'graphin'    | iconfont 的  fontFamily     |
+
+### NodeLayoutType
+
+内置的某些布局在节点上附加的属性
+
+
+
+|   属性         | 类型     | 是否必选 | 说明                         |
+| -------------- | -------- | -------- | ---------------------------- |
+| degree           | number    | 否 | 节点度数               |
+| force         | { mass?: number }| 否 | 力导布局相关的节点附加参数         |
+| concentric         | { outerR?:number; center: { x: number; y:number;} theta: number; } | 否 | 同心圆布局相关的节点附加参数       |
+
+
 
 ### Edge
 

diff --git a/packages/graphin-site/docs/manual/getting-started.zh.md b/packages/graphin-site/docs/manual/getting-started.zh.md
@@ -14,23 +14,25 @@ $ npm install @antv/graphin --save
 这是一个最简单的 Graphin 组件的在线演示。访问 https://codesandbox.io/s/data-driven-3o71b 创建一个 CodeSandbox 的在线示例，别忘了保存以创建一个新的实例。通过 CodeSandbox，我们可以不用去配那些琐碎的 React 脚手架，快速尝鲜。
 
 <iframe
-     src="https://codesandbox.io/embed/data-driven-3o71b?fontsize=14"
-     style="width:100%; height:500px; border:0; border-radius: 4px; overflow:hidden;"
+     src="https://codesandbox.io/embed/data-driven-v6v72?fontsize=14&theme=dark"
+     style="width:100%; height:600px; border:0; border-radius: 4px; overflow:hidden;"
      title="data-driven"
      allow="geolocation; microphone; camera; midi; vr; accelerometer; gyroscope; payment; ambient-light-sensor; encrypted-media; usb"
      sandbox="allow-modals allow-forms allow-popups allow-scripts allow-same-origin"
-></iframe>
+   ></iframe>
 
 ### 01. 渲染数据
 
-Graphin 使用起来就像普通的组件一样，它只有一个必选属性 `data`，内部会对其进行数据校验，data 的数据结构有一定的要求，详情参考：[核心概念/Data 数据驱动](main-concepts/data)
+Graphin 使用起来就像普通的组件一样，它只有一个必选属性 `data`，内部会对其进行数据校验，data 的数据结构有一定的要求，详情参考：[核心概念/Data 数据驱动](main-concepts/data)。
 
 Graphin 提供一个 Mock 函数，帮助我们快速生成一些图数据，让我们试试看吧：
 
 ```jsx
 import React from 'react';
 import ReactDOM from 'react-dom';
 import Graphin, { Utils } from '@antv/graphin';
+
+import "@antv/graphin/dist/index.css"; // 引入Graphin CSS
 import './styles.css';
 
 const App = () => {
@@ -46,6 +48,8 @@ const rootElement = document.getElementById('root');
 ReactDOM.render(<App />, rootElement);
 ```
 
+这个例子的效果可以看上一节中的 Sandbox 例子。
+
 ### 02. 使用布局
 
 Graphin 组件内置了 6 种布局，默认提供布局为 force（力导布局）。我们可以根据自己业务的不同来调整布局。比如，我们希望节点按照同心圆（concentric）排列。让我们来调整上述的代码：
@@ -57,6 +61,16 @@ Graphin 组件内置了 6 种布局，默认提供布局为 force（力导布局
 
 ```
 
+效果如下：
+
+<iframe
+     src="https://codesandbox.io/embed/data-driven-lbk7e?fontsize=14&theme=dark"
+     style="width:100%; height:600px; border:0; border-radius: 4px; overflow:hidden;"
+     title="quick-starter-layout-change"
+     allow="geolocation; microphone; camera; midi; vr; accelerometer; gyroscope; payment; ambient-light-sensor; encrypted-media; usb"
+     sandbox="allow-modals allow-forms allow-popups allow-scripts allow-same-origin"
+   ></iframe>
+
 ### 03. 使用组件
 
 Graphin 目前仅提供两个官方组件，Toolbar 和 ContextMenu。关于它们，你们可以在[核心概念/Components 分析组件](main-concepts/components)中得到更详细的介绍，我们以添加组件 `Toolbar` 为例：
@@ -66,6 +80,7 @@ Graphin 目前仅提供两个官方组件，Toolbar 和 ContextMenu。关于它
 ```bash
 $ npm install @antv/graphin-components --save
 ```
+> Graphin-components 基于 antd 组件，因此如果是非 antd 项目，需要手动引入 antd 的 css
 
 -   将组件放在 Graphin 组件内部，这样 `Graphin` 组件可以将 `graph`，`apis` 等属性传递给分析组件：
 
@@ -74,10 +89,13 @@ import React from 'react';
 import ReactDOM from 'react-dom';
 import Graphin, { Utils } from '@antv/graphin';
 import { Toolbar } from '@antv/graphin-components';
+
+import "@antv/graphin/dist/index.css"; // Graphin CSS
+import "@antv/graphin-components/dist/index.css"; // Graphin 组件 CSS
 import './styles.css';
 
 const App = () => {
-    const data = Utils.mock(10).graphin();
+    const data = Utils.mock(10).circle().graphin();
     return (
         <div className="App">
             <Graphin data={data} layout={{ name: 'concentric' }}>
@@ -91,11 +109,22 @@ const rootElement = document.getElementById('root');
 ReactDOM.render(<App />, rootElement);
 ```
 
-这个时候我们再到 CodeSandbox 中去体验下 Toolbar：
+效果如下：
+
+<iframe
+     src="https://codesandbox.io/embed/graphin-components-toolbar-vged5?fontsize=14&theme=dark"
+     style="width:100%; height:600px; border:0; border-radius: 4px; overflow:hidden;"
+     title="quick-starter-toolbar"
+     allow="geolocation; microphone; camera; midi; vr; accelerometer; gyroscope; payment; ambient-light-sensor; encrypted-media; usb"
+     sandbox="allow-modals allow-forms allow-popups allow-scripts allow-same-origin"
+   ></iframe>
+
+关于 Graphin 组件，我们可以到 [Grapin Studio](/zh/GraphinStudio) 中去体验一下功能：
 
 -   todo/redo 撤销重做功能
 -   zoomIn/out 缩小放大功能
 -   fullscreen 全屏功能
+-   contextmenu 右键菜单
 
 ### 04. 事件监听
 
@@ -104,6 +133,8 @@ ReactDOM.render(<App />, rootElement);
 -   1. 得到 Graphin 的 Ref 实例
 -   2. 使用 G6 的 graph 进行事件监听
 
+代码如下：
+
 ```jsx
 const App = () => {
     const data = Utils.mock(10).graphin();
@@ -195,8 +226,8 @@ Graphin 提供两种方式获得 apis 接口，第一种是通过组件的 props
 -   4. 完整代码如下：
 
 <iframe
-     src="https://codesandbox.io/embed/layout-selector-k16mh?fontsize=14&hidenavigation=1&theme=dark"
-     style="width:100%; height:500px; border:0; border-radius: 4px; overflow:hidden;"
+     src="https://codesandbox.io/embed/layout-selector-oplx5?fontsize=14&theme=dark"
+     style="width:100%; height:600px; border:0; border-radius: 4px; overflow:hidden;"
      title="layout-selector"
      allow="geolocation; microphone; camera; midi; vr; accelerometer; gyroscope; payment; ambient-light-sensor; encrypted-media; usb"
      sandbox="allow-modals allow-forms allow-popups allow-scripts allow-same-origin"
@@ -268,12 +299,13 @@ const App = () => {
 -   4. 完整代码如下：
 
 <iframe
-     src="https://codesandbox.io/embed/icy-snow-grltv?fontsize=14&hidenavigation=1&theme=dark"
-     style="width:100%; height:500px; border:0; border-radius: 4px; overflow:hidden;"
+     src="https://codesandbox.io/embed/nodeexpand-3io3m?fontsize=14&theme=dark"
+     style="width:100%; height:600px; border:0; border-radius: 4px; overflow:hidden;"
      title="nodeExpand"
      allow="geolocation; microphone; camera; midi; vr; accelerometer; gyroscope; payment; ambient-light-sensor; encrypted-media; usb"
      sandbox="allow-modals allow-forms allow-popups allow-scripts allow-same-origin"
    ></iframe>
+
 ### 03. 总结与引导
 
 以上就是 Graphin 的快速入门指南，相信大家已经看到了 Graphin 的简单易用之处。其实关于 Graphin 的使用，还有可以有很多开脑洞的想法。比如布局和数据一起改变会发生什么？大家不妨自己试试。想要深入地了解 Graphin，可以继续阅读 [核心概念](main-concepts/data) 和 [进阶指导](advanced-guides/extend) 两部分的内容
diff --git a/packages/graphin-site/docs/manual/main-concepts/data.zh.md b/packages/graphin-site/docs/manual/main-concepts/data.zh.md
@@ -30,8 +30,8 @@ export interface Data {
 
 |   属性 | 说明                                                                                |
 | ------ | ----------------------------------------------------------------------------------- |
-| source | source 是边连接的源节点的 id ，是 `string` 类型                                       |
-| target | target 是边连接的目标节点的 id ，是 `string` 类型                                     |
+| source | source 是边连接的源节点的 id ，是 string 类型                                       |
+| target | target 是边连接的目标节点的 id ，是 string 类型                                     |
 | data   | data 保存了后端返回的边数据，单独用 data 字段来存储是为了避免和 Graphin 的节点数据混在一起 |
 
 > 完整的 API，请查看[API 手册](../apis/#data)
@@ -60,6 +60,10 @@ Graphin 数据全量渲染和增量添加：
 | fontSize     | 12        | 文本的字体大小 |
 | fontColor    | '#3b3b3b' | 文本的字体颜色 |
 | dark         | '#eee'    | dark 置灰      |
+| icon         |  无    | iconfont 的 class      |
+| fontFamily        | 'graphin'    | iconfont 的 fontFamily，默认为 Graphin 内置 icon    |
+
+> 这里的 style 属性规范只针对 Graphin 的内置 Shape。如果是自定义 Shape，从 style 到 G6 节点 attr 的映射可以在 Shape 定义时自行配置
 
 -   自定义 transform 函数
 

diff --git a/packages/graphin/src/controller/layout/index.tsx b/packages/graphin/src/controller/layout/index.tsx
@@ -23,11 +23,6 @@ const noopLayout = () => {
     return [];
 };
 
-/**
- *
- * @param graphin Graphin组件对象
- * @param params
- */
 const layoutController = (
     graphin: Graphin,
     params: LayoutParams,
@@ -66,20 +61,20 @@ const layoutController = (
         return node.x && node.y;
     });
 
-    /** layout不存在，且有位置信息，则认为是save-render操作 */
     if (!(layout && layout.name)) {
+        // layout不存在，且有位置信息，则认为是 save-render 操作
         if (hasPosition) {
             return { data };
         }
-        layout = { name: 'concentric' };
+        layout = { name: 'force' };
     }
 
-    /** 重置forceSimulation  */
+    // 重置forceSimulation
     if (forceSimulation) {
         forceSimulation.stop();
     }
 
-    /** 设置布局的 options参数 */
+    // 设置布局的 options参数
     const { name } = layout;
     const options = {
         graph,
@@ -89,7 +84,7 @@ const layoutController = (
         ...layout.options,
     };
 
-    /** 得到当前匹配的布局函数 */
+    // 得到当前匹配的布局函数
     const matchLayout = layouts.find(item => item.name === name) || {
         name: '',
         icon: '',