162 lines
8.7 KiB
Markdown
162 lines
8.7 KiB
Markdown
# 区域操作
|
||
|
||
## 使用场景
|
||
|
||
用户说"清空/清除区域/擦除内容/清除格式":
|
||
- 清除区域 → `range clear`
|
||
- 仅清除值 → `range clear --type content`（默认）
|
||
- 仅清除格式 → `range clear --type format`
|
||
- 全部清除 → `range clear --type all`
|
||
- 请勿用 `range update` 写入空字符串来模拟清空，`range clear` 更简洁且支持按类型清除
|
||
|
||
用户说"排序/给数据排序/按某列排序/升序/降序":
|
||
- 区域排序 → `range sort`
|
||
- **排序前必须先 `range read` 前 3-5 行**：读取排序范围的前几行（如范围是 A1:D100 则读 A1:D5），对比首行与后续行的模式来判断是否有表头：
|
||
- 首行全文本 + 后续行含数字/日期 → 有表头，加 `--has-header`
|
||
- 首行与后续行模式一致（都是数字或都是文本） → 无表头，不加
|
||
- 首行值语义像列标题（如"姓名""金额""日期"）且与后续行明显不同 → 有表头
|
||
禁止不读就排——表头误排入数据是不可撤销的破坏性操作
|
||
- 请勿用 `range read` 读取数据后客户端排序再 `range update` 写回，`range sort` 是服务端原子操作
|
||
|
||
用户说"自动填充/填充序列/向下填充/拖拽填充/序列递增":
|
||
- 自动填充 → `range fill`
|
||
- 请勿用 `range read` 读取源数据后手动计算规律再 `range update` 写入，`range fill` 支持服务端智能填充
|
||
|
||
用户说"批量清除/批量操作/一次执行多个写操作/原子批量/先清除再写入":
|
||
- 批量清除多个区域 → `range batch-clear`
|
||
- 组合多个不同写操作 → `batch-update`
|
||
- 详见 [sheet-batch-operations](./sheet-batch-operations.md)
|
||
|
||
用户说"复制区域/把这块数据复制到/复制到另一个工作表":
|
||
- 复制区域 → `range copy-to`
|
||
- 跨工作表 → `range copy-to --target-sheet-id Sheet2` 或 `--target-range "Sheet2!A1"`
|
||
- 请勿用 `range read` + `range update` 读取再写入来模拟复制，`range copy-to` 是原子操作，保留公式引用调整
|
||
|
||
用户说"移动区域/把数据移到/剪切粘贴/移到另一个工作表":
|
||
- 移动区域 → `range move-to`
|
||
- 跨工作表 → `range move-to --target-sheet-id Sheet2` 或 `--target-range "Sheet2!A1"`
|
||
- 请勿用 `range read` + `range update` + `range clear` 读取-写入-清空来模拟移动，`range move-to` 是原子操作
|
||
|
||
## 命令详细参考
|
||
|
||
### 清除区域
|
||
```
|
||
Usage:
|
||
dws sheet range clear [flags]
|
||
Example:
|
||
dws sheet range clear --node <NODE_ID> --sheet-id <SHEET_ID> --range "A1:B3"
|
||
dws sheet range clear --node <NODE_ID> --sheet-id <SHEET_ID> --range "A1:B3" --type format
|
||
dws sheet range clear --node <NODE_ID> --sheet-id <SHEET_ID> --range "A1:B3" --type all
|
||
Flags:
|
||
--node string 表格文档 ID 或 URL (必填)
|
||
--sheet-id string 工作表 ID 或名称 (必填)
|
||
--range string 清除范围，A1 表示法 (必填)
|
||
--type string 清除类型: content(仅值,默认) / format(仅格式) / all(全部)
|
||
```
|
||
|
||
### 区域排序
|
||
```
|
||
Usage:
|
||
dws sheet range sort [flags]
|
||
Example:
|
||
dws sheet range sort --node <NODE_ID> --sheet-id <SHEET_ID> --range "A1:D10" \
|
||
--sort-keys '[{"column":"A","ascending":true}]'
|
||
dws sheet range sort --node <NODE_ID> --sheet-id <SHEET_ID> --range "A1:D10" \
|
||
--sort-keys '[{"column":"A","ascending":true},{"column":"C","ascending":false}]' --has-header
|
||
Flags:
|
||
--node string 表格文档 ID 或 URL (必填)
|
||
--sheet-id string 工作表 ID 或名称 (必填)
|
||
--range string 排序范围，A1 表示法 (必填)
|
||
--sort-keys string 排序规则 JSON 数组 (必填)
|
||
--has-header 首行是否为表头（不参与排序）
|
||
```
|
||
|
||
`--sort-keys` 格式：`[{"column":"A","ascending":true}]`，`column` 使用字母列名（如 "A"、"B"、"AA"）。多级排序按数组顺序优先级递减。
|
||
|
||
### 区域自动填充
|
||
```
|
||
Usage:
|
||
dws sheet range fill [flags]
|
||
Example:
|
||
dws sheet range fill --node <NODE_ID> --sheet-id <SHEET_ID> \
|
||
--source-range "A1:A5" --target-range "A6:A20"
|
||
dws sheet range fill --node <NODE_ID> --sheet-id <SHEET_ID> \
|
||
--source-range "A1:A5" --target-range "A6:A20" --fill-type copy
|
||
Flags:
|
||
--node string 表格文档 ID 或 URL (必填)
|
||
--sheet-id string 工作表 ID 或名称 (必填)
|
||
--source-range string 源数据范围，A1 表示法 (必填)
|
||
--target-range string 目标填充范围，A1 表示法 (必填)
|
||
--fill-type string 填充类型: series(序列,默认) / copy(复制) / onlystyle(仅格式) / withoutstyle(仅值)
|
||
```
|
||
|
||
目标范围须与源范围在行或列维度对齐（不支持对角填充）。
|
||
|
||
### 复制区域
|
||
```
|
||
Usage:
|
||
dws sheet range copy-to [flags]
|
||
Example:
|
||
dws sheet range copy-to --node <NODE_ID> --sheet-id <SHEET_ID> \
|
||
--source-range "A1:C5" --target-range "D1"
|
||
dws sheet range copy-to --node <NODE_ID> --sheet-id <SHEET_ID> \
|
||
--source-range "A1:C5" --target-range "A1" --target-sheet-id "Sheet2"
|
||
dws sheet range copy-to --node <NODE_ID> --sheet-id <SHEET_ID> \
|
||
--source-range "A1:C5" --target-range "D1" --paste-type values
|
||
Flags:
|
||
--node string 表格文档 ID 或 URL (必填)
|
||
--sheet-id string 源工作表 ID 或名称 (必填)
|
||
--source-range string 源范围，A1 表示法 (必填)
|
||
--target-range string 目标位置，A1 表示法 (必填)
|
||
--target-sheet-id string 目标工作表 ID 或名称（可选，不传则复制到同一工作表）
|
||
--paste-type string 粘贴类型: values(仅值) / formulas(仅公式) / formats(仅格式) / all(全部,默认)
|
||
```
|
||
|
||
支持跨工作表复制，两种方式指定目标工作表：
|
||
- `--target-sheet-id "Sheet2"` 显式指定
|
||
- `--target-range "Sheet2!A1"` 在目标范围中携带工作表前缀
|
||
|
||
源和目标范围不能重叠（同表时）。
|
||
|
||
### 移动区域
|
||
```
|
||
Usage:
|
||
dws sheet range move-to [flags]
|
||
Example:
|
||
dws sheet range move-to --node <NODE_ID> --sheet-id <SHEET_ID> \
|
||
--source-range "A1:C5" --target-range "D1"
|
||
dws sheet range move-to --node <NODE_ID> --sheet-id <SHEET_ID> \
|
||
--source-range "A1:C5" --target-range "A1" --target-sheet-id "Sheet2"
|
||
Flags:
|
||
--node string 表格文档 ID 或 URL (必填)
|
||
--sheet-id string 源工作表 ID 或名称 (必填)
|
||
--source-range string 源范围，A1 表示法 (必填)
|
||
--target-range string 目标位置，A1 表示法 (必填)
|
||
--target-sheet-id string 目标工作表 ID 或名称（可选，不传则移动到同一工作表）
|
||
```
|
||
|
||
支持跨工作表移动，两种方式指定目标工作表：
|
||
- `--target-sheet-id "Sheet2"` 显式指定
|
||
- `--target-range "Sheet2!A1"` 在目标范围中携带工作表前缀
|
||
|
||
源和目标范围不能重叠（同表时）。移动后源区域将被清空。
|
||
|
||
## 上下文传递
|
||
|
||
| 操作 | 从返回中提取 | 用于 |
|
||
|------|-------------|------|
|
||
| `list` | 工作表的 `sheetId` | range clear / range sort / range fill / range copy-to / range move-to 的 --sheet-id |
|
||
|
||
> **批量操作**（`range batch-clear` / `batch-update`）已拆分至 [sheet-batch-operations](./sheet-batch-operations.md)，含写入边界 + 回读校验规范、典型组合场景示例等。
|
||
|
||
## 注意事项
|
||
|
||
- ★ **`--sheet-id` 获取规范（强制）**：`sheetId` 未知时必须先通过 `dws sheet list --node <NODE_ID> --format json` 查询真实的 `sheetId` / 工作表名称后再调用，禁止凭空编造（如臆测为 `Sheet1`、`sheet1`、`0`、`default` 等）；用户仅给出工作表名称时，也应通过 `list` 校验该名称是否存在，避免名称大小写或拼写不一致导致失败
|
||
- ★ **清空区域用 `range clear` 不用 `range update`**：`range clear` 支持按类型（值/格式/全部）清除，比手动构造全空数组更简洁可靠
|
||
- ★ **复制区域用 `range copy-to` 不用 `range read` + `range update`**：原子操作，保留公式引用自动调整，支持跨工作表
|
||
- ★ **移动区域用 `range move-to` 不用 `range read` + `range update` + `range clear`**：原子操作，源区域自动清空，支持跨工作表
|
||
- ★ **排序用 `range sort` 不用 `range read` + 客户端排序 + `range update`**：服务端原子操作，支持多级排序
|
||
- ★ **排序前必须 `range read` 前几行判断表头**：读取排序范围前 3-5 行，对比首行与后续行的数据模式（类型、语义）来判断是否有表头。禁止不读就排，表头被排入数据不可撤销
|
||
- ★ **填充用 `range fill` 不用 `range read` + 手动计算 + `range update`**：服务端智能填充，支持序列递增、公式扩展等
|
||
- ★ **批量操作详见 [sheet-batch-operations](./sheet-batch-operations.md)**：`range batch-clear` 多区域清除、`batch-update` 组合写操作，均原子事务
|