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

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)