@ticatec/topside-elements 1.0.6 → 1.2.0

package/dist/data_table/DataTable.svelte

@@ -15,6 +15,13 @@
     import { buildTableSummary } from "./lib/summary";
     import { isSameColumn } from "./lib/TableUtils";
     import i18nRes from "../i18nRes";
+    import type RowExpansion from "./lib/RowExpansion";
+    import {
+        type RowExpandContext,
+        type RowExpandRequest,
+        type RowEventHandlers,
+        isInteractiveTarget
+    } from "./lib/RowExpansion";
 
     interface Props {
         columns: Array<DataColumn>;
@@ -45,6 +52,13 @@
          * 分页场景下用它显示服务端算好的全量合计（数字串会按数字格式化）。
          */
         summaryValues?: Record<string, any> | null;
+        /**
+         * 行展开配置：展开区组件、是否显示指示列图标（默认显示）、整行单击 / 双击触发等。
+         * 不配置图标时可以用组件方法 expandRow / collapseRow / toggleRowExpand，
+         * 或在行内（自定义单元格、操作列、展开区）派发 ROW_EXPAND_EVENT 事件来控制。
+         * 同一时间只展开一行。
+         */
+        rowExpansion?: RowExpansion<T> | null;
     }
 
     let {
@@ -65,6 +79,7 @@
         overscan = 8,
         summaryLabel,
         summaryValues = null,
+        rowExpansion = null,
     }: Props = $props();
 
     const id: string = Math.round(new Date().getTime() + Math.random() * 1000).toString(36);
@@ -78,13 +93,24 @@
     let frozenWidth = $state(0);
     let styleEl: HTMLStyleElement | undefined;
 
-    let expandRow = $state<TableRow | null>(null);
+    let expandedRow = $state<TableRow | null>(null);
     let scrollTop = $state(0);
     let inlineComponent = $state<any>(null);
 
+    // 有效的行展开配置：rowExpansion 优先，兼容旧的 indicatorColumn.buildInlineComponent
+    let expansion = $derived.by<RowExpansion<T> | null>(() => {
+        if (rowExpansion) return rowExpansion;
+        const legacy = indicatorColumn?.buildInlineComponent;
+        return legacy ? { build: legacy } : null;
+    });
+    let expandable = $derived(expansion != null);
+    // 指示列图标：默认显示；需要有 indicatorColumn 才有地方放
+    let showExpandToggle = $derived(expandable && indicatorColumn != null && expansion?.showToggle !== false);
+    let expandTrigger = $derived(expansion?.trigger ?? null);
+
     // Measured by ContentPanel (its scrollable data area); drives the virtual window.
     let viewportHeight = $state(0);
-    let expandIndex = $derived(expandRow ? rows.indexOf(expandRow) : -1);
+    let expandIndex = $derived(expandedRow ? rows.indexOf(expandedRow) : -1);
     // One shared window for all three panels (frozen / content / actions), so the
     // slices they render always cover the same absolute row indices.
     let vwindow = $derived(virtual
@@ -163,7 +189,7 @@
 
     const sortRows = (compareFun: CompareFn, descending: boolean) => {
         if (!table) return;
-        expandRow = null;
+        closeExpanded();
         let oList = list.sort(compareFun);
         table.data = descending ? oList.reverse() : oList;
         rows = table.rows;
@@ -183,15 +209,125 @@
         }
     };
 
