feat: merge develop

VisActor · Nov 27, 2024 · cd7ca7f · cd7ca7f
2 parents e2cac46 + 6b9ab6f
commit cd7ca7f
Show file tree

Hide file tree

Showing 12 changed files with 106 additions and 54 deletions.
diff --git a/.github/workflows/release-changelog.yml b/.github/workflows/release-changelog.yml
@@ -61,7 +61,7 @@ jobs:
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
           title: '[Auto changelog] changlog of ${{  github.event.release.tag_name }}'
-          base: feat/vstory-next
+          base: develop
           head: 'docs/generate-changelog-${{  github.event.release.tag_name }}'
           labels: changelog
           body: 'update changelog of ${{  github.event.release.tag_name }}'
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -69,6 +69,9 @@ jobs:
       - name: Build vstory-player
         run: node common/scripts/install-run-rush.js build --only @visactor/vstory-player
 
+      - name: Build vstory-external
+        run: node common/scripts/install-run-rush.js build --only @visactor/vstory-external
+
       - name: Build vstory
         env:
           NODE_OPTIONS: "--max_old_space_size=4096"

diff --git a/.github/workflows/sync-main-to-develop.yml b/.github/workflows/sync-main-to-develop.yml
@@ -55,7 +55,7 @@ jobs:
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
           title: '[Auto Sync] Sync the code from branch main to branch develop after release ${{ steps.package-version.outputs.current_version }}'
-          base: feat/vstory-next
+          base: develop
           head: sync/main-${{ steps.package-version.outputs.current_version }}
           reviewers: xile611
           body: 'Sync the code from branch main to branch develop after release ${{ steps.package-version.outputs.current_version }}'
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,9 +12,9 @@
 
 一个仪表盘会包含多种图表、以及标题、表格等模块、这些模块一部分可以使用VStory中提供的特定character实现，还有一些可以通过VChart自行去配置。在本教程中，我们将简化物料准备过程，直接给到所有用到的图表spec。
 
-1. 一个基于VChart的简单的柱状图
+1. 一个基于`VChart`的简单的柱状图
 ```javascript livedemo template=vchart
-const mockData: any = [];
+const mockData = [];
 const types = ['A', 'B', 'C'];
 
 types.forEach(type => {
@@ -44,9 +44,9 @@ vchart.renderSync();
 window['vchart'] = vchart;
 ```
 
-2. 一个基于VChart的简单的面积图
+2. 一个基于`VChart`的简单的面积图
 ```javascript livedemo template=vchart
-const mockData: any = [];
+const mockData = [];
 const types = ['A', 'B', 'C'];
 
 types.forEach(type => {
@@ -60,7 +60,7 @@ const spec = {
   data: [
     {
       id: 'id0',
-      values: mockData.filter((item: any) => item.type !== 'C')
+      values: mockData.filter((item) => item.type !== 'C')
     }
   ],
   xField: 'month',
@@ -81,9 +81,9 @@ vchart.renderSync();
 window['vchart'] = vchart;
 ```
 
-3. 一个基于VChart的简单的雷达图
+3. 一个基于`VChart`的简单的雷达图
 ```javascript livedemo template=vchart
-const mockData: any = [];
+const mockData = [];
 const types = ['A', 'B', 'C'];
 
 types.forEach(type => {
@@ -132,9 +132,9 @@ 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: any = [];
+const mockData = [];
 const types = ['A', 'B', 'C'];
 
 types.forEach(type => {
@@ -170,9 +170,9 @@ 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: any = [];
+const mockData = [];
 const types = ['A', 'B', 'C'];
 
 types.forEach(type => {
@@ -209,10 +209,15 @@ vchart.renderSync();
 window['vchart'] = vchart;
 ```
 
