From dc436c9a2dfd969d581447f24805a1d057d99a09 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=98=BF=20Cai?= Date: Thu, 15 Oct 2026 19:24:01 +0800 Subject: [PATCH] =?UTF-8?q?docs(site):=20=E8=A1=A5=E5=85=85=E8=BF=81?= =?UTF-8?q?=E7=A7=BB=E4=BE=A7=E8=BE=B9=E5=AF=BC=E8=88=AA=E4=B8=8E=E5=AE=98?= =?UTF-8?q?=E6=96=B9=20Demo=20=E4=BD=93=E9=AA=8C=E5=85=A5=E5=8F=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../acceptance.md | 19 ++++++++++ .../plan.md | 7 ++++ .../spec.md | 5 +++ .../tasks.md | 8 +++++ tdesign-site/site/docs/getting-started.md | 10 +++++- .../flutter-example-docs/guide-entry.test.mjs | 30 ++++++++++++++++ tdesign-site/site/scripts/md-to-vue.ts | 5 ++- tdesign-site/site/site.config.mjs | 36 ++++++++----------- 8 files changed, 97 insertions(+), 23 deletions(-) create mode 100644 specs/072-migration-navigation-and-demo-entry/acceptance.md create mode 100644 specs/072-migration-navigation-and-demo-entry/plan.md create mode 100644 specs/072-migration-navigation-and-demo-entry/spec.md create mode 100644 specs/072-migration-navigation-and-demo-entry/tasks.md create mode 100644 tdesign-site/site/flutter-example-docs/guide-entry.test.mjs diff --git a/specs/072-migration-navigation-and-demo-entry/acceptance.md b/specs/072-migration-navigation-and-demo-entry/acceptance.md new file mode 100644 index 0000000000..1cd6da6c5e --- /dev/null +++ b/specs/072-migration-navigation-and-demo-entry/acceptance.md @@ -0,0 +1,19 @@ +# 验收 + +本次直接核对官方CDN APK，响应200且ETag与已读取的0.2.7安装包一致；GitHub Releases当前1.0.0-alpha.1为预发布，0.2.7是正式记录。官方Web入口此前核对可访问。本次不发布、替换或重新标注线上产物版本。 + +同步最新develop后，站点示例文档26项测试通过（包含新增2项入口回归），主题6项测试通过；57份组件文档、360个生成示例映射检查通过；生产构建成功。文档同步只读检查通过，git diff --check通过。构建仍有既有的大体积chunk提示，不影响构建成功；没有浏览器人工截图记录。 + +本次没有修改Flutter组件、发布工作流或PNG基线。正式体验包的上传不属于本次文档PR。 + +交付PR1167，目标develop。最初相对1163增量7个文件；随后PR1166已经合并到develop，包含迁移正文、指南整理及路由唯一断言，本PR无需等待1163。已基于develop的313ce617重新整理提交，并逐项恢复非本次范围文件，仅保留导航、快速体验、入口回归与本Spec共7个文件。旧分支保留本地备份，远端使用旧提交校验后更新。本PR保持草稿等待页面验收与正式CI。 + +## 本地预览反馈调整 + +按用户要求移除Web在线体验、指定版本体验行，保留Android与iOS。二维码放在Android行内并使用现有站内图片。实际解码t_apk_qrcode.png，内容为https://tdesign.gtimg.com/flutter/tdesign_flutter_example.apk，与下载链接一致。 + +文档Markdown图片按Vite BASE_URL解析：本地/assets/qrcode/t_apk_qrcode.png返回200且为image/png，生产构建模块将该路径解析为/flutter/assets/qrcode/t_apk_qrcode.png。二维码文件随站点复制，未新增或修改PNG。本次图片修复另涉及Markdown渲染文件，总范围为8个文件。 + +调整后26项文档测试、6项主题测试、同步检查及生产构建再次通过。本地生成的指南模块已确认只有Android/iOS两行，Web和指定版本两行不存在。检查现有发布流程，未找到覆盖官网固定CDN APK的自动步骤；PR构建产物不等于已替换官网安装包。发布方替换同一路径APK并核对缓存及包版本时，固定链接和二维码不需要随版本修改。 + +后续按用户要求删除体验区所有版本核对与预发布说明，包括此前的简短替代句；保留Android/iOS两行入口。入口回归检查不再要求这些提示，并防止重新引入。 diff --git a/specs/072-migration-navigation-and-demo-entry/plan.md b/specs/072-migration-navigation-and-demo-entry/plan.md new file mode 100644 index 0000000000..1c2dc7243f --- /dev/null +++ b/specs/072-migration-navigation-and-demo-entry/plan.md @@ -0,0 +1,7 @@ +# 方案 + +将迁移路由从 standalone 移到开始菜单，防止重复注册；菜单顺序为快速开始、迁移指南、组件概览、常见问题、更新日志、贡献指南。路由和文件名保持稳定。 + +快速体验保留Android下载和iOS源码运行，不附加版本核对说明。Android行内直接展示站内二维码；Markdown生成模块按Vite的BASE_URL解析站内图片，以兼容本地、预览与正式部署路径。复用现有二维码资产，不复制图片。添加导航与体验入口回归，复用站点已有测试和构建入口。 + +独立 PR 直接基于最新 develop。PR1166已经带入迁移正文、指南整理及文档测试兼容修改，本PR不再依赖未合并的PR1163。范围为站点指南、导航、Markdown图片路径处理、入口回归及本Spec四个文件。 diff --git a/specs/072-migration-navigation-and-demo-entry/spec.md b/specs/072-migration-navigation-and-demo-entry/spec.md new file mode 100644 index 0000000000..9d0c7d6584 --- /dev/null +++ b/specs/072-migration-navigation-and-demo-entry/spec.md @@ -0,0 +1,5 @@ +# 迁移导航与官方体验入口 + +用户从左侧“开始”菜单可以找到迁移指南，同时保留快速开始内的升级链接。沿用既有 /flutter/migration-1-0 路由和唯一迁移正文，不建立第二份说明或自定义搜索。 + +快速开始在接入前仅提供Android APK和iOS源码体验方式，复用既有二维码并直接放在Android行内。用户已要求移除Web在线体验和指定版本体验行。二维码与APK链接指向同一固定地址，图片随站点提供，不依赖GitHub图片加载。不在用户体验区附加版本核对、正式版选择或预发布解释文字。 diff --git a/specs/072-migration-navigation-and-demo-entry/tasks.md b/specs/072-migration-navigation-and-demo-entry/tasks.md new file mode 100644 index 0000000000..dfb4be4f7d --- /dev/null +++ b/specs/072-migration-navigation-and-demo-entry/tasks.md @@ -0,0 +1,8 @@ +# 任务 + +- [x] 左侧迁移菜单与单一路由。 +- [x] 快速体验链接、二维码和版本说明。 +- [x] 验证站点测试、构建和官方地址。 +- [x] 提交独立PR并同步1166文档断言。 +- [x] 同步最新develop，移除重复差异和过时依赖，核对仅剩7个文件。 +- [x] 按用户预览反馈移除Web和指定版本行，Android行内展示站内二维码；核对二维码与下载链接一致。 diff --git a/tdesign-site/site/docs/getting-started.md b/tdesign-site/site/docs/getting-started.md index a915fe802c..b3c3fd8ece 100644 --- a/tdesign-site/site/docs/getting-started.md +++ b/tdesign-site/site/docs/getting-started.md @@ -4,8 +4,16 @@ description: 安装 TDesign Flutter 并在已有页面中使用组件。 spline: explain --- -## 接入 +## 快速体验 + +选择对应平台体验官方 Demo： +| 体验方式 | 入口 | +| --- | --- | +| Android 真机体验 | [下载官方 Demo APK](https://tdesign.gtimg.com/flutter/tdesign_flutter_example.apk)，或扫码下载。
官方 Android Demo APK 下载二维码 | +| iOS 体验 | 从[版本发布页](https://github.com/Tencent/tdesign-flutter/releases)下载对应源码，运行其中的 `tdesign-component/example` 工程。 | + +## 接入 从 0.2.7 升级时，请先阅读 [1.0 迁移指南](./migration-0.2.7-to-1.0.md)。1.0 包含不兼容的接口与默认行为变化，不能只替换组件前缀。 diff --git a/tdesign-site/site/flutter-example-docs/guide-entry.test.mjs b/tdesign-site/site/flutter-example-docs/guide-entry.test.mjs new file mode 100644 index 0000000000..db2d076aca --- /dev/null +++ b/tdesign-site/site/flutter-example-docs/guide-entry.test.mjs @@ -0,0 +1,30 @@ +import assert from 'node:assert/strict'; +import { readFileSync } from 'node:fs'; +import test from 'node:test'; + +import siteConfig from '../site.config.mjs'; + +test('migration guide is discoverable in the start menu with one stable route', () => { + const start = siteConfig.docs.find(group => group.title === '开始'); + assert.deepEqual(start.children.map(page => page.title), [ + '快速开始', '迁移指南', '组件概览', '常见问题', '更新日志', '贡献指南', + ]); + const pages = [...siteConfig.standalone, ...siteConfig.docs.flatMap(group => group.children ?? [])]; + const migration = pages.filter(page => page.path === '/flutter/migration-1-0'); + assert.equal(migration.length, 1); + assert.equal(migration[0].name, 'migration-1-0'); + assert.equal(migration[0].meta.docType, 'explain'); + assert.ok(!start.children.some(page => page.name === 'dark-mode')); +}); + +test('getting started offers official demos and keeps the migration entry', () => { + const source = readFileSync(new URL('../docs/getting-started.md', import.meta.url), 'utf8'); + assert.ok(source.indexOf('## 快速体验') < source.indexOf('## 接入')); + assert.doesNotMatch(source, /Web 在线体验|指定版本体验/); + assert.match(source, /https:\/\/tdesign\.gtimg\.com\/flutter\/tdesign_flutter_example\.apk/); + assert.match(source, /https:\/\/github\.com\/Tencent\/tdesign-flutter\/releases/); + assert.match(source, /migration-0\.2\.7-to-1\.0\.md/); + assert.doesNotMatch(source, /版本差异|核对应用版本|预发布版/); + assert.match(source, /Android 真机体验[^\n]*