From 4744bfe2db01987e89843dfcd0c0facd8168ada8 Mon Sep 17 00:00:00 2001 From: imtaotao Date: Sat, 3 Aug 2024 23:16:05 +0800 Subject: [PATCH] docs: adjust document content --- .../content/docs/zh/guide/create-plugin.mdx | 9 ++- .../content/docs/zh/guide/getting-started.mdx | 24 +++--- .../docs/zh/guide/typescript-interface.mdx | 3 +- docs/src/content/docs/zh/reference/index.mdx | 1 + .../content/docs/zh/reference/manager-api.mdx | 74 ++++++++++++------- .../docs/zh/reference/manager-config.mdx | 12 ++- 6 files changed, 75 insertions(+), 48 deletions(-) diff --git a/docs/src/content/docs/zh/guide/create-plugin.mdx b/docs/src/content/docs/zh/guide/create-plugin.mdx index b273021c..31abec21 100644 --- a/docs/src/content/docs/zh/guide/create-plugin.mdx +++ b/docs/src/content/docs/zh/guide/create-plugin.mdx @@ -52,10 +52,15 @@ import { Steps } from '@astrojs/starlight/components'; 你需要通过 `mananger.use()` 来注册插件。 - ```ts title="init.ts" {6-9} + ```ts title="init.ts" {12-13} import { create } from 'danmu'; - const manager = create(); + interface ValueType { + userId: number; + content: string; + } + + const manager = create(); manager.use( filter({ diff --git a/docs/src/content/docs/zh/guide/getting-started.mdx b/docs/src/content/docs/zh/guide/getting-started.mdx index 9908c87e..13374914 100644 --- a/docs/src/content/docs/zh/guide/getting-started.mdx +++ b/docs/src/content/docs/zh/guide/getting-started.mdx @@ -94,20 +94,15 @@ manager.mount(container).startPlaying(); 当前面的一些工作准备完成之后，就可以发送弹幕了。 ```ts -manager.push({ - id: 1, // id 是可选的 - value: '弹幕内容', // value 的类型可以在创建 manager 的时候通过范型来约定，可以看后面的小节 -}); +// value 的类型可以在创建 manager 的时候通过范型来约定，可以看后面的小节 +manager.push('弹幕内容'); ``` 但是通过 [**`push`**](../../reference/manager-api/#push) 方法来发送的弹幕可能会受到弹幕算法的影响，不会立即渲染，想象一些往一个数组里面 push 一个数据，但是消费是从数组最前端拿出数据消费的。我们可以换一个 [**`unshift`**](../../reference/manager-api/#unshift) 方法来发送弹幕。 ```ts // 在下一次渲染轮询中，立即渲染 -manager.unshift({ - id: 1, - value: '弹幕内容', -}); +manager.unshift('弹幕内容'); ``` 我们在初始化 `manager` 的时候，可以通过 `plugin` 属性来传递默认全局插件，他的作用域是对所有的弹幕都生效，而且包含[**全局**](../../reference/manager-hooks)和[**弹幕**](../../reference/danmaku-hooks)两种类型的钩子。 @@ -115,15 +110,16 @@ manager.unshift({ 不过我们在发送弹幕的时候，也可以传递弹幕自己的插件，他不包含全局钩子，**作用域只对当前渲染的弹幕生效**，如果你需要的话，这会让你更好的来控制当前要渲染的这个弹幕。 ```ts -manager.push( - { value: '弹幕内容' }, - { +manager.push('弹幕内容', { + // ... 其他属性，详情见 push api 文档 + id: 1, // 可选参数 + plugin: { moveStart(danmaku) { // moveStart 钩子会在弹幕即将开始运动之前触发，你可以在这里更改弹幕的样式 danmaku.setStyle(csskey, cssValue); }, }, -); +}); ``` ### 5. 发送高级弹幕 @@ -132,11 +128,9 @@ manager.push( ```diff lang="ts" manager.pushFlexibleDanmaku( + '弹幕内容', { id: 1, // 可选参数 - value: '弹幕内容', - }, - { duration: 1000, // 默认从 manager.options.times 中随机取一个值 direction: 'none', // 默认取 manager.options.direction 的值 position: (danmaku, box) => { diff --git a/docs/src/content/docs/zh/guide/typescript-interface.mdx b/docs/src/content/docs/zh/guide/typescript-interface.mdx index 22de4128..041cf9e3 100644 --- a/docs/src/content/docs/zh/guide/typescript-interface.mdx +++ b/docs/src/content/docs/zh/guide/typescript-interface.mdx @@ -45,7 +45,8 @@ import type { Mode, StyleKey, Position, - PushData, + PushOptions, + PushFlexOptions, ValueType, Direction, CreateOption, diff --git a/docs/src/content/docs/zh/reference/index.mdx b/docs/src/content/docs/zh/reference/index.mdx index 2665edd9..d471f8df 100644 --- a/docs/src/content/docs/zh/reference/index.mdx +++ b/docs/src/content/docs/zh/reference/index.mdx @@ -96,6 +96,7 @@ import { Tabs, TabItem } from '@astrojs/starlight/components'; [**`show()`**](./manager-api/#show)
[**`nextFrame()`**](./manager-api/#nextframe)
[**`updateOccludedUrl()`**](./manager-api/#updateoccludedurl)
+ [**`render()`**](./manager-api/#render)
[**`remove()`**](./manager-api/#remove)
[**`use()`**](./manager-api/#use) diff --git a/docs/src/content/docs/zh/reference/manager-api.mdx b/docs/src/content/docs/zh/reference/manager-api.mdx index 1de4d11a..4be44c1b 100644 --- a/docs/src/content/docs/zh/reference/manager-api.mdx +++ b/docs/src/content/docs/zh/reference/manager-api.mdx @@ -256,34 +256,42 @@ manager.canPush('flexible'); ### `push()` -**类型：`(data: PushData, plugin?: DanmakuPlugin) => boolean`** +**类型：`(data: T, options?: PushOptions) => boolean`** 发送一条弹幕，这条弹幕会被放在内存数组中等待被渲染，这不一定是即时响应渲染的，要看你设置的渲染算法，你可以通过调用 `manager.setMode()` 来更改，会触发 `push` 钩子。 :::note[注意] -发送弹幕的时候，**数据格式必须是 `PushData`，其中 `id` 是可选的。也就是说必须是一个带有 `value` 的对象 `{ value: unknown }`**，至于 `value` 的类型由你自己来控制，只要你能在渲染的时候能正确拿到就可以了，具体见下面的示例。 +1. 发送弹幕的时候，**数据格式必须是 `T`**，至于 `T` 的类型由你自己来控制，只要你能在渲染的时候能正确拿到就可以了，具体见下面的示例。 +2. 当第二个参数没有传递时，或者其中某些参数没有传递时，则会从 `manager.options` 里面取默认的值。 ::: -```ts {7, 11, 15-16} -interface PushData { - id?: any; - value: T; +```ts {12, 16, 21} +export interface PushOptions { + id?: number | string; + rate?: number; + duration?: number; + plugin?: DanmakuPlugin; + direction?: 'right' | 'left'; } +const manager = create<{ content: string }>(); + // 发送一条弹幕 -manager.push({ value: '弹幕内容' }); +manager.push({ '弹幕内容' }); // 发送一条弹幕并添加插件处理，插件的作用域仅限当前 push 的这一条弹幕。 manager.push( - { value: '弹幕内容' }, + { content: '弹幕内容' }, { - createNode(danmaku) { - const div = document.createElement('div'); - div.innerHTML = danmaku.data.value; // 弹幕内容 - danmaku.node.appendChild(div); - }, + plugin: { + createNode(danmaku) { + const div = document.createElement('div'); + div.innerHTML = danmaku.data.content; // 弹幕内容 + danmaku.node.appendChild(div); + }, + } }, ); ``` @@ -292,7 +300,7 @@ manager.push( ### `unshift()` -**类型：`(data: PushData, plugin?: DanmakuPlugin) => boolean`** +**类型：`(data: T, options?: PushOptions) => boolean`** `push` 方法是添加到内存数组后面，此方法会将弹幕**添加到内存数组前面**，当用户在输入了一条弹幕点击发送的时候，你应该使用此方法，以便于让弹幕在下次轮询的时候**立即渲染**，用法和 `push` 方法一样，会触发 `push` 钩子。 @@ -300,38 +308,35 @@ manager.push( ### `pushFlexibleDanmaku()` -**类型：`(data: PushData, options?: PushFlexOptions) => boolean`** +**类型：`(data: T, options?: PushFlexOptions) => boolean`** 发送一条高级弹幕，**高级弹幕会在下次轮询的时候渲染**，会触发 `push` 钩子。 :::note[高级弹幕说明] -1. 高级弹幕的插件和普通弹幕的插件行为一样，你可以通过 `danmaku.type` 属性来区分。 -2. 高级弹幕如果不传 `duration` 则**会从 `manager.options.times` 范围里面随机生成一个**。 -3. 高级弹幕如果不传 `direction` 则**会取 `manager.options.direaction`**。 -4. 高级弹幕**必须传递 `position` 来指定位置**，如果需要指定在某个轨道渲染，可以借助 [**`getTrackLocation()`**](./#gettracklocation) 来做到。 +1. 高级弹幕的 `options` 和普通弹幕的 `options` 行为一样，如果不传会默认从 `manager.options` 里面取默认值。 +2. 高级弹幕**必须传递 `position` 来指定位置**，如果需要指定在某个轨道渲染，可以借助 [**`getTrackLocation()`**](./#gettracklocation) 来做到。 ::: ```ts -// 普通弹幕没有 'none' -type Direction = 'left' | 'right' | 'none'; - interface Position { x: number; y: number; } interface PushFlexOptions { - plugin?: DanmakuPlugin; + id?: number | string; + rate?: number; duration?: number; - direction?: Direction; + plugin?: DanmakuPlugin; + direction?: 'left' | 'right' | 'none'; // 普通弹幕没有 'none' position: Position | ((d: Danmaku, box: Box) => Position); } // 发送一条弹幕，在容器居中的位置，静止 5s manager.pushFlexibleDanmaku( - { value: { content: '弹幕内容' } }, + { content: '弹幕内容' }, { duration: 5000, direction: 'none', @@ -373,13 +378,13 @@ const { start, middle, end } = manager.getTrackLocation(-1); ::: -```ts {7, 10} +```ts {12, 15} // 打开控制台后，容器会由变化，需要先调用 `format` 方法重新继续 manager.format(); // 发送一个高级弹幕 manager.pushFlexibleDanmaku( - { value: { content: '测试' } }, + { content: '测试' }, { duration: 5000, direction: 'none', @@ -554,6 +559,21 @@ manager.nextFrame(() => {
+### `render()` + +**类型：`() => Manager`** + +跳过等到下次轮询，立即进行渲染，如果你发送了一个弹幕，不想等待下次轮询，想立即渲染，则可以使用此方法。 + +```ts +manager.unshift('弹幕内容'); + +// 立即渲染 +manager.render(); +``` + +
+ ### `remove()` **类型：`(pluginName: string) => Manager`** diff --git a/docs/src/content/docs/zh/reference/manager-config.mdx b/docs/src/content/docs/zh/reference/manager-config.mdx index f0a52228..1801d8a9 100644 --- a/docs/src/content/docs/zh/reference/manager-config.mdx +++ b/docs/src/content/docs/zh/reference/manager-config.mdx @@ -5,7 +5,13 @@ sidebar: order: 1 --- -在初始化 `manager` 的时候，允许传递 options，替换默认的配置。以下所有的配置都是**可选的**。 +在初始化 `manager` 的时候，允许传递全局 options，替换默认的配置。以下所有的配置都是**可选的**。 + +:::note[注意] + +这里的是全局属性，在发送弹幕的时候如果一些可选属性没有传递，**会默认取这里的全局属性**。 + +::: **示例：** @@ -96,7 +102,7 @@ manager.setGap('10%'); // 最小间距为容器宽度的 10% **类型：`string`**
**默认值：`'right'`** -弹幕的运动方向，默认从右往左运动，**普通弹幕没有 `none` 值，高级弹幕可以设置 `none` 值**。 +弹幕的运动方向，默认从右往左运动，**普通弹幕没有 `none` 值，高级弹幕可以设置 `none` 值**。如果发送弹幕的时候有自己的 `direction`，则会取弹幕自身的配置。
@@ -121,7 +127,7 @@ manager.setTrackHeight('33%'); // 高度为容器高度的 33% **类型：`[number, number]`**
**默认值：`[4000, 6000]`** -普通弹幕的运动时间，这是一个范围值，**普通弹幕会在这个范围内随机选择一个时间作为运动时间**，如果你希望所有的弹幕运动时间都一致，你可以将两个数设置为同样的数。当发送高级弹幕的时候，如果没有指定运动时长，也会从这个范围随机取一个值。 +普通弹幕的运动时间，这是一个范围值，**普通弹幕会在这个范围内随机选择一个时间作为运动时间**，如果你希望所有的弹幕运动时间都一致，你可以将两个数设置为同样的数。如果发送弹幕的时候有自己的 `duration`，则会取弹幕自身的配置。