9-25 · ProTable（下）：运行时引擎

packages/pro-components/pro-table/src/pro-table.vue 中的 requestReload 触发点
1452  onMounted           → "initial"        首屏装载（immediate !== false）
1406  watch requestParams → "params-change"  外部参数变化（deep 监听）
 956  handlePageChange    → "page-change"    翻页
 962  handleSearch        → "search"         搜索提交
 967  handleSearchReset   → "reset"          搜索区重置
 973  handleSavedViewSelect → "view-change"  切换保存视图
 801  handleFilterApply   → "filter"         筛选抽屉应用
 806  handleFilterReset   → "reset"          筛选抽屉重置
 910  reload()            → "reload"         实例方法
 914  refresh()           → "refresh"        实例方法（工具栏刷新按钮同源）
 933  reset()             → "reset"          实例方法（全状态复位）

// packages/pro-components/pro-table/src/pro-table.vue:862-934
function buildRequestParams() {
  return {
    ...(props.request?.requestParams ?? {}),
    ...(searchModel.value ?? {}),
    ...(filterModel.value ?? {}),
    ...(activeViewKey.value ? { activeViewKey: activeViewKey.value } : {})
  };
}

async function requestReload(action = "reload") {
  if (!props.request) {
    return;
  }

  const requestId = ++latestRequestId;
  requestLoading.value = true;
  requestError.value = null;

  try {
    const params = buildRequestParams();
    const result = await props.request.request(
      params,
      createProRequestContext(action, params, currentPageState.value, pageSizeState.value)
    );
    const normalized = normalizeProRequestResult(result);

    if (requestId !== latestRequestId) {
      return;
    }

    internalData.value = normalized.data as ProTableRow[];
    requestTotal.value = normalized.total;
    emit("request-success", internalData.value.slice());
  } catch (error) {
    if (requestId !== latestRequestId) {
      return;
    }

    requestError.value = error;
    emit("request-error", error);
  } finally {
    if (requestId === latestRequestId) {
      requestLoading.value = false;
    }
  }
}

async function reload() {
  await requestReload("reload");
}

async function refresh() {
  await requestReload("refresh");
}

async function reset() {
  currentPageState.value = props.defaultCurrentPage;
  pageSizeState.value = props.defaultPageSize;
  cancelEdit();
  closeContextmenu();
  selectedRows.value = [];
  if (searchModel.value) {
    Object.keys(searchModel.value).forEach((key) => {
      searchModel.value![key] = undefined;
    });
  }
  if (filterModel.value) {
    Object.keys(filterModel.value).forEach((key) => {
      filterModel.value![key] = undefined;
    });
  }
  await requestReload("reset");
}

// packages/pro-components/request-utils.ts（全文 33 行）
import type { ProRequestContext, ProRequestResult } from "./core";

export function normalizeProRequestResult<T>(result: ProRequestResult<T>) {
  if (Array.isArray(result)) {
    return {
      data: result,
      total: result.length,
      extra: {}
    };
  }

  return {
    data: result.data,
    total: result.total ?? result.data.length,
    extra: result.extra ?? {}
  };
}

export function createProRequestContext(
  action: string,
  params: Record<string, unknown>,
  page: number,
  pageSize: number,
  signal?: AbortSignal
): ProRequestContext {
  return {
    action,
    params,
    page,
    pageSize,
    signal
  };
}

// packages/pro-components/pro-table/src/pro-table.vue:1353-1363
watch(
  () => props.data,
  (value) => {
    if (!props.request) {
      internalData.value = value.slice();
    }
  },
  {
    deep: true
  }
);

