docs: @user/client-modules & fix: 修复 client-modules 中的一些错误

packages-user/client-modules/src/action/move.ts

@@ -1,6 +1,6 @@
 import { KeyCode } from '@motajs/client-base';
 import { Hotkey, HotkeyData } from '@motajs/system-action';
-import type { HeroMover, IMoveController } from '@user/data-state';
+import { HeroMover, IMoveController } from '@user/data-state';
 import { Ticker } from 'mutate-animate';
 import { mainScope } from '@motajs/legacy-ui';
 
@@ -114,7 +114,7 @@ export class HeroKeyMover {
 
         this.mover.oneStep(this.moveDir);
         const controller = this.mover.startMove(false, false, false, true);
-        if (!controller) return;
+        if (!controller) return false;
 
         this.controller = controller;
         controller.onEnd.then(() => {

packages-user/client-modules/src/audio/decoder.ts

@@ -106,7 +106,7 @@ export abstract class AudioDecoder {
             } else {
                 const decoder = new Decoder();
                 await decoder.create();
-                const decodedData = await decoder.decode(data);
+                const decodedData = await decoder.decodeAll(data);
                 if (!decodedData) return null;
                 const buffer = player.ac.createBuffer(
                     decodedData.channelData.length,
@@ -150,7 +150,7 @@ export abstract class AudioDecoder {
     abstract flush(): Promise<IAudioDecodeData | undefined>;
 }
 
-export class VorbisDecoder implements AudioDecoder {
+export class VorbisDecoder extends AudioDecoder {
     decoder?: OggVorbisDecoderWebWorker;
 
     async create(): Promise<void> {
@@ -175,7 +175,7 @@ export class VorbisDecoder implements AudioDecoder {
     }
 }
 
-export class OpusDecoder implements AudioDecoder {
+export class OpusDecoder extends AudioDecoder {
     decoder?: OggOpusDecoderWebWorker;
 
     async create(): Promise<void> {

packages-user/client-modules/src/audio/player.ts

@@ -156,7 +156,7 @@ export class AudioPlayer extends EventEmitter<AudioPlayerEvent> {
      *             |-----------|
      * ```
      */
-    createDelay() {
+    createDelayEffect() {
         return new DelayEffect(this.ac);
     }
 
@@ -209,6 +209,10 @@ export class AudioPlayer extends EventEmitter<AudioPlayerEvent> {
      * @param id 要移除的播放路由的名称
      */
     removeRoute(id: string) {
+        const route = this.audioRoutes.get(id);
+        if (route) {
+            route.destroy();
+        }
         this.audioRoutes.delete(id);
     }
 
@@ -565,6 +569,10 @@ export class AudioRoute
         this.emit('updateEffect');
     }
 
+    destroy() {
+        this.effectRoute.forEach(v => v.disconnect());
+    }
+
     private setOutput() {
         const effect = this.effectRoute.at(-1);
         if (!effect) this.output = this.source.output;

packages-user/client-modules/src/audio/sound.ts

@@ -131,4 +131,5 @@ export class SoundPlayer<
         this.playing.clear();
     }
 }
+
 export const soundPlayer = new SoundPlayer<SoundIds>(audioPlayer);

packages-user/client-modules/src/audio/source.ts

@@ -112,7 +112,7 @@ export class AudioStreamSource extends AudioSource implements IStreamReader {
     /** 音频解析器 */
     private parser?: CodecParser;
     /** 每多长时间组成一个缓存 Float32Array */
-    private bufferChunkSize = 10;
+    private bufferChunkSize: number = 10;
     /** 缓存音频数据，每 bufferChunkSize 秒钟组成一个 Float32Array，用于流式解码 */
     private audioData: Float32Array[][] = [];
 

packages-user/client-modules/src/render/components/choices.tsx

@@ -468,7 +468,7 @@ export const Choices = defineComponent<
             <Background
                 loc={[0, 0, props.width, boxHeight.value]}
                 winskin={props.winskin}
-                color={props.color}
+                color={props.color ?? '#333'}
                 border={props.border}
             />
             {hasTitle.value && (
@@ -515,6 +515,7 @@ export const Choices = defineComponent<
                                 font={props.selFont}
                                 cursor="pointer"
                                 zIndex={5}
+                                fillStyle={props.selFill}
                                 onClick={() => emit('choose', v[0])}
                                 onSetText={(_, width, height) =>
                                     updateChoiceSize(i, width, height)

packages-user/client-modules/src/render/components/misc.tsx

@@ -14,6 +14,7 @@ import { transitioned } from '../use';
 import { hyper } from 'mutate-animate';
 import { logger } from '@motajs/common';
 import { GameUI, IUIMountable } from '@motajs/system-ui';
+import { clamp } from 'lodash-es';
 
 interface ProgressProps extends DefaultProps {
     /** 进度条的位置 */
@@ -57,9 +58,10 @@ export const Progress = defineComponent<ProgressProps>(props => {
         ctx.moveTo(lineWidth, height / 2);
         ctx.lineTo(width - lineWidth, height / 2);
         ctx.stroke();
-        if (!isNaN(props.progress)) {
+        const progress = clamp(props.progress, 0, 1);
+        if (!isNaN(progress)) {
             ctx.strokeStyle = props.success ?? 'green';
-            const p = lineWidth + (width - lineWidth * 2) * props.progress;
+            const p = lineWidth + (width - lineWidth * 2) * progress;
             ctx.beginPath();
             ctx.moveTo(lineWidth, height / 2);
             ctx.lineTo(p, height / 2);
@@ -137,7 +139,7 @@ export const Arrow = defineComponent<ArrowProps>(props => {
     );
 }, arrowProps);
 
-export interface ScrollTextProps extends TextboxProps, ScrollProps {
+export interface ScrollTextProps extends TextContentProps, ScrollProps {
     /** 自动滚动的速度，每秒多少像素 */
     speed: number;
     /** 文字的最大宽度 */
@@ -232,6 +234,7 @@ export const ScrollText = defineComponent<
             emit('scrollEnd');
             paused = true;
         }
+        lastFixedTime = now;
     });
 
     const pause = () => {

packages-user/client-modules/src/render/components/page.tsx

@@ -33,7 +33,7 @@ export type PageEmits = {
 export interface PageExpose {
     /**
      * 切换页码
-     * @param page 要切换至的页码数，1 表示第一页
+     * @param page 要切换至的页码数，0 表示第一页
      */
     changePage(page: number): void;
 

packages-user/client-modules/src/render/components/textbox.tsx

@@ -41,15 +41,27 @@ export interface TextContentProps
     fill?: boolean;
     /** 是否描边 */
     stroke?: boolean;
-    /** 是否自适应高度 */
+    /** 是否自适应高度，即组件内部计算 height 的值，而非指定，可与滚动条结合 */
     autoHeight?: boolean;
     /** 文字的最大宽度 */
     width: number;
 }
 
 export type TextContentEmits = {
+    /**
+     * 当打字机结束时触发
+     */
     typeEnd: () => void;
+
+    /**
+     * 当打字机开始打字时触发
+     */
     typeStart: () => void;
+
+    /**
+     * 当文字发生变动，组件内部重新计算文字高度时触发
+     * @param height 更新后的高度
+     */
     updateHeight: (height: number) => void;
 };
 
@@ -290,7 +302,7 @@ export const Textbox = defineComponent<
     TextboxEmits,
     keyof TextboxEmits,
     TextboxSlots
->((props, { slots, expose }) => {
+>((props, { slots, expose, emit }) => {
     const contentData = shallowReactive<TextContentProps>({ width: 200 });
     const data = shallowReactive<TextboxProps>({ width: 200 });
 
@@ -403,10 +415,12 @@ export const Textbox = defineComponent<
 
     const onTypeStart = () => {
         store.emitTypeStart();
+        emit('typeStart');
     };
 
     const onTypeEnd = () => {
         store.emitTypeEnd();
+        emit('typeEnd');
     };
 
     expose<TextboxExpose>({

packages-user/client-modules/src/render/components/textboxTyper.ts

@@ -669,7 +669,7 @@ export class TextContentParser {
             font: this.font,
             fontSize: this.status.fontSize,
             fillStyle: this.status.fillStyle,
-            wait,
+            wait: wait * this.config.interval,
             splitLines: [],
             wordBreak: []
         };

packages-user/client-modules/src/render/use.ts

@@ -70,7 +70,25 @@ export function onLoaded(hook: () => void) {
 export interface ITransitionedController<T> {
     readonly ref: Ref<T>;
     readonly value: T;
+
+    /**
+     * 执行动画，使当前值缓慢变化至目标值
+     * @param value 目标值
+     * @param time 动画时长
+     */
     set(value: T, time?: number): void;
+
+    /**
+     * 设置动画的速率曲线
+     * @param timing 速率曲线
+     */
+    mode(timing: TimingFn): void;
+
+    /**
+     * 设置动画的动画时长
+     * @param time 动画时长
+     */
+    setTime(time: number): void;
 }
 
 class RenderTransition implements ITransitionedController<number> {
@@ -90,8 +108,8 @@ class RenderTransition implements ITransitionedController<number> {
     constructor(
         value: number,
         public readonly transition: Transition,
-        public readonly time: number,
-        public readonly curve: TimingFn
+        public time: number,
+        public curve: TimingFn
     ) {
         this.ref = ref(value);
         transition.value[this.key] = value;
@@ -103,6 +121,14 @@ class RenderTransition implements ITransitionedController<number> {
     set(value: number, time: number = this.time): void {
         this.transition.time(time).mode(this.curve).transition(this.key, value);
     }
+
+    mode(timing: TimingFn): void {
+        this.curve = timing;
+    }
+
+    setTime(time: number): void {
+        this.time = time;
+    }
 }
 
 type ColorRGBA = [number, number, number, number];
@@ -127,8 +153,8 @@ class RenderColorTransition implements ITransitionedController<string> {
     constructor(
         value: string,
         public readonly transition: Transition,
-        public readonly time: number,
-        public readonly curve: TimingFn
+        public time: number,
+        public curve: TimingFn
     ) {
         this.ref = ref(value);
         const [r, g, b, a] = this.decodeColor(value);
@@ -145,6 +171,14 @@ class RenderColorTransition implements ITransitionedController<string> {
         this.transitionColor(this.decodeColor(value), time);
     }
 
+    mode(timing: TimingFn): void {
+        this.curve = timing;
+    }
+
+    setTime(time: number): void {
+        this.time = time;
+    }
+
     private transitionColor([r, g, b, a]: ColorRGBA, time: number) {
         this.transition
             .mode(this.curve)

packages-user/client-modules/src/utils/index.ts

@@ -1 +1,2 @@
 export * from './saves';
+export * from './use';

packages-user/client-modules/src/utils/use.ts

@@ -0,0 +1,14 @@
+import { getCurrentInstance, onUnmounted } from 'vue';
+import { WeatherController } from '../weather';
+
+let weatherId = 0;
+
+export function useWeather(): [WeatherController] {
+    const weather = new WeatherController(`@weather-${weatherId}`);
+
+    onUnmounted(() => {
+        weather.destroy();
+    });
+
+    return [weather];
+}

packages-user/client-modules/src/weather/weather.ts

@@ -117,6 +117,7 @@ export class WeatherController {
      */
     destroy() {
         WeatherController.map.delete(this.id);
+        this.clearWeather();
     }
 
     static get(id: string) {