VisActor · neuqzxy · Nov 26, 2024 · Nov 26, 2024
diff --git a/common/config/rush/pnpm-lock.yaml b/common/config/rush/pnpm-lock.yaml
diff --git a/docs/assets/guide/menu.json b/docs/assets/guide/menu.json
@@ -69,8 +69,8 @@
             {
               "path": "story-player",
               "title": {
-                "zh": "Story-Player",
-                "en": "Story-Player"
+                "zh": "Story 和 Player",
+                "en": "Story and Player"
               }
             }
           ]

diff --git a/docs/assets/guide/zh/tutorial_docs/Basic/A_Basic_DSL.md b/docs/assets/guide/zh/tutorial_docs/Basic/A_Basic_DSL.md
@@ -12,7 +12,7 @@
 
 一个仪表盘会包含多种图表、以及标题、表格等模块、这些模块一部分可以使用VStory中提供的特定character实现，还有一些可以通过VChart自行去配置。在本教程中，我们将简化物料准备过程，直接给到所有用到的图表spec。
 
-1. 一个基于VChart的简单的柱状图
+1. 一个基于`VChart`的简单的柱状图
 ```javascript livedemo template=vchart
 const mockData = [];
 const types = ['A', 'B', 'C'];
@@ -44,7 +44,7 @@ vchart.renderSync();
 window['vchart'] = vchart;
 ```
 
-2. 一个基于VChart的简单的面积图
+2. 一个基于`VChart`的简单的面积图
 ```javascript livedemo template=vchart
 const mockData = [];
 const types = ['A', 'B', 'C'];
@@ -81,7 +81,7 @@ vchart.renderSync();
 window['vchart'] = vchart;
 ```
 
-3. 一个基于VChart的简单的雷达图
+3. 一个基于`VChart`的简单的雷达图
 ```javascript livedemo template=vchart
 const mockData = [];
 const types = ['A', 'B', 'C'];
@@ -132,7 +132,7 @@ vchart.renderSync();
 // Just for the convenience of console debugging, DO NOT COPY!
 window['vchart'] = vchart;
 ```
-4. 一个基于VChart的简单的玫瑰图
+4. 一个基于`VChart`的简单的玫瑰图
 ```javascript livedemo template=vchart
 const mockData = [];
 const types = ['A', 'B', 'C'];
@@ -170,7 +170,7 @@ vchart.renderSync();
 // Just for the convenience of console debugging, DO NOT COPY!
 window['vchart'] = vchart;
 ```
-5. 一个基于VChart的简单的仪表盘图
+5. 一个基于`VChart`的简单的仪表盘图
 ```javascript livedemo template=vchart
 const mockData = [];
 const types = ['A', 'B', 'C'];
@@ -209,7 +209,7 @@ vchart.renderSync();
 window['vchart'] = vchart;
 ```
 
-6. 使用一个VStory的Text类型作为标题
+6. 使用一个`VStory`的`Text`类型作为标题
 ```javascript livedemo template=vstory
 // 注册所有需要的内容
 VStory.registerAll();
@@ -247,7 +247,7 @@ story.addCharacterWithAppear({
 player.play(-1);
 window.vstory = story;
 ```