// packages/pro-components/pro-table/__tests__/pro-table.spec.ts:580-659
  it("连续触发 request 时只保留最后一次响应结果", async () => {
    const resolvers: Array<(value: { data: Row[]; total: number }) => void> = [];
    const request = vi.fn(
      () =>
        new Promise<{ data: Row[]; total: number }>((resolve) => {
          resolvers.push(resolve);
        })
    );

    const wrapper = mountHost(
      `
        <xy-pro-table
          :data="[]"
          :columns="columns"
          :request="{ request, requestParams, immediate: true }"
          :table-props="{ rowKey: 'id' }"
          @request-success="requestEvents.push($event)"
        />
      `,
      () => ({
        request,
        requestParams: {
          keyword: "first"
        },
        requestEvents: [] as Array<Row[]>,
        columns: [
          {
            prop: "name",
            label: "名称"
          },
          {
            prop: "status",
            label: "状态"
          }
        ] as ProTableColumn<Row>[]
      })
    );

    await nextTick();
    expect(request).toHaveBeenCalledTimes(1);

    await wrapper.setData({
      requestParams: {
        keyword: "second"
      }
    });
    await nextTick();
    expect(request).toHaveBeenCalledTimes(2);

    resolvers[1]?.({
      data: [
        {
          id: 2,
          name: "最新结果",
          status: "启用"
        }
      ],
      total: 1
    });
    await flushPromises();

    expect(wrapper.text()).toContain("最新结果");
    expect((wrapper.vm as unknown as { requestEvents: Array<Row[]> }).requestEvents).toHaveLength(1);

    resolvers[0]?.({
      data: [
        {
          id: 1,
          name: "过期结果",
          status: "停用"
        }
      ],
      total: 1
    });
    await flushPromises();

    expect(wrapper.text()).toContain("最新结果");
    expect(wrapper.text()).not.toContain("过期结果");
    expect((wrapper.vm as unknown as { requestEvents: Array<Row[]> }).requestEvents).toHaveLength(1);
  });

// packages/pro-components/pro-table/src/pro-table.vue:1402-1412
watch(
  () => props.request?.requestParams,
  () => {
    if (props.request?.autoReloadOnParamsChange !== false) {
      void requestReload("params-change");
    }
  },
  {
    deep: true
  }
);

// packages/pro-components/pro-table/src/pro-table.vue:288-293
const exportableColumns = computed(() =>
  visibleLeafColumns.value.filter((column) => column.exportable !== false && column.type === "default")
);
const printableColumns = computed(() =>
  visibleLeafColumns.value.filter((column) => column.printable !== false && column.type === "default")
);

// packages/pro-components/pro-table/src/pro-table.vue:1087-1132
async function handleExport(type?: "csv" | "excel") {
  const exportType = type ?? props.exportOptions?.defaultType ?? "csv";
  const filename = props.exportOptions?.filename ?? "pro-table-export";
  const rows = internalData.value.slice();
  const columns = exportableColumns.value.map((column) => cloneColumn(column));
  const payload = {
    type: exportType,
    filename,
    columns,
    rows
  };

  if ((await props.exportOptions?.beforeExport?.(payload)) === false) {
    return;
  }

  const mappedRows = rows.map((row) => props.exportOptions?.mapRow?.(row) ?? row);
  const headers = columns.map((column) => column.label ?? column.prop ?? column.key ?? "");
  const records = mappedRows.map((row) =>
    columns.map((column) => {
      const key = column.prop ?? column.key;
      return stringifyCellValue(key ? readPathValue(row, key) : undefined);
    })
  );

  if (exportType === "excel") {
    const XLSX = await import("xlsx");
    const worksheet = XLSX.utils.aoa_to_sheet([headers, ...records]);
    const workbook = XLSX.utils.book_new();
    XLSX.utils.book_append_sheet(workbook, worksheet, "Sheet1");
    XLSX.writeFile(workbook, `${filename}.xlsx`);
  } else {
    const csv = [headers.map((value) => escapeCsvValue(value)).join(","), ...records.map((row) => row.map((value) => escapeCsvValue(value)).join(","))].join("\n");
    const blob = new Blob([csv], {
      type: "text/csv;charset=utf-8;"
    });
    const url = URL.createObjectURL(blob);
    const anchor = document.createElement("a");
    anchor.href = url;
    anchor.download = `${filename}.csv`;
    anchor.click();
    URL.revokeObjectURL(url);
  }

  emit("export", payload);
}

