Skip to content

FEISHU-FIELD-VALIDATION.md

Latest commit

 

History

History
268 lines (194 loc) · 7.04 KB

FEISHU-FIELD-VALIDATION.md

File metadata and controls

268 lines (194 loc) · 7.04 KB
Raw

飞书字段验证功能说明

功能概述

版本: v3.5.12

从 v3.5.12 开始，「测试连接」功能新增了飞书多维表格字段验证，确保表格配置正确。

验证内容

测试连接时会自动验证以下9个必需字段（V4.3.7更新，新增分类和标签）：

字段名 字段类型 说明
标题 文本 帖子标题
链接 超链接 原帖URL（可点击跳转）
作者 文本 发帖人
分类 文本 帖子所属分类（V4.3.7新增）
标签 文本 帖子标签，多个用逗号分隔（V4.3.7新增）
保存时间 日期 自动记录保存时间
评论数 数字 评论条数
附件 附件 MD文件（勾选上传附件时使用）
正文 文本 内容摘要（不上传附件时使用）

验证规则

1. 字段名称必须完全一致

字段名称区分大小写，必须与上表完全一致。

❌ 错误示例：

  • 标 题（有空格）
  • 题目（名称不对）
  • biaoTi（拼音）

✅ 正确示例：

  • 标题

2. 字段类型必须匹配

字段 必须类型 常见错误
标题 文本 误设为多行文本
链接 超链接 误设为文本
作者 文本 误设为人员
分类 文本 -
标签 文本 -
保存时间 日期 误设为文本
评论数 数字 误设为文本
附件 附件 -
正文 文本 -

错误提示示例

示例1：缺失字段

字段配置有误：

❌ 缺失字段（2个）：
  • 「附件」(类型: 附件)
  • 「正文」(类型: 文本)

请在飞书多维表格中创建或修正这些字段。
详细要求请参考 README.md 的「飞书配置教程」。

解决方法：

  1. 打开飞书多维表格
  2. 点击表格右上角的「+」添加字段
  3. 输入字段名（如「附件」）
  4. 选择正确的字段类型（如「附件」）
  5. 保存

示例2：字段类型错误

字段配置有误：

⚠️ 字段类型错误（2个）：
  • 「链接」(期望: 超链接, 实际: 文本)
  • 「评论数」(期望: 数字, 实际: 文本)

请在飞书多维表格中创建或修正这些字段。
详细要求请参考 README.md 的「飞书配置教程」。

解决方法：

  1. 打开飞书多维表格
  2. 找到错误的字段
  3. 点击字段名右侧的「▼」→「编辑字段」
  4. 修改字段类型为正确类型
  5. 保存

注意：修改字段类型可能会导致现有数据格式变化，建议在修改前备份数据。

示例3：全部正确

✅ 连接成功！

字段配置正确（9个必需字段）
表格中有 15 条记录

使用流程

1. 创建飞书多维表格

按照 README.md 中的「飞书配置教程」创建表格和字段。

2. 填写插件配置

在扩展选项页面填写：

  • App ID
  • App Secret
  • app_token
  • table_id

3. 点击「测试连接」

插件会自动：

  1. 获取 tenant_access_token
  2. 获取表格字段列表
  3. 验证字段配置
  4. 测试访问表格记录

4. 根据提示修正

如果有错误，按照提示修正字段配置，然后重新测试。

飞书字段类型对照表

类型中文名 类型代码 用途
文本 1 短文本（如标题、作者）
数字 2 数值（如评论数）
单选 3 单选下拉
多选 4 多选下拉
日期 5 日期时间（如保存时间）
复选框 7 布尔值
人员 11 飞书用户
电话号码 13 电话
超链接 15 URL链接（如帖子链接）
附件 17 文件附件（如MD文件）
单向关联 18 关联其他表
查找引用 21 引用关联表字段
公式 22 计算公式
双向关联 23 双向关联表

常见问题

Q1: 为什么需要「附件」和「正文」两个字段？

A: 这是为了支持两种保存模式：

  • 上传附件模式（推荐）：完整内容保存为 MD 文件附件

    • 使用字段：附件
    • 优点：保留完整格式，支持大内容
    • 适合：内容较长的帖子

  • 文本模式：内容摘要保存为文本

    • 使用字段：正文
    • 优点：快速预览
    • 适合：快速索引

可以在插件配置中选择「上传 MD 附件」来切换模式。

Q2: 已有表格，如何快速修正字段？

A: 按优先级修正：

  1. 删除错误类型字段（如果已有数据，先导出备份）
  2. 重新创建正确类型字段
  3. 导入备份数据（手动调整格式）

或者创建新表格，按照要求从头配置（推荐）。

Q3: 测试连接通过后，保存时还是报错？

A: 可能的原因：

  1. 字段名称有隐藏字符（复制时带入的空格）

    • 解决：手动输入字段名，不要复制粘贴

  2. 应用未添加为协作者

    • 解决：表格右上角「...」→「更多」→「添加文档应用」

  3. 权限配置不正确

    • 解决：检查是否开通了 bitable:app 权限

  4. 应用未发布

    • 解决：飞书开放平台 → 版本管理与发布 → 发布应用

Q4: 字段验证通过，但保存时提示"FieldNameNotFound"？

A: 这通常是字段名有细微差异（如不可见字符）。建议：

  1. 在飞书表格中，删除所有相关字段
  2. 逐个重新创建，手动输入字段名
  3. 确保字段名与要求完全一致
  4. 重新测试连接

技术细节

API 调用流程

1. POST /open-apis/auth/v3/tenant_access_token/internal
   ↓ 获取 token

2. GET /open-apis/bitable/v1/apps/{app_token}/tables/{table_id}/fields
   ↓ 获取字段列表

3. 本地验证字段配置
   ↓ 检查字段名和类型

4. GET /open-apis/bitable/v1/apps/{app_token}/tables/{table_id}/records
   ↓ 测试访问记录

5. 返回测试结果

字段验证逻辑

// 构建字段映射
const fieldMap = {};
fields.forEach(field => {
  fieldMap[field.field_name] = {
    type: field.type,
    typeName: getFieldTypeName(field.type)
  };
});

// 验证每个必需字段
REQUIRED_FIELDS.forEach(required => {
  const existing = fieldMap[required.name];

  if (!existing) {
    // 字段不存在
    missingFields.push(required.name);
  } else if (existing.type !== required.type) {
    // 字段类型不匹配
    wrongTypeFields.push({
      name: required.name,
      expected: required.desc,
      actual: existing.typeName
    });
  }
});

版本历史

v3.5.12 (2026-03-11)

  • ✨ 新增飞书字段验证功能
  • ✨ 测试连接时自动检查9个必需字段
  • ✨ 详细的错误提示和修正建议

v3.5.10 及更早版本

  • 仅测试连接和权限，不验证字段配置

参考资料