-7. 使用一个VStory的WaveScatter图表类型
+7. 使用一个`VStory`的`WaveScatter`图表类型
 
 ```javascript livedemo template=vstory
 // 注册所有需要的内容
@@ -306,11 +306,11 @@ window.vstory = story;
 
 ## 2. 拼接
 
-接下来，我们将这些素材拼接到VStory的大画布中，形成一个完整的作品，我们使用1920 * 1080作为画布的完整尺寸，图表之间的margin为30px，距离左右边界的margin也是30px。具体的布局如下图所示
+接下来，我们将这些素材拼接到`VStory`的大画布中，形成一个完整的作品，我们使用1920 * 1080作为画布的完整尺寸，图表之间的`margin`为30px，距离左右边界的`margin`也是30px。具体的布局如下图所示
 
 ![](https://lf9-dp-fe-cms-tos.byteorg.com/obj/bit-cloud/vstory/dashboard_layout_detail.png)
 
-完成了布局的设计之后，接下来我们开始DSL的编写，来实现上图中的效果，DSL核心包括一个character数组和一个acts数组，character数组包含了作品中的所有角色（元素），acts数组包含了作品中的各种角色的各种动作（动画），具体的接口定义如下：
+完成了布局的设计之后，接下来我们开始DSL的编写，来实现上图中的效果，DSL核心包括一个`character`数组和一个`acts`数组，`character`数组包含了作品中的所有角色（元素），`acts`数组包含了作品中的各种角色的各种动作（动画），具体的接口定义如下：
 
 ```ts
 interface IStoryDSL {
@@ -357,7 +357,7 @@ interface IAction {
 ```
 
 ### 2.1 character数组配置
-根据我们提供的每个character的配置，以及接口定义，我们可以组装我们的character数组。
+根据我们提供的每个`character`的配置，以及接口定义，我们可以组装我们的`character`数组。
 
 ```ts
 const characters = [
@@ -536,7 +536,7 @@ const characters = [
 ]
 ```
 ### 2.2 acts数组配置
-characters数组中只是定义了作品中有这些元素可用，具体的动作还没有定义，如果不定义动作的话，元素将不会展示，所以接下来我们开始定义acts数组。我们期望作品中的元素有如下动作
+`characters`数组中只是定义了作品中有这些元素可用，具体的动作还没有定义，如果不定义动作的话，元素将不会展示，所以接下来我们开始定义`acts`数组。我们期望作品中的元素有如下动作
 
 1. 柱状图和玫瑰图会有`oneByOne`(图元一个接着一个)的`appear`(入场)动画效果，其他图表都是默认的`appear`（入场）的动画效果
 2. 包含图表本身的面板也要有一个`bounce`(弹跳)的`appear`(入场)的动画效果
@@ -608,7 +608,7 @@ const acts = [
 
 ## 3. 播放
 
-至此，我们已经完成了一个简易的仪表盘的制作步骤，接下来，我们将character和acts数组拼起来合成一个DSL，然后使用 VStory 进行播放。
+至此，我们已经完成了一个简易的仪表盘的制作步骤，接下来，我们将`character`和`acts`数组拼起来合成一个DSL，然后使用 VStory 进行播放。
 
 ```ts
 // 注册所有需要的内容
@@ -999,4 +999,4 @@ window['story'] = story;
 window['vstory'] = story;
 ```
 
-通过本教程，您已经了解了一份基础的 DSL 配置组成，后面你可以尝试更改Character和Acts，探索 VStory 的强大功能和灵活性，编绘出绚丽多彩的作品。祝您编码愉快！
+通过本教程，您已经了解了一份基础的 DSL 配置组成，后面你可以尝试更改`character`和`acts`，探索 VStory 的强大功能和灵活性，编绘出绚丽多彩的作品。祝您编码愉快！
diff --git a/docs/assets/guide/zh/tutorial_docs/VStory_Concepts/dsl.md b/docs/assets/guide/zh/tutorial_docs/VStory_Concepts/dsl.md
@@ -3,11 +3,11 @@
 DSL是描述一个VStory作品的JSON格式。其中定义了这个作品中使用了哪些元素，以及相关配置。描述了这个作品是如何编排的，什么元素在什么时刻做了什么行为。关于DSL的快速实战入门请参考[一份基础的 DSL](../Basic/A_Basic_DSL)。本节教程将详细介绍DSL的具体定义。
 
 ## 结构
-DSL 是一个 JSON 格式的对象，包含以下几个字段：
-1. character数组
-  character 数组用于描述这个作品中使用了哪些元素，以及相关配置。
-2. acts数组
-  acts 数组用于描述这个作品是如何编排的，什么元素在什么时刻做了什么行为。
+`DSL` 是一个 JSON 格式的对象，包含以下几个字段：
+1. `character`数组
+  `character` 数组用于描述这个作品中使用了哪些元素，以及相关配置。
+2. `acts`数组
+  `acts` 数组用于描述这个作品是如何编排的，什么元素在什么时刻做了什么行为。
 
 ```ts
 interface IStoryDSL {
@@ -17,7 +17,7 @@ interface IStoryDSL {
 ```
 
 ### character数组
-character 数组用于描述这个作品中使用了哪些类型的元素，以及相关配置。其中包含位置大小（position），层级（layout）。
+`character` 数组用于描述这个作品中使用了哪些类型的元素，以及相关配置。其中包含位置大小（`position`），层级（`layout`）。
 
 ```ts
 type ICharacterConfig = IChartCharacterConfig | IComponentCharacterConfig;
@@ -50,7 +50,7 @@ interface ICharacterConfigBase {
 }
 ```
 
-目前character有三大类型，分别是图表、组件、表格。主要是因为这三大类型的配置有较大差异，然后每个类型下面还有无数的子类型，比如组件类型，你可以自定义任意的组件，然后注册到VStory中在DSL中使用。
+目前`character`有三大类型，分别是图表、组件、表格。主要是因为这三大类型的配置有较大差异，然后每个类型下面还有无数的子类型，比如组件类型，你可以自定义任意的组件，然后注册到VStory中在DSL中使用。
 
 #### 图表类型
 
@@ -103,7 +103,7 @@ interface IChartCharacterConfig extends ICharacterConfigBase {
 #### 组件类型
 
 文字、图片等都属于组件类型，如果需要在VStory中使用自定义组件，需要先注册到VStory中，然后在DSL中使用。这个在[自定义组件](./Custom_Component)中会详细介绍。
-注意的是，组件可以携带一个额外的文本，这个文本通过text属性配置，而graphic属性则是组件本身的配置。
+注意的是，组件可以携带一个额外的文本，这个文本通过`text`属性配置，而`graphic`属性则是组件本身的配置。
 ```ts
 interface IComponentCharacterConfig extends ICharacterConfigBase {
   options: {
@@ -122,7 +122,8 @@ interface IComponentCharacterConfig extends ICharacterConfigBase {
 正在开发中
 
 ### Acts数组
-通过characters数组，我们可以在画布中放置多个元素，接下来我们需要通过acts数组来描述这个作品是如何编排的，什么元素在什么时刻做了什么行为。Acts由幕、场景、动作组成。acts数组中可以包含多个幕，幕与幕之间是有先后顺序的串联结构。每一个幕中可以包含多个场景，场景与场景默认是有先后顺序的串联结构。但是场景和场景的时间线是可以重叠的，通过配置场景的delay字段，可以控制该场景与上一个场景时间线的偏移。每一个场景中可以包含多个动作，动作中描述了一个或多个character的具体行为，一个场景中可以包含多个character和多个动作，动作之间是并行执行的，通过配置startTime来控制该动作的开始时间。
+通过`characters`数组，我们可以在画布中放置多个元素，接下来我们需要通过`acts`数组来描述这个作品是如何编排的，什么元素在什么时刻做了什么行为。`acts`由幕、场景、动作组成。
+`acts`数组中可以包含多个幕，幕与幕之间是有先后顺序的串联结构。每一个幕中可以包含多个场景，场景与场景默认是有先后顺序的串联结构。但是场景和场景的时间线是可以重叠的，通过配置场景的`delay`字段，可以控制该场景与上一个场景时间线的偏移。每一个场景中可以包含多个动作，动作中描述了一个或多个`character`的具体行为，一个场景中可以包含多个`character`和多个动作，动作之间是并行执行的，通过配置`startTime`来控制该动作的开始时间。
 
 #### 幕
 幕是作品中最大的章节，一个作品可以包含多个幕，幕与幕之间是有先后顺序的串联结构。
@@ -133,7 +134,7 @@ interface IActSpec {
 }
 ```
 #### 场景
-场景是一个时间线，一个场景包含一个动作数组，场景与场景默认是有先后顺序的串联结构，但也可以通过配置delay字段来控制该场景与上一个场景时间线的偏移。
+场景是一个时间线，一个场景包含一个动作数组，场景与场景默认是有先后顺序的串联结构，但也可以通过配置`delay`字段来控制该场景与上一个场景时间线的偏移。
 ```ts
 type ISceneSpec = {
   id: string;
@@ -142,7 +143,7 @@ type ISceneSpec = {
 };
 ```
 #### 动作
-一个动作包含一个或多个character的具体行为，一个场景中可以包含多个动作，动作之间是并行执行的，通过配置startTime来控制该动作的开始时间。
+一个动作包含一个或多个`character`的具体行为，一个场景中可以包含多个动作，动作之间是并行执行的，通过配置`startTime`来控制该动作的开始时间。
 ```ts
 interface IActions {
   characterId: string | string[]; // 要执行动作的character的id或者数组
@@ -174,4 +175,4 @@ export interface IAnimationParams {
 }
 ```
 
-到这里，一个DSL的完整定义就完成了，大家可以自己动手试一下，或者去example[/vstory/example]里去改一改试一试。
+到这里，一个DSL的完整定义就完成了，大家可以自己动手试一下，或者去[example](/vstory/example)里去改一改试一试。
diff --git a/docs/assets/guide/zh/tutorial_docs/VStory_Concepts/story-player.md b/docs/assets/guide/zh/tutorial_docs/VStory_Concepts/story-player.md
@@ -1,6 +1,6 @@
 # Story和Player
 
-首先建议大家阅读[dsl]()的章节，了解如何编写一个VStory的DSL描述。当我们有了一个DSL的JSON描述之后，我们就需要进行VStory的实例化，然后使用播放器去播放作品了。
+首先建议大家阅读[dsl](./dsl)的章节，了解如何编写一个VStory的DSL描述。当我们有了一个DSL的JSON描述之后，我们就需要进行VStory的实例化，然后使用播放器去播放作品了。
 
 ## 注册
 
@@ -40,7 +40,7 @@ story.load(dsl);
 
 ## 命令添加character（可选）
 
-如果您的DSL中没有包含character，那么您可以使用命令添加character。如果您已经静态的定义好了DSL，这个步骤就不需要
+如果您的DSL中没有包含`character`，那么您可以使用命令添加`character`。如果您已经静态的定义好了DSL，这个步骤就不需要
 
 ```ts
 // 接口定义如下
@@ -108,15 +108,15 @@ story.addCharacterWithAppear({
 
 ## 创建Player并绑定Story
 
-创建好Story之后，我们就可以进行播放流程了，我们需要创建一个Player实例，然后绑定Story实例。
+创建好`Story`之后，我们就可以进行播放流程了，我们需要创建一个`Player`实例，然后绑定`Story`实例。
 
 ```ts
 // 创建Player实例
 const player = new Player(story);
 // 初始化Story
 story.init(player);
 ```
-接下来调用`player.play()`即可播放。play方法接收一个number类型的参数，可传入0,-1,1
+接下来调用`player.play()`即可播放。`play`方法接收一个`number`类型的参数，可传入0,-1,1
 传入0表示只播放一次，播放到结尾就停止
 传入1表示循环播放，播放到结尾就从头开始播放
 传入-1表示不循环也不停止，播放到结尾之后时间线继续往后走，适用于有循环动画的场景，比如有一个持续播放的背景动画
@@ -130,4 +130,4 @@ player.play(1);
 player.play(-1);
 ```
 
-到这里，story和player的定义就介绍完了，大家可以自己动手试一下，或者去example[/vstory/example]里去改一改试一试。
+到这里，`story`和`player`的定义就介绍完了，大家可以自己动手试一下，或者去example[/vstory/example]里去改一改试一试。
diff --git a/docs/assets/guide/zh/tutorial_docs/VStory_Website_Guide.md b/docs/assets/guide/zh/tutorial_docs/VStory_Website_Guide.md
@@ -17,9 +17,10 @@
 VStory 的文档提供了有关功能和配置的详细信息。根据你的需求，你可以查看以下几个部分：
 
 - [教程](./VStory_Website_Guide)：介绍了 VStory 的基本概念和各种使用方法。
-- [组件](../../components)：提供了 VStory 图表的所有组件配置及其详细说明。
+- [概念](./VStory_Concepts/dsl)：提供了 VStory `DSL` 的定义以及核心类的介绍。
+- [扩展](./extend/Custom_Character)：提供了自定义扩展的教程和指南。
 
-另外，为了更好的使用VStory，建议你再了解一下[VChart](/Vchart)、[VTable](/VTable)。
+另外，为了更好的使用VStory，建议你再了解一下[VChart](/Vchart)、[VTable](/VTable)、[VRender](/VRender)。
 
 ## 图表示例
 

diff --git a/docs/assets/guide/zh/tutorial_docs/extend/Custom_Character.md b/docs/assets/guide/zh/tutorial_docs/extend/Custom_Character.md
@@ -6,6 +6,8 @@
 
 我们提供了`@visactor/vstory-external`包，用于方便用户进行自定义Character的开发。一些扩展功能都可以在这个包中实现。下面我们通过一个接入Lottie的例子来介绍如何在这个包中进行扩展。
 
+![](https://lf9-dp-fe-cms-tos.byteorg.com/obj/bit-cloud/vstory/vstory-external.png)
+
 ## 自定义一个Lottie的Character
 
 如果需要在作品中现在需要展示一个Lottie动画，但是VStory的主包里并没有提供这样的Character。现在我们就需要在`@visactor/vstory-external`包中进行扩展。
@@ -173,3 +175,44 @@ export class LottieVisibilityActionProcessor extends CommonVisibilityActionProce
 
 接下来我们导出`Character`和`Processor`的注册方法即可。
 具体的代码大家在`packages/vstory-external/src/character/lottie`和`packages/vstory-external/src/processor/lottie`中可以看到。
+
+最终，我们就可以在`DSL`中使用`Lottie`了。
+
+```javascript livedemo template=vstory
+// 注册所有需要的内容
+VStory.registerAll();
+// 注册Lottie
+VStory.registerLottie();
+VStory.registerLottieAction();
+
+const story = new VStory.Story(null, { dom: CONTAINER_ID, background: '#ebecf0' });
+const player = new VStory.Player(story);
+story.init(player);
+
+story.addCharacterWithAppear({
+  type: 'Lottie',
+  id: 'lottie-test',
+  zIndex: 2,
+  position: {
+    top: 50,
+    left: 50,
+    width: 300,
+    height: 300
+  },
+  options: {
+    graphic: {
+      data: 'loading1'
+    },
+    panel: {
+      fill: '#ffffff',
+      shadowColor: 'rgba(0, 0, 0, 0.05)',
+      shadowBlur: 10,
+      shadowOffsetX: 4,
+      shadowOffsetY: 4
+    }
+  }
+});
+
+player.play(-1);
+window.vstory = story;
+```
diff --git a/packages/vstory/package.json b/packages/vstory/package.json
@@ -28,7 +28,8 @@
     "@visactor/vstory-animate": "workspace:0.0.12",
     "@visactor/vstory-editor": "workspace:0.0.12",
     "@visactor/vstory-player": "workspace:0.0.12",
-    "@visactor/vstory-templates": "workspace:0.0.12"
+    "@visactor/vstory-templates": "workspace:0.0.12",
+    "@visactor/vstory-external": "workspace:0.0.12"
   },
   "devDependencies": {
     "@internal/bundler": "workspace:*",

diff --git a/packages/vstory/src/index.ts b/packages/vstory/src/index.ts
@@ -4,6 +4,7 @@ import { registerCommonBounceAction, registerVChartAction, registerVComponentAct
 export * from '@visactor/vstory-core';
 export * from '@visactor/vstory-player';
 export * from '@visactor/vstory-templates';
+export * from '@visactor/vstory-external';
 
 export function registerAll() {
   registerGraphics();