Merge pull request #121 from VisActor/docs/tutorial-update

Docs/tutorial update
VisActor · Nov 27, 2024 · 906170c · 906170c
2 parents 31d031d + f80cf62
commit 906170c
Show file tree

Hide file tree

Showing 10 changed files with 2,501 additions and 10 deletions.
diff --git a/docs/assets/guide/en/tutorial_docs/Basic/A_Basic_DSL.md b/docs/assets/guide/en/tutorial_docs/Basic/A_Basic_DSL.md
diff --git a/docs/assets/guide/en/tutorial_docs/Basic/How_to_Get_VStory.md b/docs/assets/guide/en/tutorial_docs/Basic/How_to_Get_VStory.md
@@ -0,0 +1,40 @@
+# How to Get VStory
+
+There are several ways to get VStory:
+
+1. Get from npm
+2. Get from cdn
+3. Get from GitHub repository
+
+## Get from npm
+
+```bash
+# npm
+$ npm install @visactor/vstory
+
+# yarn
+$ yarn add @visactor/vstory
+```
+
+For how to use when getting, see [How to Import VStory in Your Project](./How_to_Import_VStory).
+
+## Get from cdn
+
+> Note: When importing VStory via cdn, pay attention to the way of referencing VStory: `const story = new VStory.Story(dsl, { dom: 'chart' });`
+
+You can get VStory from the following free CDNs:
+
+```html
+<!-- unpkg -->
+<script src="https://unpkg.com/@visactor/vstory/build/index.min.js"></script>
+
+<!-- jsDelivr -->
+<script src="https://cdn.jsdelivr.net/npm/@visactor/vstory/build/index.min.js"></script>
+```
+
+## Get from GitHub
+
+You can directly get the source code of VStory from GitHub:
+
+1. You can clone the source code directly from GitHub.
+2. You can also choose the corresponding version from the [release](https://github.com/VisActor/VStory/releases) page of VStory on GitHub, click on the Source code under Assets at the bottom of the page, download it to your local machine, unzip it, and then use it.
diff --git a/docs/assets/guide/en/tutorial_docs/Basic/How_to_Import_VStory.md b/docs/assets/guide/en/tutorial_docs/Basic/How_to_Import_VStory.md
@@ -0,0 +1,237 @@
+# How to Reference VStory in Your Project
+
+In the [How to Get VStory](./How_to_Get_VStory) section, we introduced how to get VStory. This section will explain how to reference VStory under these acquisition methods.
+
+## CDN Usage
+
+After we get the VStory file from [cdn](./How_to_Get_VStory#cdn-获取), we can add it to the `<script>` tag in the HTML file:
+
+**Note: When using the CDN method to import, pay attention to the way VStory is referenced:**
+
+`const story = new VStory.story(dsl, { dom: 'chart' });`
+
+```html
+<body>
+  <div id="chart" style="outline: solid red 1px; width: 100%; height: 500px"></div>
+</body>
+<!-- Import VStory -->
+<script src="https://unpkg.com/@visactor/vstory/build/index.min.js"></script>
+
+<script>
+  // Register all content
+  VStory.registerAll();
+  // Create a pie chart
+  const spec = {
+    type: 'pie',
+    data: [
+      {
+        id: 'id0',
+        values: [
+          { type: 'oxygen', value: '46.60' },
+          { type: 'silicon', value: '27.72' },
+          { type: 'aluminum', value: '8.13' },
+          { type: 'iron', value: '5' },
+          { type: 'calcium', value: '3.63' },
+          { type: 'sodium', value: '2.83' },
+          { type: 'potassium', value: '2.59' },
+          { type: 'others', value: '3.5' }
+        ]
+      }
+    ],
+    outerRadius: 0.8,
+    valueField: 'value',
+    categoryField: 'type',
+    title: {
+      visible: true,
+      text: 'Surface element content statistics'
+    },
+    legends: {
+      visible: true,
+      orient: 'left'
+    },
+    label: {
+      visible: true
+    },
+    tooltip: {
+      mark: {
+        content: [
+          {
+            key: datum => datum['type'],
+            value: datum => datum['value'] + '%'
+          }
+        ]
+      }
+    }
+  };
+  // Create a DSL
+  const dsl = {
+    characters: [
+      {
+        type: 'VChart',
+        id: '0',
+        position: {
+          top: 50,
+          left: 50,
+          width: 300,
+          height: 300
+        },
+        options: {
+          spec,
+          panel: {
+            fill: '#ffffff',
+            shadowColor: 'rgba(0, 0, 0, 0.05)',
+            shadowBlur: 10,
+            shadowOffsetX: 4,
+            shadowOffsetY: 4,
+            cornerRadius: 8
+          },
+        }
+      }
+    ],
+    acts: [
+      {
+        id: 'default-chapter',
+        scenes: [
+          {
+            id:'scene0',
+            actions: [
+              {
+                characterId: '0',
+                characterActions: [
+                  {
+                    action: 'appear',
+                    payload: {
+                      animation: {
+                        duration: 3000
+                      }
+                    }
+                  }
+                ]
+              }
+            ]
+          }
+        ]
+      }
+    ]
+  }
+
+  // Create a vstory instance
+  const story = new VStory.Story(dsl, { dom: 'chart', background: 'pink' });
+  const player = new VStory.Player(story);
+  story.init(player);
+
+  player.play(0);
+
+</script>
+```
+
+## NPM Usage
+
+After we install `@visactor/vstory` into the project through the [npm](./How_to_Get_VStory#npm-获取) method, we can use it in the following way:
+
+```ts
+import { registerAll, Story, Player } from '@visactor/vstory';
+// Register all content
+registerAll();
+const spec = {
+  type: 'pie',
+  data: [
+    {
+      id: 'id0',
+      values: [
+        { type: 'oxygen', value: '46.60' },
+        { type: 'silicon', value: '27.72' },
+        { type: 'aluminum', value: '8.13' },
+        { type: 'iron', value: '5' },
+        { type: 'calcium', value: '3.63' },
+        { type: 'sodium', value: '2.83' },
+        { type: 'potassium', value: '2.59' },
+        { type: 'others', value: '3.5' }
+      ]
+    }
+  ],
+  outerRadius: 0.8,
+  valueField: 'value',
+  categoryField: 'type',
+  title: {
+    visible: true,
+    text: 'Surface element content statistics'
+  },
+  legends: {
+    visible: true,
+    orient: 'left'
+  },
+  label: {
+    visible: true
+  },
+  tooltip: {
+    mark: {
+      content: [
+        {
+          key: datum => datum['type'],
+          value: datum => datum['value'] + '%'
+        }
+      ]
+    }
+  }
+};
+
+// Create a DSL
+const dsl = {
+  characters: [
+    {
+      type: 'VChart',
+      id: '0',
+      position: {
+        top: 50,
+        left: 50,
+        width: 300,
+        height: 300
+      },
+      options: {
+        spec,
+        panel: {
+          fill: '#ffffff',
+          shadowColor: 'rgba(0, 0, 0, 0.05)',
+          shadowBlur: 10,
+          shadowOffsetX: 4,
+          shadowOffsetY: 4,
+          cornerRadius: 8
+        },
+      }
+    }
+  ],
+  acts: [
+    {
+      id: 'default-chapter',
+      scenes: [
+        {
+          id:'scene0',
+          actions: [
+            {
+              characterId: '0',
+              characterActions: [
+                {
+                  action: 'appear',
+                  payload: {
+                    animation: {
+                      duration: 3000
+                    }
+                  }
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}
+
+// Create a vstory instance
+const story = new Story(dsl, { dom: 'chart', background: 'pink' });
+const player = new Player(story);
+story.init(player);
+
+player.play(0);
+```