跳到主要内容

文档读取

在服务端 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 提供,脚本不能通过参数覆盖。

参数​

参数类型说明
fileIdstring必填,文件资产 UUID
startChunknumber起始文字块索引,从 0 开始,默认 0
startCharacternumber首个文字块内的起始字符位置,从 0 开始,默认 0
maxChunksnumber每次最多读取的文字块数量,整数 1–50,默认 20
maxCharsnumber每次最多读取的字符数量,整数 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_INVALIDUUID、参数范围、类型不合法,或包含未声明字段
DOCUMENT_FILE_NOT_FOUND当前工作空间中没有该文件
DOCUMENT_FILE_NOT_READY文件尚未就绪
DOCUMENT_FORMAT_UNSUPPORTED不支持的文件扩展名
DOCUMENT_FILE_TOO_LARGE超出配置的解析大小限制
DOCUMENT_READ_POSITION_INVALID续读位置不合法

解析服务不可用或解析过程失败时也会抛出异常;需要自行处理时,可在脚本中使用 try/catch。