Skip to content

caosinian2014-coder/feishu-markdown-viewer

BranchesTags

Repository files navigation

飞书多维表格 Markdown 代码显示插件

当前版本：v1.0

项目概述

这是一个飞书多维表格插件，用于从多维表格单元格中读取并显示 Markdown 格式的代码内容。

技术栈

  • 前端框架: Vue 3 (Composition API)
  • 构建工具: Vite 5
  • 语言: TypeScript
  • UI框架: Naive UI (轻量级 Vue 3 UI 库)
  • 核心SDK: @lark-base-open/js-sdk (飞书多维表格开放平台 SDK)
  • Markdown渲染: markdown-it
  • 代码高亮: highlight.js

开发文档与 API 用法

以下为本项目与官方文档对齐的单元格读取规范（来源：Base JS SDK 示例与 Table API 文档）。

  • 获取当前表：bitable.base.getActiveTable()（或根据选择 bitable.base.getSelection() 决定 tableId）
  • 获取记录列表：table.getRecordIdList() / table.getRecordList()
  • 读取单元格原始值（优先）：table.getCellValue(fieldId, recordId)
  • 读取单元格纯文本（回退）：table.getCellString(fieldId, recordId)
  • 从 Field/Record 也可读取：
    • field.getCellValue(recordId) / field.getCellString(recordId)
    • record.getCellValue(fieldId) / record.getCellString(fieldId)

本项目统一约定：

  • 优先使用 getCellValue(fieldId, recordId)；若为空再回退 getCellString(fieldId, recordId)；
  • 仍为空时，JSON 展示原始值便于排查；
  • 参数顺序统一为：先 fieldId，后 recordId。

示例（推荐流程）：

const table = await bitable.base.getActiveTable()
const value = await table.getCellValue(fieldId, recordId)
let text = extractTextFromValue(value)
if (!text) {
  text = await table.getCellString(fieldId, recordId)
}
if (!text && value != null) {
  text = typeof value === 'string' ? value : JSON.stringify(value)
}
render(text)

参考文档要点

飞书多维表格插件开发关键信息

1. 核心SDK (@lark-base-open/js-sdk)

  • bitable: 多维表格主要接口
  • FieldType: 字段类型枚举
  • ViewType: 视图类型枚举
  • base: 基础功能模块

2. 关键API

  • bitable.bridge.getTheme(): 获取主题（深色/浅色）
  • bitable.bridge.getLanguage(): 获取语言设置
  • bitable.bridge.onThemeChange(): 监听主题变化
  • 表格操作、视图操作、字段操作等API

3. 项目结构（参考示例）

项目根目录/
├── src/
│   ├── App.vue           # 主应用组件（处理主题、国际化）
│   ├── main.ts           # 应用入口
│   ├── views/            # 视图/功能页面
│   ├── components/       # 通用组件
│   ├── utils/            # 工具函数
│   └── locales/          # 国际化文件
├── public/               # 静态资源
├── index.html            # HTML入口
├── package.json          # 项目配置
├── vite.config.ts        # Vite配置
└── tsconfig.json         # TypeScript配置

4. 开发环境要求

  • 需要HTTPS证书（开发环境）
  • 使用 pnpm 作为包管理器
  • 支持热更新开发

5. 插件发布流程

  • 使用 vite build 构建生产版本
  • 将构建产物上传到飞书开放平台
  • 需要飞书开放平台账号和权限

功能规划

核心功能

  1. 单元格内容读取

    • 选择目标表格和字段
    • 读取单元格中的Markdown代码内容

  2. Markdown渲染

    • 解析Markdown格式
    • 渲染代码块
    • 支持代码语法高亮

  3. 界面展示

    • 清晰的代码展示界面
    • 支持深色/浅色主题切换
    • 支持代码复制功能

  4. 多语言支持

    • 中文（简体）
    • 英文

扩展功能（可选）

  • 代码编辑功能
  • 将编辑后的内容写回单元格
  • 支持多种代码高亮主题
  • 导出功能

开发计划

阶段一：项目初始化 ✓

  • 创建项目目录
  • 拉取参考项目
  • 分析技术栈和项目结构

阶段二：基础搭建 ✓

  • 初始化项目配置（package.json, vite.config.ts等）
  • 配置TypeScript
  • 搭建基础项目结构
  • 配置开发环境（HTTPS证书）

阶段三：核心功能开发 ✓

  • 实现表格/字段选择组件
  • 实现单元格内容读取功能
  • 集成Markdown解析库
  • 集成代码高亮库
  • 实现内容渲染组件

阶段四：UI/UX优化 ✓

  • 实现主题切换适配
  • 添加国际化支持
  • 优化界面布局和交互
  • 添加代码复制功能

阶段五：测试与优化 ✓

  • 功能测试（代码检查通过）
  • 性能优化（构建配置已优化）
  • 兼容性测试（TypeScript严格模式）

阶段六：构建与发布 ✅ 准备就绪

  • 配置生产环境构建
  • 构建项目
  • 准备发布材料（文档完备）
  • 上传到飞书开放平台（等待用户操作）