-6. 使用一个VStory的Text类型作为标题
+6. 使用一个`VStory`的`Text`类型作为标题
 ```javascript livedemo template=vstory
 // 注册所有需要的内容
 VStory.registerAll();
+
+const story = new VStory.Story(null, { dom: CONTAINER_ID, background: '#ebecf0' });
+const player = new VStory.Player(story);
+story.init(player);
+
 story.addCharacterWithAppear({
   type: 'Text',
   id: 'title',
@@ -239,19 +244,15 @@ story.addCharacterWithAppear({
   }
 });
 
-const story = new VStory.Story(null, { dom: CONTAINER_ID, background: '#ebecf0' });
-const player = new VStory.Player(story);
-story.init(player);
-
 player.play(-1);
 window.vstory = story;
 ```
-7. 使用一个VStory的WaveScatter图表类型
+7. 使用一个`VStory`的`WaveScatter`图表类型
 
 ```javascript livedemo template=vstory
 // 注册所有需要的内容
 VStory.registerAll();
-const mockData: any = [];
+const mockData = [];
 const types = ['A', 'B', 'C'];
 
 types.forEach(type => {
@@ -260,6 +261,10 @@ types.forEach(type => {
   }
 });
 
+const story = new VStory.Story(null, { dom: CONTAINER_ID, background: '#ebecf0' });
+const player = new VStory.Player(story);
+story.init(player);
+
 story.addCharacterWithAppear({
   type: 'WaveScatter',
   id: 'wave-scatter',
@@ -272,7 +277,7 @@ story.addCharacterWithAppear({
   },
   options: {
     data: {
-      values: mockData.filter((item: any) => item.type === 'A')
+      values: mockData.filter((item) => item.type === 'A')
     },
     categoryField: 'month',
     valueField: 'value',
@@ -295,21 +300,17 @@ story.addCharacterWithAppear({
   }
 });
 
-const story = new VStory.Story(null, { dom: CONTAINER_ID, background: '#ebecf0' });
-const player = new VStory.Player(story);
-story.init(player);
-
 player.play(-1);
 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 {
@@ -356,7 +357,7 @@ interface IAction {
 ```
 
 ### 2.1 character数组配置
-根据我们提供的每个character的配置，以及接口定义，我们可以组装我们的character数组。
+根据我们提供的每个`character`的配置，以及接口定义，我们可以组装我们的`character`数组。
 
 ```ts
 const characters = [
@@ -394,7 +395,7 @@ const characters = [
     },
     options: {
       data: {
-        values: mockData.filter((item: any) => item.type === 'A')
+        values: mockData.filter((item) => item.type === 'A')
       },
       categoryField: 'month',
       valueField: 'value',
@@ -535,7 +536,7 @@ const characters = [
 ]
 ```
 ### 2.2 acts数组配置
-characters数组中只是定义了作品中有这些元素可用，具体的动作还没有定义，如果不定义动作的话，元素将不会展示，所以接下来我们开始定义acts数组。我们期望作品中的元素有如下动作
+`characters`数组中只是定义了作品中有这些元素可用，具体的动作还没有定义，如果不定义动作的话，元素将不会展示，所以接下来我们开始定义`acts`数组。我们期望作品中的元素有如下动作
 
 1. 柱状图和玫瑰图会有`oneByOne`(图元一个接着一个)的`appear`(入场)动画效果，其他图表都是默认的`appear`（入场）的动画效果
 2. 包含图表本身的面板也要有一个`bounce`(弹跳)的`appear`(入场)的动画效果
@@ -607,7 +608,7 @@ const acts = [
 
 ## 3. 播放
 
-至此，我们已经完成了一个简易的仪表盘的制作步骤，接下来，我们将character和acts数组拼起来合成一个DSL，然后使用 VStory 进行播放。
+至此，我们已经完成了一个简易的仪表盘的制作步骤，接下来，我们将`character`和`acts`数组拼起来合成一个DSL，然后使用 VStory 进行播放。
 
 ```ts
 // 注册所有需要的内容
@@ -998,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)。
 
 ## 图表示例