文档读取
在服务端 Studio 脚本中使用 context.document.read,读取已上传文档的解析文字。该方法复用租户 Runtime 已有的文档解析能力:首次读取时解析并保存结果,文件内容未变化时复用解析缓存。
context.file.read 返回原始文件的 Base64 字节;context.document.read 返回解析文字块、标题、说明、页码和续读位置。
按行、按列读取 Excel 或 CSV
使用 context.document.readRows 读取原始 .xlsx 或 UTF-8 编码、逗号分隔的 .csv 文件。该方法直接读取源表格,不再拆分 read 返回的 Markdown 文字。
表单任务按钮可直接使用下列脚本,将 excel_file 替换为附件字段的 API 名称:
export default async function main(
payload: FormButtonRuntimePayload,
context: StudioScriptContext,
) {
const files = payload.draft?.data?.excel_file;
const fileId = Array.isArray(files) ? files[0] : undefined;
if (typeof fileId !== 'string') throw new Error('Please upload a spreadsheet first.');
const page = await context.document.readRows({
fileId,
// sheetName: 'Sheet1', // 不填则读取第一个工作表;CSV 的表名为 CSV。
headerRow: 1,
startRow: 2,
limit: 100,
});
return {
rows: page.rows.map(row => ({
rowNumber: row.rowNumber,
email: row.data['邮箱'],
number: row.data['数字'],
firstColumn: row.cells[0]?.value,
})),
nextStartRow: page.nextStartRow,
hasMore: page.hasMore,
};
}
row.data['邮箱'] 按源表格的表头取值,表头会去除首尾空格,这里不是表单字段 API 名称。row.cells[0] 是 A 列;rowNumber 和单元格的 column 从 1 开始。每行数据示例:
{
"rowNumber": 2,
"data": {
"邮箱": "contact@solncn.com",
"数字": "120.5",
"多部门": "[\"department-1\",\"department-2\"]"
}
}
CSV 单元格保持字符串,包括数字、日期、JSON 和带前导零的编号。需要时显式转换:先检查空值及格式,再用 Number(row.data['数字']);确认内容是目标 JSON 结构后用 JSON.parse(value)。CSV 解析器正确处理带引号的逗号、双引号转义、UTF-8 BOM 和单元格内换行,不会因这些内容拆错列。CSV 行号按逻辑记录计数,单元格中的换行不会增加记录行号。
XLSX 保留数字和布尔类型,日期返回 ISO 字符串。公式单元格返回已保存的计算结果及公式信息,不会重新计算公式。cells 还包含 letter、header、type、displayText、merged、masterAddress。
行列读取参数与分页
| 参数 | 说明 |
|---|---|
fileId | 必填,已上传的 XLSX 或 CSV 文件资产 UUID |
sheetName | 准确工作表名;不填时读取第一个工作表,CSV 的表名为 CSV |
headerRow | 从 1 开始的表头行,默认 1,最大 1000 |
startRow | 第一条数据行,必须大于 headerRow;默认表头下一行,最大 100000 |
limit | 每次读取 1–1000 行,默认 200 |
返回 fileAssetId、fileName、mimeType、sheetName、headerRow、startRow、endRow、rowCount、dataRowCount、columns、rows、hasMore、nextStartRow。行数包含工作表范围内的空行。继续读取时保持文件、工作表和表头参数不变:
const next = page.nextStartRow === null ? null : await context.document.readRows({
fileId,
sheetName: page.sheetName,
headerRow: page.headerRow,
startRow: page.nextStartRow,
limit: 100,
});
限制:单文件 20 MiB,最多 50 个工作表,每表最多 100000 行、200 列,所有工作表共最多 1000000 个单元格。表头为空或去空格后重名时,报错 DATA_PROCESSING_SPREADSHEET_EMPTY_HEADER 或 DATA_PROCESSING_SPREADSHEET_DUPLICATE_HEADER。工作表不存在时,报错 DATA_PROCESSING_SPREADSHEET_SHEET_NOT_FOUND;CSV 引号格式错误时,报错 DATA_PROCESSING_SPREADSHEET_INVALID_CSV;非 UTF-8 CSV 报错 DATA_PROCESSING_SPREADSHEET_CSV_UTF8_REQUIRED。旧版 .xls 应先另存为 .xlsx 或 UTF-8 CSV。
读取只返回数据。将行写入表单时,仍需明确映射字段并经过表单 SDK 正常校验,读取不会修改源文件。
读取文档
export default async function main(
payload: StudioScriptRuntimeContextPayload,
context: StudioScriptContext,
) {
const fileId = payload.input.fileId;
if (typeof fileId !== 'string') throw new Error('A fileId is required.');
const result = await context.document.read({
fileId,
maxChunks: 20,
maxChars: 30000,
});
return {
filename: result.document.filename,
text: result.content.map((chunk) => chunk.text).join('\n\n'),
next: result.position.next,
};
}
fileId 必须是当前工作空间中真实上传的文件资产 ID,例如附件对应的资产 ID。不能传文件 URL、选中的会话内容编号或第三方文档编号。执行身份和工作空间由 Runtime 提供,脚本不能通过参数覆盖。
参数
| 参数 | 类型 | 说明 |
|---|---|---|
fileId | string | 必填,文件资产 UUID |
startChunk | number | 起始文字块索引,从 0 开始,默认 0 |
startCharacter | number | 首个文字块内的起始字符位置,从 0 开始,默认 0 |
maxChunks | number | 每次最多读取的文字块数量,整数 1–50,默认 20 |
maxChars | number | 每次最多读取的字符数量,整数 1000–100000,默认 30000 |
返回值与继续读取
| 字段 | 说明 |
|---|---|
document | 包含 fileId、filename、mimeType、字节数 size、pageCount、chunkCount |
content | 文字块数组,每项包含 chunkIndex、text、headings、captions、pageNumbers、characterStart、characterEnd、complete |
position.hasMore | 是否还有未读取内容 |
position.next | 下一次读取的 { startChunk, startCharacter },读完后为 null |
达到字符限制时,一个文字块可能只返回一部分。继续读取时应同时使用 position.next 中的两个位置参数,避免遗漏或重复:
const first = await context.document.read({ fileId, maxChars: 10000 });
if (first.position.next) {
const next = await context.document.read({
fileId,
...first.position.next,
maxChars: 10000,
});
// 处理 next.content;如需续读,继续使用 next.position.next。
}
支持格式与执行说明
支持的扩展名包括 PDF、DOC/DOCX、XLS/XLSX/ODS、PPT/PPTX/ODP、ODT、CSV、TXT、Markdown、HTML、XML、JSON、YAML、常见图片、EPUB、EML、VTT、TeX。OCR 和版面提取效果取决于已部署的解析器及源文件质量。返回的是文字表示,不是原始可编辑文件,也不保证将电子表格转换为结构化业务行。
文件必须处于可读取状态,并满足部署环境配置的解析大小限制。大型文档或扫描件首次解析可能较慢,应在平台允许范围内配置合适的脚本执行超时,不应假设默认超时足以完成解析。浏览器页面资产通过已声明的服务端动作调用,不能在页面客户端直接调用。
错误处理
调用失败时会抛出异常,常见错误信息如下:
| 错误码 | 说明 |
|---|---|
SL_COMMAND_INPUT_INVALID | UUID、参数范围、类型不合法,或包含未声明字段 |
DOCUMENT_FILE_NOT_FOUND | 当前工作空间中没有该文件 |
DOCUMENT_FILE_NOT_READY | 文件尚未就绪 |
DOCUMENT_FORMAT_UNSUPPORTED | 不支持的文件扩展名 |
DOCUMENT_FILE_TOO_LARGE | 超出配置的解析大小限制 |
DOCUMENT_READ_POSITION_INVALID | 续读位置不合法 |
解析服务不可用或解析过程失败时也会抛出异常;需要自行处理时,可在脚本中使用 try/catch。