Svelte 5：如何为Props编写JSDoc（含表格遍历场景）

以下是修改后的代码，已为tables Props和遍历的table对象补充完整JSDoc注释，同时统一类型定义以确保类型一致性：

1. 状态仓库代码（tables.svelte） #

先统一类型命名（将table改为大写开头的Table，符合JS类型命名规范）：

import { user } from "./user.svelte"

function createTables(){
    /**
     * 服务员对象类型定义
     * @typedef {Object} Waiter
     * @property {number} id - 服务员ID
     */

    /**
     * 餐桌对象类型定义
     * @typedef {Object} Table
     * @property {number} id - 餐桌唯一ID
     * @property {string} name - 餐桌名称
     * @property {number|null} seats - 餐桌座位数，为空表示未设置
     * @property {null|Object} order - 餐桌关联的订单，为null表示无订单
     * @property {Waiter} waiter - 负责该餐桌的服务员
     */

    /**
     * 所有餐桌的状态数组
     * @type {Array<Table>}
     */
    let tables = $state([])

    let userTables = $derived(() => {
        return tables.filter(table => {
            return +user.currentUser?.id === +table.waiter?.id
        })
    })

    let userTablesFree = $derived(() => {
        return tables.filter(table => {
            return +user.currentUser?.id === +table.waiter?.id &&
            table.order === null
        })
    })

    let userTablesUsed = $derived(() => {
        return tables.filter(table => {
            return +user.currentUser?.id === +table.waiter?.id &&
            table.order !== null
        })
    })

    let otherTablesFree = $derived(() => {
        return tables.filter(table => {
            return +user.currentUser?.id !== +table.waiter?.id &&
            table.order === null
        })
    })

    let otherTablesUsed = $derived(() => {
        return tables.filter(table => {
            return +user.currentUser?.id !== +table.waiter?.id &&
            table.order !== null
        })
    })

    return {
        get tables(){
            return tables
        },
        set tables(newValue){
            tables = newValue
        },
        userTables,
        userTablesFree,
        userTablesUsed,
        otherTablesFree,
        otherTablesUsed
    }
}

export const tables = createTables()

2. 组件代码（Table.svelte） #

为tables Props指定类型，并在{each}块前添加注释说明遍历对象：

<script>
    import { dialog } from "../store/dialog.svelte";
    /**
     * 需要展示的餐桌列表
     * @type {import('../store/tables.svelte').Table[]}
     */
    let { tables } = $props();

    /**
     * 打开餐桌订单弹窗
     * @function
     * @param {import('../store/tables.svelte').Table} table - 目标餐桌对象
     * @returns {void}
    */
    function getOrder(table){
        dialog.open = true;
        dialog.title = `${table.name} Order`;
    }
</script>

<!-- 遍历餐桌列表，渲染每个餐桌卡片 -->
{#each tables as table (table.id)}
    <div class="card bg-base-100 shadow-xl">
        <div class="card-body py-2 px-1">
            <h2 class="card-title">{table.name}
                <sup class="text-sm">({table.seats}<i class="fa-solid fa-chair"></i>)</sup>

                {#if table.order }
                <sup>
                    <button class="bg-green-500 text-white p-2 rounded-full
                    transition duration-300 ease-in-out transform hover:scale-105 animate-pulse"
                    ></button>
                </sup>
                {/if}
            </h2>

            <div class="card-actions justify-end">
                <button class="btn btn-info btn-xs"
                onclick={() => getOrder(table)}>Show Order</button>
            </div>
        </div>
    </div>
{/each}

3. Props传递代码（调用Table组件的页面） #

无需修改，保持原有逻辑即可：

<script>
    import { tables } from "../store/tables.svelte";
    import Table from "../snippets/Table.svelte";
</script>

<nav id="mainNav">
    <h3>Tables</h3>
    <div class="divider"></div>

    <div class="border grid grid-cols-4 gap-4 justify-between py-5 px-2 bg-gray-100">
        <Table tables={tables.tables}></Table>
    </div>
</nav>

关键修改说明： #

• 状态仓库中统一类型命名为Table，规范类型定义
• 组件中通过import('../store/tables.svelte').Table跨文件引用类型，确保类型一致性
• 为tables Props明确标注为Table[]类型，IDE可提供完整的类型提示
• 在{each}块前添加注释说明遍历逻辑，同时添加(table.id)作为遍历键值，提升Svelte渲染性能
• 更新getOrder函数的参数类型，直接引用仓库定义的Table类型

内容的提问来源于stack exchange，提问作者Sasha