参考资源

项目配置信息

当前配置（测试环境）

  • 插件名称: Markdown Code Viewer / Markdown代码查看器
  • 插件描述: 从多维表格单元格读取并显示Markdown格式的代码内容
  • App ID: 请在 .env 中配置 VITE_FEISHU_APP_ID
  • Markdown渲染: markdown-it
  • 代码高亮: highlight.js
  • 开发端口: 5173
  • HTTPS证书: 已生成自签名证书（localhost.pem / localhost-key.pem）

环境变量配置

项目使用 .env 文件管理敏感配置信息：

# 查看配置模板
cat .env.example

# 实际配置已写入 .env 文件（不会提交到git）

重要提示：

  • .env 文件已添加到 .gitignore，不会泄露到版本控制
  • 正式发布前需要在飞书开放平台创建正式应用，并更新 App ID 和 App Secret

版本与现状

  • 当前版本：v1.0
  • 主要功能：单元格 Markdown 渲染与代码高亮、深浅色主题、复制原文、精简/全功能预览切换、按宿主选择记录/字段
  • 生产构建：已通过（pnpm build）

快速开始

1. 安装依赖

cd feishu-bitable-markdown-plugin
pnpm install

2. 启动开发服务器

pnpm dev

开发服务器将在 https://localhost:5173 启动

3. 在飞书多维表格中测试

  1. 打开飞书多维表格
  2. 进入插件管理 https://<your-HTTPS-domain>/feishu-bitable-markdown-plugin/?v=<timestamp>
  3. 保存后在多维表格中打开插件进行验证

4. 构建生产版本

pnpm build

构建产物将输出到 dist/ 目录

5. 发布到飞书开放平台

  1. 确认 dist/ 产物完整且已本地验证
  2. 登录飞书开放平台，在插件管理页面上传 dist/ 内容
  3. 在生产环境更新 .env 中的 VITE_FEISHU_APP_ID 和 VITE_FEISHU_APP_SECRET

6. 远端部署与域名

  • 严格路径规范：线上访问路径固定为 /feishu-bitable-markdown-plugin/
  • 线上访问示例：https://caosinian.top/feishu-bitable-markdown-plugin/?v=20251023-09
  • 文件系统部署目录（默认）：/var/www/feishu-bitable-markdown-plugin
  • 部署步骤（密码方式）： 
    pnpm build

export SERVER_HOST="" export SERVER_USER="root" export SERVER_NAME="" export SSHPASS="{{SERVER_PASSWORD}}" # 请以环境变量方式注入密码 ./scripts/deploy.sh

- 部署步骤（SSH 免密）：直接 rsync 到默认目录，然后按下方 Nginx 配置即可
```bash
pnpm build
rsync -avz dist/ root@<your-server-host>:/var/www/feishu-bitable-markdown-plugin/
  • Nginx 示例（子路径部署）： 
    server {
  listen 80;

server_name ; location /feishu-bitable-markdown-plugin/ { alias /var/www/feishu-bitable-markdown-plugin/; index index.html; try_files $uri $uri/ /feishu-bitable-markdown-plugin/index.html; } location /feishu-bitable-markdown-plugin/assets/ { alias /var/www/feishu-bitable-markdown-plugin/assets/; expires 1y; add_header Cache-Control "public, immutable"; } }

- 若遇到域名/证书问题，可先用 IP 测试（HTTP），再切回 HTTPS 域名。

## 技术选型说明

### 为什么选择 markdown-it？
- 功能强大，插件生态丰富
- 支持扩展语法
- 性能优秀，适合大文档渲染

### 为什么选择 highlight.js？
- 支持 190+ 编程语言
- 自动语言检测
- 主题丰富，易于定制

## 测试结果

### 代码质量检查
```bash
pnpm lint
# ✅ 通过：只有1个预期的v-html警告

构建测试

pnpm build
# ✅ 成功：生成了生产环境构建产物
# - index.html (0.45 kB)
# - CSS (3.33 kB, gzipped: 1.20 kB)
# - JS bundles (2.4 MB, gzipped: 775 kB)

TypeScript类型检查

✅ 严格模式开启，所有类型定义完备

已实现功能

  • ✅ 表格/字段/记录选择
  • ✅ Markdown渲染和代码高亮
  • ✅ 深色/浅色主题自动切换
  • ✅ 中英文国际化
  • ✅ 代码复制功能
  • ✅ 原始内容/预览切换

注意事项

  1. ✅ HTTPS证书已自动生成（开发用自签名证书）
  2. ✅ 敏感信息已安全存储在 .env 文件中
  3. 🔒 正式发布前需要更新为生产环境的 App ID 和 App Secret
  4. 📝 插件名称和描述可在发布前修改
  5. 🔐 确保使用的SDK版本与飞书平台兼容
  6. 📋 遵循飞书插件开发规范
  7. 🛡️ 注意权限申请和数据安全

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

1 tags

Packages

No packages published

Languages