// packages/pro-components/pro-table/src/pro-table.vue:165-185
function stringifyCellValue(value: unknown) {
  if (value == null) {
    return "";
  }

  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
    return String(value);
  }

  return JSON.stringify(value);
}

function escapeCsvValue(value: unknown) {
  const text = stringifyCellValue(value);

  if (!/[",\n]/.test(text)) {
    return text;
  }

  return `"${text.replace(/"/g, "\"\"")}"`;
}

// packages/pro-components/pro-table/src/pro-table.vue:1134-1189
async function handlePrint() {
  const rows = internalData.value.slice();

  if ((await props.printOptions?.beforePrint?.(rows)) === false) {
    return;
  }

  const printWindow = window.open("", "_blank", "noopener,noreferrer");

  if (!printWindow) {
    return;
  }

  const title = props.printOptions?.title ?? props.title ?? "表格打印";
  const subtitle = props.printOptions?.subtitle ?? props.description ?? "";
  const headers = printableColumns.value.map((column) => column.label ?? column.prop ?? column.key ?? "");
  const body = rows
    .map(
      (row) =>
        `<tr>${printableColumns.value
          .map((column) => `<td>${escapeCsvValue(readPathValue(row, column.prop ?? column.key)).replace(/"/g, "")}</td>`)
          .join("")}</tr>`
    )
    .join("");

  printWindow.document.write(`
    <html>
      <head>
        <title>${title}</title>
        <style>
          body { font-family: sans-serif; padding: 24px; color: #111827; }
          h1 { font-size: 20px; margin: 0 0 8px; }
          p { margin: 0 0 16px; color: #6b7280; }
          table { width: 100%; border-collapse: collapse; }
          th, td { border: 1px solid #d1d5db; padding: 10px 12px; text-align: left; }
          th { background: #f3f4f6; }
        </style>
      </head>
      <body>
        <h1>${title}</h1>
        ${subtitle ? `<p>${subtitle}</p>` : ""}
        <table>
          <thead>
            <tr>${headers.map((item) => `<th>${item}</th>`).join("")}</tr>
          </thead>
          <tbody>${body}</tbody>
        </table>
      </body>
    </html>
  `);
  printWindow.document.close();
  printWindow.focus();
  printWindow.print();
  printWindow.close();
  emit("print", rows);
}

// packages/pro-components/pro-table/__tests__/pro-table.spec.ts:726-756
  it("支持右键菜单、虚拟列表和导出打印入口", async () => {
    const openMock = vi.fn(() => ({
      document: {
        write: vi.fn(),
        close: vi.fn()
      },
      focus: vi.fn(),
      print: vi.fn(),
      close: vi.fn()
    }));
    const createObjectURLMock = vi.fn(() => "blob:demo");
    const revokeObjectURLMock = vi.fn();
    const appendAnchorClick = vi.fn();
    const originalOpen = window.open;
    const originalCreateObjectURL = URL.createObjectURL;
    const originalRevokeObjectURL = URL.revokeObjectURL;

    window.open = openMock as unknown as typeof window.open;
    URL.createObjectURL = createObjectURLMock;
    URL.revokeObjectURL = revokeObjectURLMock;

    const createElementSpy = vi.spyOn(document, "createElement");
    createElementSpy.mockImplementation(((tagName: string) => {
      const element = document.createElementNS("http://www.w3.org/1999/xhtml", tagName) as HTMLElement;

      if (tagName === "a") {
        (element as HTMLAnchorElement).click = appendAnchorClick;
      }

      return element;
    }) as typeof document.createElement);

// packages/pro-components/pro-table/src/pro-table.vue:1220-1269
function destroySortables() {
  rowSortable?.destroy();
  rowSortable = null;
  columnSortable?.destroy();
  columnSortable = null;
}

async function syncSortables() {
  destroySortables();
  await nextTick();

  if (props.draggableRow) {
    const body = rootRef.value?.querySelector(".xy-table__body-wrapper tbody");

    if (body) {
      rowSortable = Sortable.create(body as HTMLElement, {
        animation: 150,
        onEnd: ({ oldIndex, newIndex }) => {
          if (oldIndex == null || newIndex == null || oldIndex === newIndex) {
            return;
          }

          internalData.value = move(internalData.value, oldIndex, newIndex);
          emit("drag-row-change", internalData.value.slice());
        }
      });
    }
  }

  if (canColumnDrag.value) {
    const headerRow = rootRef.value?.querySelector(".xy-table__header-main thead tr:last-child");

    if (headerRow) {
      columnSortable = Sortable.create(headerRow as HTMLElement, {
        animation: 150,
        onEnd: ({ oldIndex, newIndex }) => {
          if (oldIndex == null || newIndex == null || oldIndex === newIndex) {
            return;
          }

          internalColumns.value = reorderVisibleTopLevelColumns(oldIndex, newIndex);
          emit("drag-column-change", internalColumns.value.slice());
          nextTick(() => {
            tableRef.value?.doLayout();
          });
        }
      });
    }
  }
}

// packages/pro-components/pro-table/src/pro-table.vue:365-370
const canColumnDrag = computed(
  () =>
    props.draggableColumn &&
    visibleColumns.value.length > 1 &&
    visibleColumns.value.every((column) => (column.children?.length ?? 0) === 0)
);

// packages/pro-components/pro-table/src/pro-table.vue:1191-1218
function reorderVisibleTopLevelColumns(fromIndex: number, toIndex: number) {
  const source = internalColumns.value.slice();
  const visibleIndexes = source
    .map((column, index) => ({ column, index }))
    .filter(({ column }) => !column.hidden);

  if (
    fromIndex < 0 ||
    toIndex < 0 ||
    fromIndex >= visibleIndexes.length ||
    toIndex >= visibleIndexes.length
  ) {
    return source;
  }

  const reorderedVisibleColumns = move(
    visibleIndexes.map(({ column }) => column),
    fromIndex,
    toIndex
  );
  const nextColumns = source.slice();

  visibleIndexes.forEach(({ index }, orderIndex) => {
    nextColumns[index] = reorderedVisibleColumns[orderIndex];
  });

  return nextColumns;
}

// packages/pro-components/pro-table/src/pro-table.vue:1392-1400
watch(
  () => [props.draggableRow, props.draggableColumn, internalData.value.length, visibleColumns.value.length],
  () => {
    void syncSortables();
  },
  {
    flush: "post"
  }
);

// packages/pro-components/pro-table/__tests__/pro-table-drag.spec.ts（全文 75 行）
import { mount } from "@vue/test-utils";
import { defineComponent, h, nextTick } from "vue";
import { describe, expect, it, vi } from "vitest";
import { XyProTable } from "@xiaoye/pro-components";

const sortableMock = vi.hoisted(() => ({
  instances: [] as Array<{
    options: {
      onEnd?: (payload: {
        oldIndex?: number;
        newIndex?: number;
      }) => void;
    };
  }>
}));

vi.mock("sortablejs", () => ({
  default: {
    create: vi.fn((_element, options) => {
      const instance = {
        options,
        destroy: vi.fn()
      };
      sortableMock.instances.push(instance);
      return instance;
    })
  }
}));

describe("XyProTable drag", () => {
  it("启用 draggableRow / draggableColumn 时会挂载 sortable 并派发事件", async () => {
    const wrapper = mount(XyProTable, {
      attachTo: document.body,
      props: {
        data: [
          { id: 1, name: "控制台" },
          { id: 2, name: "账单中心" }
        ],
        columns: [
          { prop: "name", label: "名称" },
          { prop: "id", label: "编号" }
        ],
        draggableRow: true,
        draggableColumn: true,
        tableProps: {
          rowKey: "id"
        }
      }
    });

    await nextTick();
    await nextTick();

    expect(sortableMock.instances).toHaveLength(2);

    sortableMock.instances[0]?.options.onEnd?.({
      oldIndex: 0,
      newIndex: 1
    });

    sortableMock.instances[1]?.options.onEnd?.({
      oldIndex: 0,
      newIndex: 1
    });

    expect(wrapper.emitted("drag-row-change")?.[0]?.[0]).toMatchObject([
      { id: 2, name: "账单中心" },
      { id: 1, name: "控制台" }
    ]);
    expect(wrapper.emitted("drag-column-change")?.[0]?.[0]).toMatchObject([
      { prop: "id", label: "编号" },
      { prop: "name", label: "名称" }
    ]);
  });
});

// packages/pro-components/pro-table/src/pro-table.vue:761-785
async function toggleFullscreen(force?: boolean) {
  const host = rootRef.value;

  if (!host || typeof document === "undefined") {
    fullscreen.value = force ?? !fullscreen.value;
    return;
  }

  const shouldOpen = force ?? !fullscreen.value;

  try {
    if (shouldOpen) {
      if (document.fullscreenElement !== host) {
        await host.requestFullscreen?.();
      }
    } else if (document.fullscreenElement) {
      await document.exitFullscreen?.();
    }
  } catch {
    fullscreen.value = shouldOpen;
  }

  fullscreen.value = shouldOpen;
  emit("workbench-action", shouldOpen ? "fullscreen:open" : "fullscreen:close");
}

/* packages/theme/src/pro/pro-table.css:8-17 */
.xy-pro-table.is-fullscreen {
  position: fixed;
  inset: 0;
  z-index: 1200;
  padding: 24px;
  overflow: auto;
  background:
    radial-gradient(circle at top right, color-mix(in srgb, var(--xy-brand) 12%, var(--xy-mix-light)), transparent 220px),
    var(--xy-bg-page);
}

// packages/pro-components/pro-table/src/pro-table.vue:1438-1444
function syncFullscreenState() {
  if (typeof document === "undefined" || !rootRef.value) {
    return;
  }

  fullscreen.value = document.fullscreenElement === rootRef.value;
}

// packages/pro-components/pro-table/src/pro-table.vue:229-238
const resolvedWorkbench = computed(() => ({
  refresh: Boolean(props.workbench.refresh || props.request),
  density: Boolean(props.workbench.density),
  columnSetting: Boolean(props.workbench.columnSetting),
  fullscreen: Boolean(props.workbench.fullscreen),
  treeToggle: Boolean(props.workbench.treeToggle),
  filter: Boolean(props.workbench.filter || props.views?.filterFields?.length),
  export: Boolean(props.workbench.export || props.exportOptions),
  print: Boolean(props.workbench.print || props.printOptions)
}));

<!-- packages/pro-components/pro-table/src/pro-table.vue:1544-1567 -->
        <xy-button v-if="resolvedWorkbench.refresh" text @click="handleRefresh">刷新</xy-button>
        <xy-button v-if="resolvedWorkbench.filter" text @click="openFilterDrawer">筛选</xy-button>
        <xy-button
          v-if="resolvedWorkbench.treeToggle && tableRef?.bodyRows?.length"
          text
          @click="tableRef?.setAllTreeRowsExpanded(true)"
        >
          展开树
        </xy-button>
        <xy-button
          v-if="resolvedWorkbench.treeToggle && tableRef?.bodyRows?.length"
          text
          @click="tableRef?.setAllTreeRowsExpanded(false)"
        >
          收起树
        </xy-button>
        <xy-button v-if="resolvedWorkbench.columnSetting" text @click="settingsOpen = !settingsOpen">
          列设置
        </xy-button>
        <xy-button v-if="resolvedWorkbench.export" text @click="handleExport()">导出</xy-button>
        <xy-button v-if="resolvedWorkbench.print" text @click="handlePrint">打印</xy-button>
        <xy-button v-if="resolvedWorkbench.fullscreen" text @click="toggleFullscreen()">
          {{ fullscreen ? "退出全屏" : "全屏" }}
        </xy-button>

<!-- packages/pro-components/pro-table/src/pro-table.vue:1697-1702 -->
        <template v-if="slots.loading" #loading>
          <slot name="loading" :loading="props.loading || requestLoading" />
        </template>
        <template v-if="slots.empty" #empty>
          <slot name="empty" :empty="!props.loading && !requestLoading && internalData.length === 0" />
        </template>

【本篇直接拆解】
packages/pro-components/pro-table/src/pro-table.vue
                                                            17（sortablejs import）
                                                            79-80 / 116-117（拖拽 props 与事件声明）
                                                            139-149（move）
                                                            151-163 / 165-175 / 177-185（取值与 CSV 转义）
                                                            200 / 225-227（internalData 初值；三运行时句柄）
                                                            229-238（resolvedWorkbench）
                                                            244-248（rootClasses 的 is-fullscreen）
                                                            288-293（导出/打印列圈定）
                                                            324-343 / 341（tableBindings / 默认 rowKey）
                                                            365-370（canColumnDrag）
                                                            761-785（toggleFullscreen）
                                                            801 / 806（筛选触发）
                                                            862-869 / 871-907 / 876 / 888 / 896 / 903（请求编排与三守卫）
                                                            909-934（reload/refresh/reset）
                                                            936-939 / 951-958 / 960-963 / 965-968 / 970-974（触发源）
                                                            1087-1132（handleExport）/ 1113（动态 import xlsx）
                                                            1134-1189（handlePrint）
                                                            1191-1218（reorderVisibleTopLevelColumns）
                                                            1220-1225 / 1227-1269（销毁与同步 Sortable）
                                                            1353-1363（data watch 的 request 分界）
                                                            1392-1400（Sortable 重建 watch）
                                                            1402-1412（params-change watch）
                                                            1438-1444（syncFullscreenState）
                                                            1446-1454 / 1456-1460（挂载与卸载）
                                                            1489-1493（expose 的引擎方法）
                                                            1544-1567（工作台按钮区）
                                                            1573-1609（内联列设置面板）
                                                            1671-1678（错误横幅）
                                                            1697-1702（loading/empty 代理）
packages/pro-components/pro-table/src/pro-table.ts          154-155 / 158-168 / 170-175 / 218-224 / 221 / 226-230 / 232-248 / 237 / 331-381
packages/pro-components/request-utils.ts                    1-33（全文）/ 3-17 / 19-33 / 24
packages/pro-components/core.ts                             5-25 / 11 / 13-19 / 18 / 21-25
packages/components/shared/display-renderer.ts              1-353（9-24 显示管线，导出不参与）
packages/pro-components/list-page/src/list-page.vue         92-101（三插槽转发，9-21 考据）
packages/pro-components/package.json                        56（sortablejs dependencies）
package.json                                                83（xlsx 仅根 devDependencies）
packages/theme/src/pro/pro-table.css                        1-6 / 8-17（is-fullscreen）/ 147
packages/xiaoye-primitives/src/composables/use-namespace.ts 8（is() 前缀规则）
packages/pro-components/pro-table/index.ts                  1-14（15-17 的 XyProTable 导出与 default export 从略）
packages/pro-components/exports.ts                          14
packages/pro-components/component-manifest.json             107-112
【测试】
packages/pro-components/pro-table/__tests__/pro-table.spec.ts
                                                            30-134（工具栏/分页联动）
                                                            136-169（loading 优先于 empty）
                                                            580-659（竞态用例，全文引用）
                                                            726-821（右键/虚拟/导出打印入口）
packages/pro-components/pro-table/__tests__/pro-table-drag.spec.ts  1-75（全文引用）
【文档示例】
apps/docs/examples/pro/pro-table/workbench-request.vue      39-72（request 协议）/ 82-89（workbench 配置）/ 121-122（导出打印选项）
apps/docs/examples/pro/pro-table/virtual-list.vue           1-52（虚拟列表与拖拽未同框）
【专栏内引】
column/02-分卷大纲.md                                       175-181 / 179（本篇条目）
column/9-02-core.ts-协议层.md                               （signal 协议与竞态守卫的宪法表述）
column/9-04-SearchForm-查询语义.md                          （两层 reset 对照）
column/9-10-RequestForm-请求表单.md                         （request-utils 双消费者与无令牌欠账）
column/9-21-ListPage-薄预设封装.md                          （插槽转发考据）
column/9-22-CrudPage-整页CRUD.md                            （顶层组装心法与预告链）