-    const onRowExpand = async (row: TableRow) => {
-        if (row == expandRow) {
-            expandRow = null;
-            inlineComponent = null;
+    const isExpandableRow = (row: TableRow): boolean =>
+        expandable && (expansion?.isExpandable?.(row.data) ?? true);
+
+    const closeExpanded = () => {
+        if (expandedRow == null) return;
+        expandedRow = null;
+        inlineComponent = null;
+        expansion?.onExpandChange?.(null);
+    };
+
+    // 异步 build 期间用户可能又点了别的行：只接受最后一次请求的结果
+    let expandSeq = 0;
+    const openRow = async (row: TableRow) => {
+        if (!isExpandableRow(row)) return;
+        const seq = ++expandSeq;
+        const comp = await expansion!.build(row.data);
+        if (seq !== expandSeq) return;
+        inlineComponent = comp;
+        expandedRow = row;
+        expansion?.onExpandChange?.(row.data);
+    };
+
+    /** 切换某行展开状态；expanded 指定目标状态，不传则切换 */
+    const setRowExpanded = async (row: TableRow, expanded?: boolean) => {
+        const isOpen = row === expandedRow;
+        const target = expanded ?? !isOpen;
+        if (target === isOpen) return;
+        if (target) {
+            await openRow(row);
         } else {
-            inlineComponent = await indicatorColumn?.buildInlineComponent?.(row.data);
-            expandRow = row;
+            expandSeq++;
+            closeExpanded();
         }
     };
+
+    const onRowExpand = (row: TableRow) => setRowExpanded(row);
+
+    // 对外方法（bind:this 后调用）用它定位行：按数据对象同一性匹配
+    const findRow = (data: T): TableRow | undefined => rows.find(r => r.data === data);
+
+    /** 展开指定行（按行数据对象匹配）；行不存在或不允许展开时不做任何事 */
+    export async function expandRow(data: T): Promise<void> {
+        const row = findRow(data);
+        if (row) await setRowExpanded(row, true);
+    }
+
+    /** 收起指定行；不传参数则收起当前展开的行 */
+    export function collapseRow(data?: T): void {
+        if (data === undefined) {
+            expandSeq++;
+            closeExpanded();
+            return;
+        }
+        const row = findRow(data);
+        if (row) void setRowExpanded(row, false);
+    }
+
+    /** 切换指定行的展开状态 */
+    export async function toggleRowExpand(data: T): Promise<void> {
+        const row = findRow(data);
+        if (row) await setRowExpanded(row);
+    }
+
+    /** 某行当前是否展开 */
+    export function isRowExpanded(data: T): boolean {
+        return expandedRow != null && expandedRow.data === data;
+    }
+
+    /** 当前展开行的数据，没有则为 null */
+    export function getExpandedRow(): T | null {
+        return expandedRow?.data ?? null;
+    }
+
+    // ---- 行级触发（整行单击 / 双击） ----
+
+    const handleRowClick = (row: TableRow, e: MouseEvent) => {
+        if (expandTrigger !== 'click' || isInteractiveTarget(e)) return;
+        void setRowExpanded(row);
+    };
+
+    const handleRowDblClick = (row: TableRow, e: MouseEvent) => {
+        if (expandTrigger !== 'dblclick' || isInteractiveTarget(e)) return;
+        e.preventDefault();
+        void setRowExpanded(row);
+    };
+
+    // ---- 行内自定义事件：render cell / ActionCell / 操作列 / 展开区内部都可以派发 ----
+
+    const handleExpandRequest = (row: TableRow, e: Event) => {
+        if (!expandable) return;
+        e.stopPropagation();
+        const detail = (e as CustomEvent<RowExpandRequest>).detail;
+        void setRowExpanded(row, detail?.expanded);
+    };
+
+    // 传给展开区组件的上下文
+    let expandContext = $derived.by<RowExpandContext<T> | null>(() => {
+        const row = expandedRow;
+        if (!row) return null;
+        const data = row.data as T;
+        const actions = actionsColumn?.getActions(data) ?? [];
+        return {
+            data,
+            collapse: () => { void setRowExpanded(row, false); },
+            actions,
+            invoke: async (label: string) => {
+                const action = actions.find(a => a.label === label);
+                if (!action || action.disabled) return false;
+                await action.handler(data);
+                return true;
+            }
+        };
+    });
+
+    const rowEvents: RowEventHandlers<TableRow> = {
+        onRowClick: handleRowClick,
+        onRowDblClick: handleRowDblClick,
+        onExpandRequest: handleExpandRequest,
+    };
 </script>
 
 <div id="tab-{id}" {style} class="topside-data-table" class:cell-border={colBorder} class:row-border={rowBorder}>
@@ -204,7 +340,10 @@
                 {orderColumn}
                 {onCellClick}
                 {indicatorColumn}
-                bind:expandRow
+                expandRow={expandedRow}
+                expandable={showExpandToggle}
+                isExpandable={isExpandableRow}
+                {rowEvents}
                 {rowHeight}
                 {headerHeight}
                 {fixedCols}
@@ -227,7 +366,9 @@
             {tabWidth}
             bind:rows
             bind:scrollTop
-            {expandRow}
+            expandRow={expandedRow}
+            {expandContext}
+            {rowEvents}
             {rowHeight}
             {headerHeight}
             {list}
@@ -245,6 +386,6 @@
     {/if}
 
     {#if actionsColumn}
-        <ActionPanel {expandRow} {rowHeight} {headerHeight} {actionsColumn} {rows} {inlineRowHeight} bind:scrollTop {vwindow} showSummary={tableSummary != null} />
+        <ActionPanel expandRow={expandedRow} {rowEvents} {rowHeight} {headerHeight} {actionsColumn} {rows} {inlineRowHeight} bind:scrollTop {vwindow} showSummary={tableSummary != null} />
     {/if}
 </div>

package/dist/data_table/DataTable.svelte.d.ts

@@ -2,6 +2,7 @@ import type DataColumn from "./lib/DataColumn";
 import type ActionsColumn from "./lib/ActionsColumn";
 import type IndicatorColumn from "./lib/IndicatorColumn";
 import type { GetRowFontStyle } from "../types";
+import type RowExpansion from "./lib/RowExpansion";
 declare function $$render<T = any>(): {
     props: {
         columns: Array<DataColumn>;
@@ -32,8 +33,21 @@ declare function $$render<T = any>(): {
          * 分页场景下用它显示服务端算好的全量合计（数字串会按数字格式化）。
          */
         summaryValues?: Record<string, any> | null;
+        /**
+         * 行展开配置：展开区组件、是否显示指示列图标（默认显示）、整行单击 / 双击触发等。
+         * 不配置图标时可以用组件方法 expandRow / collapseRow / toggleRowExpand，
+         * 或在行内（自定义单元格、操作列、展开区）派发 ROW_EXPAND_EVENT 事件来控制。
+         * 同一时间只展开一行。
+         */
+        rowExpansion?: RowExpansion<T> | null;
+    };
+    exports: {
+        expandRow: (data: T) => Promise<void>;
+        collapseRow: (data?: T) => void;
+        toggleRowExpand: (data: T) => Promise<void>;
+        isRowExpanded: (data: T) => boolean;
+        getExpandedRow: () => T | null;
     };
-    exports: {};
     bindings: "inlineRowHeight" | "selectedRows";
     slots: {};
     events: {};
@@ -43,7 +57,13 @@ declare class __sveltets_Render<T = any> {
     events(): ReturnType<typeof $$render<T>>['events'];
     slots(): ReturnType<typeof $$render<T>>['slots'];
     bindings(): "inlineRowHeight" | "selectedRows";
-    exports(): {};
+    exports(): {
+        expandRow: (data: T) => Promise<void>;
+        collapseRow: (data?: T | undefined) => void;
+        toggleRowExpand: (data: T) => Promise<void>;
+        isRowExpanded: (data: T) => boolean;
+        getExpandedRow: () => T | null;
+    };
 }
 interface $$IsomorphicComponent {
     new <T = any>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T>['props']>, ReturnType<__sveltets_Render<T>['events']>, ReturnType<__sveltets_Render<T>['slots']>> & {

package/dist/data_table/README.md

@@ -55,6 +55,7 @@ import type { DataColumn, ActionsColumn, IndicatorColumn, RowAction } from "@tic
 | `style` | `string` | `""` | Additional CSS styles |
 | `summaryLabel` | `string` | i18n `dataTable.summaryLabel` ("Total") | Label of the summary row; empty string hides it |
 | `summaryValues` | `Record<string, any> \| null` | `null` | External totals keyed by field; override local aggregation (server-side totals for paged data) |
+| `rowExpansion` | `RowExpansion \| null` | `null` | Row expansion config (inline component, toggle icon, click / double-click trigger…), see [Row Expansion](#row-expansion) |
 
 ## Types
 
@@ -134,7 +135,28 @@ interface IndicatorColumn {
   width: number;                   // Column width in pixels
   selectable?: boolean;            // Whether rows are selectable
   showRowNo?: boolean;             // Whether to show row numbers
-  buildInlineComponent?: (data: any) => Promise<any>;  // Inline component builder
+  /** @deprecated use the DataTable `rowExpansion` prop instead */
+  buildInlineComponent?: (data: any) => Promise<any>;
+}
+```
+
+### RowExpansion
+
+```typescript
+interface RowExpansion<T = any> {
+  build: (data: T) => Promise<Component> | Component; // inline component builder (may be async)
+  showToggle?: boolean;             // show the expand icon in the indicator column, default true (needs indicatorColumn)
+  trigger?: 'click' | 'dblclick';   // toggle by clicking / double-clicking the row; unset by default
+  isExpandable?: (data: T) => boolean; // which rows may expand
+  onExpandChange?: (data: T | null) => void; // fired on expand / collapse (null when collapsed)
+}
+
+// Props received by the inline component: data (row data) and context
+interface RowExpandContext<T = any> {
+  data: T;
+  collapse: () => void;                       // collapse the expanded row
+  actions: Array<RowAction<T>>;               // the row's actions (from actionsColumn.getActions)
+  invoke: (label: string) => Promise<boolean>; // run a row action by label
 }
 ```
 
@@ -486,60 +508,36 @@ Using the custom component in column definitions:
   import OrderDetails from "./OrderDetails.svelte";
   
   const columns = [
-    { text: "Order ID", field: "orderId", width: 120 },
-    { text: "Customer", field: "customer", width: 150 },
-    { text: "Total", field: "total", width: 100, align: "right",
+    { title: "Order ID", field: "orderId", width: 120 },
+    { title: "Customer", field: "customer", width: 150 },
+    { title: "Total", field: "total", width: 100, align: "right",
       formatter: (value) => `$${value?.toFixed(2) ?? '0.00'}`
     },
-    { text: "Status", field: "status", width: 120, align: "center" },
-    { text: "Date", field: "orderDate", width: 120 }
+    { title: "Status", field: "status", width: 120, align: "center" }
   ];
   
-  const indicatorColumn = {
-    width: 50,
-    selectable: false,
-    showRowNo: false,
-    buildInlineComponent: async (orderData) => {
-      // Simulate API call to fetch order details
-      await new Promise(resolve => setTimeout(resolve, 1000));
+  const indicatorColumn = { width: 50 };
+
+  const rowExpansion = {
+    build: async (orderData) => {
+      // e.g. fetch the details first, then pick the component
+      await new Promise(resolve => setTimeout(resolve, 300));
       return OrderDetails;
     }
   };
-  
-  const orders = [
-    {
-      orderId: "ORD-001",
-      customer: "John Doe",
-      total: 299.99,
-      status: "Shipped",
-      orderDate: "2024-01-15",
-      items: [
-        { product: "Laptop", quantity: 1, price: 299.99 }
-      ]
-    },
-    {
-      orderId: "ORD-002", 
-      customer: "Jane Smith",
-      total: 149.98,
-      status: "Processing",
-      orderDate: "2024-01-14",
-      items: [
-        { product: "Mouse", quantity: 2, price: 24.99 },
-        { product: "Keyboard", quantity: 1, price: 99.99 }
-      ]
-    }
-  ];
 </script>
 
 <DataTable 
   {columns} 
   list={orders} 
   {indicatorColumn}
-  inlineRowHeight={200}
+  {rowExpansion}
   emptyText="No orders found"
 />
 ```
 
+See [Row Expansion](#row-expansion) for other triggers and for closing / running row actions from inside the expanded panel.
+
 ### Table with Frozen Columns
 
 ```svelte
@@ -837,6 +835,89 @@ Set `summary` on any column (or pass `summaryValues` for a column's field) and a
 - **Paging**: pass server totals via `summaryValues` (keyed by field); they win over local aggregation and work on columns without `summary`.
 - Background: CSS variable `--topside-data-table-summary-bg` (defaults to the header background).
 
+## Row Expansion
+
+Configured through `rowExpansion`. Only one row is expanded at a time; the inline component receives `data` (the row data) and `context` (a `RowExpandContext`).
+
+### Triggers
+
+```svelte
+<script>
+  import DataTable from "@ticatec/topside-elements/DataTable";
+  import OrderDetails from "./OrderDetails.svelte";
+
+  let table;
+
+  const rowExpansion = {
+    build: async (order) => OrderDetails,
+    showToggle: false,       // no expand icon in the indicator column (default true)
+    trigger: 'dblclick',     // double-click the row to toggle; 'click' for single click (clicks on buttons / links / inputs are ignored)
+    isExpandable: (order) => order.items?.length > 0,
+    onExpandChange: (order) => console.log('expanded:', order)   // null when collapsed
+  };
+
+  const actionsColumn = {
+    width: 120,
+    getActions: (order) => [
+      { label: 'Edit', handler: () => edit(order) },
+      // an action button can drive expansion through the component methods
+      { label: 'Details', handler: () => table.toggleRowExpand(order) }
+    ]
+  };
+</script>
+
+<DataTable bind:this={table} {columns} {list} {rowExpansion} {actionsColumn} />
+<button onclick={() => table.expandRow(list[0])}>Expand first row</button>
+<button onclick={() => table.collapseRow()}>Collapse</button>
+```
+
+Component methods (call them on the `bind:this` instance; rows are matched by data object identity):
+
+| Method | Description |
+|--------|-------------|
+| `expandRow(data)` | Expand the row (ignored when already expanded, not allowed by `isExpandable`, or not found); returns a Promise |
+| `collapseRow(data?)` | Collapse the row; without an argument collapses whatever is expanded |
+| `toggleRowExpand(data)` | Toggle the row; returns a Promise |
+| `isRowExpanded(data)` | Whether the row is expanded |
+| `getExpandedRow()` | Data of the expanded row, or `null` |
+
+### Triggering from a custom cell
+
+A custom `render` component or an `ActionCell` does not need the table instance: dispatch a request from any element inside the row and the DataTable resolves the row itself.
+
+```svelte
+<!-- OrderNoCell.svelte -->
+<script>
+  import { requestRowToggle } from "@ticatec/topside-elements/DataTable";
+  let { data } = $props();
+</script>
+
+<a href="#" onclick={(e) => { e.preventDefault(); requestRowToggle(e.currentTarget); }}>{data.orderId}</a>
+```
+
+Helpers: `requestRowExpand(el)`, `requestRowCollapse(el)`, `requestRowToggle(el)`. You can also dispatch `ROW_EXPAND_EVENT` (`topside-row-expand`, `detail: { expanded?: boolean }`, `bubbles: true`) yourself. Requests are ignored when no `rowExpansion` is configured.
+
+### Closing / running row actions from the expanded panel
+
+```svelte
+<!-- OrderDetails.svelte -->
+<script>
+  let { data, context } = $props();
+</script>
+
+<div>
+  {#each context.actions as action}
+    <button disabled={action.disabled} onclick={() => action.handler(data)}>{action.label}</button>
+  {/each}
+  <button onclick={() => context.invoke('Edit')}>Edit</button>
+  <button onclick={() => context.collapse()}>Close</button>
+</div>
+```
+
+`context.actions` is the result of `actionsColumn.getActions(data)` (an empty array without an `actionsColumn`); deeply nested children can also call `requestRowCollapse(el)` to close their row.
+
+> Compatibility: the legacy `indicatorColumn.buildInlineComponent` still works and is equivalent to `rowExpansion = { build }`.
+
 ## Styling
 
 The DataTable component supports extensive styling customization through CSS custom properties and classes:

package/dist/data_table/README_CN.md

@@ -55,6 +55,7 @@ import type { DataColumn, ActionsColumn, IndicatorColumn, RowAction } from "@tic
 | `style` | `string` | `""` | 附加 CSS 样式 |
 | `summaryLabel` | `string` | i18n `dataTable.summaryLabel`（合计） | 合计行标签，传空串不显示 |
 | `summaryValues` | `Record<string, any> \| null` | `null` | 外部合计值（按 field），优先于本地计算，用于分页时显示服务端全量合计 |
+| `rowExpansion` | `RowExpansion \| null` | `null` | 行展开配置（展开区组件、是否显示图标、单击 / 双击触发等），见[行展开](#行展开) |
 
 ## 类型
 
@@ -134,7 +135,28 @@ interface IndicatorColumn {
   width: number;                   // 列宽（像素）
   selectable?: boolean;            // 行是否可选择
   showRowNo?: boolean;             // 是否显示行号
-  buildInlineComponent?: (data: any) => Promise<any>;  // 内联组件生成器
+  /** @deprecated 请改用 DataTable 的 rowExpansion 属性 */
+  buildInlineComponent?: (data: any) => Promise<any>;
+}
+```
+
+### RowExpansion
+
+```typescript
+interface RowExpansion<T = any> {
+  build: (data: T) => Promise<Component> | Component; // 展开区组件生成器（可异步）
+  showToggle?: boolean;             // 指示列是否显示展开图标，默认 true（需配置 indicatorColumn）
+  trigger?: 'click' | 'dblclick';   // 整行单击 / 双击切换展开，默认不设置
+  isExpandable?: (data: T) => boolean; // 哪些行允许展开
+  onExpandChange?: (data: T | null) => void; // 展开 / 收起回调
+}
+
+// 展开区组件收到的属性：data（行数据）与 context
+interface RowExpandContext<T = any> {
+  data: T;
+  collapse: () => void;                       // 关闭当前展开行
+  actions: Array<RowAction<T>>;               // 本行的行动作（来自 actionsColumn.getActions）
+  invoke: (label: string) => Promise<boolean>; // 按 label 执行行动作
 }
 ```
 
@@ -486,60 +508,36 @@ interface RowAction {
   import OrderDetails from "./OrderDetails.svelte";
   
   const columns = [
-    { text: "订单ID", field: "orderId", width: 120 },
-    { text: "客户", field: "customer", width: 150 },
-    { text: "总计", field: "total", width: 100, align: "right",
+    { title: "订单ID", field: "orderId", width: 120 },
+    { title: "客户", field: "customer", width: 150 },
+    { title: "总计", field: "total", width: 100, align: "right",
       formatter: (value) => `¥${value?.toFixed(2) ?? '0.00'}`
     },
-    { text: "状态", field: "status", width: 120, align: "center" },
-    { text: "日期", field: "orderDate", width: 120 }
+    { title: "状态", field: "status", width: 120, align: "center" }
   ];
   
-  const indicatorColumn = {
-    width: 50,
-    selectable: false,
-    showRowNo: false,
-    buildInlineComponent: async (orderData) => {
-      // 模拟 API 调用以获取订单详情
-      await new Promise(resolve => setTimeout(resolve, 1000));
+  const indicatorColumn = { width: 50 };
+
+  const rowExpansion = {
+    build: async (orderData) => {
+      // 可以先请求明细再决定展开区组件
+      await new Promise(resolve => setTimeout(resolve, 300));
       return OrderDetails;
     }
   };
-  
-  const orders = [
-    {
-      orderId: "ORD-001",
-      customer: "张伟",
-      total: 2999.99,
-      status: "已发货",
-      orderDate: "2024-01-15",
-      items: [
-        { product: "笔记本电脑", quantity: 1, price: 2999.99 }
-      ]
-    },
-    {
-      orderId: "ORD-002", 
-      customer: "李娜",
-      total: 1499.98,
-      status: "处理中",
-      orderDate: "2024-01-14",
-      items: [
-        { product: "鼠标", quantity: 2, price: 249.99 },
-        { product: "键盘", quantity: 1, price: 999.99 }
-      ]
-    }
-  ];
 </script>
 
 <DataTable 
   {columns} 
   list={orders} 
   {indicatorColumn}
-  inlineRowHeight={200}
+  {rowExpansion}
   emptyText="未找到订单"
 />
 ```
 
+更多触发方式与展开区内关闭 / 调用行动作见下文[行展开](#行展开)。
+
 ### 带有冻结列的表格
 
 ```svelte
@@ -862,6 +860,89 @@ const columns: DataColumn[] = [
 
 合计行背景色可用 CSS 变量 `--topside-data-table-summary-bg` 覆盖（默认同表头）。
 
+## 行展开
+
+通过 `rowExpansion` 配置。同一时间只展开一行；展开区组件收到 `data`（行数据）与 `context`（`RowExpandContext`）两个属性。
+
+### 触发方式
+
+```svelte
+<script>
+  import DataTable from "@ticatec/topside-elements/DataTable";
+  import OrderDetails from "./OrderDetails.svelte";
+
+  let table;
+
+  const rowExpansion = {
+    build: async (order) => OrderDetails,
+    showToggle: false,       // 不在指示列显示展开图标（默认 true）
+    trigger: 'dblclick',     // 双击行切换；'click' 为单击（点到按钮 / 链接 / 输入框不会触发）
+    isExpandable: (order) => order.items?.length > 0,
+    onExpandChange: (order) => console.log('expanded:', order)   // 收起时为 null
+  };
+
+  const actionsColumn = {
+    width: 120,
+    getActions: (order) => [
+      { label: '编辑', handler: () => edit(order) },
+      // 操作列按钮通过组件方法控制展开
+      { label: '明细', handler: () => table.toggleRowExpand(order) }
+    ]
+  };
+</script>
+
+<DataTable bind:this={table} {columns} {list} {rowExpansion} {actionsColumn} />
+<button onclick={() => table.expandRow(list[0])}>展开第一行</button>
+<button onclick={() => table.collapseRow()}>收起</button>
+```
+
+组件方法（`bind:this` 后调用，按行数据对象匹配）：
+
+| 方法 | 说明 |
+|------|------|
+| `expandRow(data)` | 展开指定行（已展开 / 不允许展开 / 找不到时忽略），返回 Promise |
+| `collapseRow(data?)` | 收起指定行；不传参数收起当前展开行 |
+| `toggleRowExpand(data)` | 切换指定行，返回 Promise |
+| `isRowExpanded(data)` | 该行是否展开 |
+| `getExpandedRow()` | 当前展开行的数据，没有为 `null` |
+
+### 在自定义单元格里触发
+
+自定义 `render` 组件或 `ActionCell` 不需要拿到表格实例：在行内任意元素上派发事件即可，DataTable 会定位到所在行。
+
+```svelte
+<!-- OrderNoCell.svelte -->
+<script>
+  import { requestRowToggle } from "@ticatec/topside-elements/DataTable";
+  let { data } = $props();
+</script>
+
+<a href="#" onclick={(e) => { e.preventDefault(); requestRowToggle(e.currentTarget); }}>{data.orderId}</a>
+```
+
+可用的助手：`requestRowExpand(el)`、`requestRowCollapse(el)`、`requestRowToggle(el)`；也可以自己派发 `ROW_EXPAND_EVENT`（`topside-row-expand`，`detail: { expanded?: boolean }`，需要 `bubbles: true`）。没有配置 `rowExpansion` 时这些请求被忽略。
+
+### 展开区内关闭 / 调用行动作
+
+```svelte
+<!-- OrderDetails.svelte -->
+<script>
+  let { data, context } = $props();
+</script>
+
+<div>
+  {#each context.actions as action}
+    <button disabled={action.disabled} onclick={() => action.handler(data)}>{action.label}</button>
+  {/each}
+  <button onclick={() => context.invoke('编辑')}>编辑</button>
+  <button onclick={() => context.collapse()}>关闭</button>
+</div>
+```
+
+`context.actions` 即 `actionsColumn.getActions(data)` 的结果（没有 `actionsColumn` 时为空数组）；嵌套很深的子组件也可以用 `requestRowCollapse(el)` 关闭所在行。
+
+> 兼容：旧写法 `indicatorColumn.buildInlineComponent` 仍然有效，等价于 `rowExpansion = { build }`。
+
 ## 样式
 
 DataTable 组件通过 CSS 自定义属性和类支持广泛的样式定制：