col-picker添加搜索功能、添加下拉刷新上拉加载功能 by Xiabaiyou · Pull Request #1417 · Moonofweisheng/wot-design-uni

Xiabaiyou · 2025-12-28T14:45:37Z

🤔 这个 PR 的性质是？(至少选择一个)

🔗 相关 Issue

💡 需求背景和解决方案

☑️ 请求合并前的自查清单

⚠️ 请自检并全部勾选全部选项。⚠️

文档已补充或无须补充
代码演示已提供或无须提供
TypeScript 定义已补充或无须补充

Summary by CodeRabbit

新功能
- 新增可配置的 Tour 引导组件与演示页；新增拖拽排序（DragSort）组件与演示页；为列选择器（ColPicker）添加本地/远程搜索、下拉刷新与上拉加载，并暴露停止刷新接口。
文档
- 添加 Tour 与 DragSort 组件完整文档；扩展 ColPicker 文档，包含搜索、刷新、加载更多示例与 API 说明。
本地化
- 补充多语言文案（Tour、DragSort、ColPicker 等新提示与标题）。
样式
- 优化 Tour、ColPicker 与 DragSort 的样式与空状态展示，支持主题适配。
测试
- 新增并更新 Tour 与 ColPicker 的单元测试，覆盖交互与错误场景。

在 global.d.ts 文件中添加 WdGuide 组件的类型声明，确保 TypeScript 项目中可以正确识别该组件。添加引导组件主逻辑

- 将 offset、borderRadius、padding、bottomSafetyOffset 和 topSafetyOffset 的类型从数组修改为 Number - 这种更改提高了类型定义的准确性和一致性，确保了更好的类型检查和代码质量

- 将 border-radius、padding、bottom-safety-offset 和 top-safety-offset 属性的类型从 string / number 修改为 number - 优化文档中属性类型的准确性，提高开发者体验

- 修改 highlightStyle 和 popoverStyle 计算属性，优化样式对象的创建方式 - 移除多余的空行和注释，提高代码整洁度 - 调整 updateElementInfo、getEffectiveBoundaries、checkScrollNeeds 等函数的结构，提升可读性 - 优化 scrollUp 和 scrollDown 函数中的变量赋值和注释

- 丰富了自定义功能，包括引导内容、高亮区域、按钮等 - 优化了引导步骤的控制逻辑，支持双向绑定当前步骤 - 调整了高亮区域和引导内容的样式，提升了用户体验 - 增加了组件的响应式处理，适应不同平台和屏幕尺寸 - 优化了代码结构，提高了组件的可维护性和可测试性

- 将 manifest.json 中的 appid 从 "wxf81518e7b11ea8d8" 更改为 "wx18107b71aa1672e2"

- 添加了向导组件的单元测试文件 - 实现了对向导组件各项功能的测试，包括基本渲染、隐藏状态、步骤内容渲染、按钮显示和功能、自定义文本和样式、事件触发等 - 模拟了 uni 对象和元素查询，以适应uni-app环境 wd-guide 去除多余的打印修复menuButtonInfo的ts报错

- 移除了多处 console.log 调试日志，清理无用输出 - 为 menuButtonInfo 添加了更精确的类型定义 - 删除了未使用的计算属性 watch

- 提取公共的默认样式函数 getDefaultStyle - 提取公共的高亮样式计算函数 calculateHighlightStyle - 使用 computed 属性优化高亮样式和元素信息的计算 - 简化代码结构，提高可维护性和可读性

- 优化了引导组件的滚动逻辑，确保滚动到顶部后再显示引导步骤 - 添加了系统信息更新功能，提高元素定位的准确性 - 修复了某些场景下引导步骤显示异常的问题 - 优化了代码结构，提高了组件的可维护性 - 修复重复调用导致位置计算偏差问题

- 将 controlCurrent.value 的初始值从 6 修改为 2 - 优化了控制指南的起始步骤，提高了用户体验

- 将 guide 组件重命名为 tour 组件 - 更新了相关文件和代码中的 guide 引用，改为 tour - 调整了部分样式和命名以适应新的组件名称

- 移除旧的引导组件代码和文档 - 更新类型定义，使用通用的类型构造函数 - 优化组件属性定义，使用统一的类型创建方法 - 删除冗余的属性类型和默认值定义

- 将 guide-show 动画名称改为 tour-show，统一动画命名风格 - 此更改不影响功能，仅用于提升代码一致性和可维护性

- 新增中英文文档侧边栏目录 - 修改演示组件入口位置，确保导航一致性

- 调整标题结构，将“介绍”合并为描述文字，“基本用法”更名为“基本使用” - 统一代码块语言标识为 html，并更新 v-model 为 :model-value 以符合 Vue 3 写法 - 补充插槽、属性和方法的说明，优化自定义内容与样式的描述 - 规范化 props 类型标注，统一数值类属性类型为 number - 更新事件参数格式，移除冗余字段说明 - 更新本地化标题文本，保持中英文一致

- 在 H5 环境中使用 useLockScroll 返回的 lock 和 unlock 方法以正确控制滚动锁定 - 为 popoverStyle 增加更精确的 TypeScript 类型定义，提升代码可维护性 - 新增对 useLockScroll 的 mock 实现，完善组件单元测试覆盖

该提交移除了 `src/subPages/tour/index.vue` 文件中的所有内容，包括模板、脚本和样式部分。这可能是因为该页面不再需要，或其功能已被迁移至其他位置。

vercel · 2025-12-28T14:45:41Z

@Xiabaiyou is attempting to deploy a commit to the weisheng's projects Team on Vercel.

A member of the Team first needs to authorize it.

coderabbitai · 2025-12-28T14:45:56Z

Walkthrough

新增完整 Tour（漫游）功能与 DragSort（拖拽排序）示例组件及其样式、类型、全局声明、文档、测试、多语言项与页面注册；同时为 ColPicker 增加本地/远程搜索、下拉刷新与上拉加载能力并扩展多语言条目与演示页，包含若干样式与配置性调整。

Changes

Cohort / File(s)	Summary
文档本地化 & 导航 `docs/.vitepress/locales/en-US.ts`, `docs/.vitepress/locales/zh-CN.ts`, `src/locale/en-US.json`, `src/locale/zh-CN.json`	新增/更新侧边栏导航项（Tour）与多语言键（如 `tour-title`, `dragSort` 等），仅文档/本地化更改。
页面注册与首页入口 `src/pages.json`, `src/pages/index/Index.vue`, `src/subPages/tour/Index.vue`	注册并添加 `tour` 页面与首页索引项；新增演示页 `src/subPages/tour/Index.vue`（多个示例与触发逻辑）。
WdTour 组件（实现、样式、类型、全局声明） `src/uni_modules/wot-design-uni/components/wd-tour/wd-tour.vue`, `.../wd-tour/types.ts`, `.../wd-tour/index.scss`, `src/uni_modules/wot-design-uni/global.d.ts`, `tests/components/wd-tour.test.ts`	新增 WdTour 组件：props/types、位置计算、滚动调整、mask/highlight/popover、事件与方法暴露、暗色主题样式、全局类型声明与单元测试。
DragSort 组件族（实现、类型、样式、示例页） `src/uni_modules/wot-design-uni/components/wd-drag-sort/...`, `src/uni_modules/wot-design-uni/components/wd-drag-sort-item/...`, `src/uni_modules/wot-design-uni/components/wd-drag-handle/...`, `src/subPages/dragSort/Index.vue`	新增 wd-drag-sort 及其子组件（item、handle）、类型、utils、样式与演示页，包含拖拽逻辑、auto-scroll、布局计算与多个示例。
ColPicker 功能扩展（搜索/刷新/上拉） `src/uni_modules/wot-design-uni/components/wd-col-picker/wd-col-picker.vue`, `.../types.ts`, `.../index.scss`, `src/subPages/colPicker/Index.vue`, `docs/component/col-picker.md`, `tests/components/wd-col-picker.test.ts`	为 ColPicker 添加 filterable/filter-type 等 props、远程/本地搜索事件、refresh/scroll-to-lower 事件与 stopRefresh 暴露、样式与示例页面与文档更新，测试微调。
多语言扩展（colPicker.search） `src/uni_modules/wot-design-uni/locale/lang/*` (多语言文件), `src/locale/en-US.json`, `src/locale/zh-CN.json`	在众多 locale 文件中为 colPicker 加入 `search` 字段，并新增若干翻译键（如 `dragSort`, `tour-title` 等）。
其它元数据/格式与小改动 `src/manifest.json`, `.hbuilderx/launch.json`, 其他样式微调文件	格式/元数据微调、新增 IDE launch 配置文件与若干 SCSS 样式调整，无业务逻辑变更。

Sequence Diagram(s)

sequenceDiagram
    autonumber
    participant Page as 页面/父组件
    participant Tour as WdTour 组件
    participant DOM as 目标 DOM 元素
    participant Sys as 系统信息

    Page->>Tour: 设置 modelValue = true（显示）
    activate Tour

    Tour->>DOM: querySelector / getBoundingClientRect
    DOM-->>Tour: 返回 boundingRect

    Tour->>Sys: 请求 windowHeight / 状态栏高度
    Sys-->>Tour: 返回系统信息

    Note over Tour: 计算高亮区域与 popover 位置，决定向上或向下展示

    alt 目标不可见
        Tour->>Page: 请求 scrollTo / 调整页面滚动使目标可见
    end

    loop 用户遍历步骤
        Page->>Tour: 触发 next/prev/skip/finish
        Tour->>Tour: 更新 currentIndex；emit change/next/prev/skip/finish
        Tour->>DOM: 重新查询目标元素位置
        DOM-->>Tour: boundingRect
    end

    Page->>Tour: 设置 modelValue = false（隐藏）
    deactivate Tour

Estimated code review effort

🎯 4 (复杂) | ⏱️ ~60 分钟

Possibly related PRs

refactor: ♻️ 重构 Tour 漫游组件 #1399: 与本 PR 在 Tour 组件实现、样式、types 与测试方面高度重叠。
添加 WdGuide 组件的 #1237: 另一个与 Tour 功能实现密切相关的 PR（组件、types、文档层面）。
feat: ✨ 为 Cell、Input、Textarea 等组件添加 marker-side 属性控制必填*位置 #1181: 与 ColPicker 的搜索/刷新/加载扩展在代码层面有交集（types 与实现变更）。

Suggested reviewers

Moonofweisheng
810505339

Poem

🐰 漫游新迹映朝光，
光圈引路步步扬，
插槽随心铺彩章，
小兔挥耳唱一腔，
旅途有你更辉煌 ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	PR标题准确反映了主要变更内容，即为col-picker组件添加搜索功能和下拉刷新上拉加载功能，与代码变更高度对应。
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

📝 Generate docstrings

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

netlify · 2025-12-28T14:45:58Z

✅ Deploy Preview for wot-design-uni ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`9e9537d`
🔍 Latest deploy log	https://app.netlify.com/projects/wot-design-uni/deploys/69820a01528fad0008ce2822
😎 Deploy Preview	https://deploy-preview-1417--wot-design-uni.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

coderabbitai

Actionable comments posted: 5

🧹 Nitpick comments (9)

src/manifest.json (1)

49-51: compatible.ignoreVersion 调整为单独块，不影响运行

这里只是在 app-plus 下显式补了一段 "compatible": { "ignoreVersion": true } 配置（或仅调整空格/缩进），对实际行为基本无影响。需要注意的是，manifest.json 中广泛使用注释，像 Biome 这类按严格 JSON 解析的工具会报错，建议在工具配置里将该文件视为 JSONC/排除检查，以免产生噪音告警。

src/pages.json (1)

1329-1344: 新增 tour/Index 子页面配置与现有模式一致

路径 tour/Index、name: "tour"、MP 与非 MP 下的 navigationBarTitleText 配置方式都与其它示例子页一致，其中非 MP 使用 %tour-title%，已经在中英文 locale 中定义，可以正确本地化。

MP 端直接使用中文 "Tour 页面引导" 也符合当前文件其它条目的写法。

需要注意的是，本文件包含大量注释和 // #ifdef MP 这类条件编译指令，属于 uni-app 特有的“扩展 JSON”语法，对 Biome 这类严格 JSON 解析器会触发 parse 报错。建议在工具配置里将 pages.json 视为 JSONC 或从通用 JSON 规则中排除，以免产生无效告警。

src/uni_modules/wot-design-uni/components/wd-tour/types.ts (1)

80-98: 考虑按钮文本的国际化支持

默认按钮文本使用了中文硬编码（"上一步"、"下一步"、"跳过"、"完成"）。如果项目需要支持多语言，建议考虑使用 i18n 机制或从 locale 配置中读取默认值。
src/subPages/tour/Index.vue (1)
182-182: 未使用的 watch 导入

watch 从 Vue 导入但未在组件中使用，建议移除以保持代码整洁。
🔎 建议修复
-import { ref, watch, nextTick } from 'vue'
+import { ref, nextTick } from 'vue'
tests/components/wd-tour.test.ts (3)
59-81: Mock 设置重复

beforeEach 中的 mock 实现与初始定义（第 14-40 行）重复。建议只在 beforeEach 中使用 mockClear() 重置状态，而不是重新定义整个实现。
🔎 建议简化
 beforeEach(() => {
   vi.clearAllMocks()
-  // 重置模拟函数
-  mockUni.createSelectorQuery.mockClear()
-  mockUni.createSelectorQuery.mockImplementation(() => ({
-    select: vi.fn(() => ({
-      boundingClientRect: vi.fn((callback) => {
-        // 模拟元素位置信息
-        setTimeout(() => {
-          callback({
-            top: 100,
-            left: 50,
-            width: 200,
-            height: 100
-          })
-        }, 10)
-        return {
-          exec: vi.fn()
-        }
-      })
-    }))
-  }))
+  // vi.clearAllMocks() 已经重置了所有 mock 状态
 })
如果需要在特定测试中修改 mock 行为，可以在该测试内部单独设置。
175-175: 移除占位符注释

// ... existing code ... 看起来是开发过程中的占位符，应该移除。
🔎 建议修复
-  // ... existing code ...
-
   // 测试自定义按钮文字
121-129: 考虑使用更可靠的异步等待方式

测试中多处使用 await new Promise((resolve) => setTimeout(resolve, 100)) 等待异步操作完成，这种方式可能导致测试不稳定。建议考虑使用 @vue/test-utils 的 flushPromises 或轮询等待特定条件。
src/uni_modules/wot-design-uni/components/wd-tour/wd-tour.vue (2)
267-267: 缺少类型注解

scrollNeeds 参数缺少类型注解，建议添加以提高代码可读性和类型安全。
🔎 建议修复
-function handleScrolling(res: ElementRect, scrollNeeds, boundaries: { top: number; bottom: number }) {
+function handleScrolling(res: ElementRect, scrollNeeds: { up: boolean; down: boolean }, boundaries: { top: number; bottom: number }) {
190-190: 空函数可添加注释说明用途

noop 函数用于阻止 touchmove 事件的默认行为，但函数名和空实现可能让其他开发者困惑。建议添加简短注释说明用途。
🔎 建议修复
+// 空函数，用于阻止 touchmove 事件冒泡和默认行为
 function noop() {}

📜 Review details

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 1d7572d and 3e76200.

📒 Files selected for processing (14)

docs/.vitepress/locales/en-US.ts
docs/.vitepress/locales/zh-CN.ts
docs/component/tour.md
src/locale/en-US.json
src/locale/zh-CN.json
src/manifest.json
src/pages.json
src/pages/index/Index.vue
src/subPages/tour/Index.vue
src/uni_modules/wot-design-uni/components/wd-tour/index.scss
src/uni_modules/wot-design-uni/components/wd-tour/types.ts
src/uni_modules/wot-design-uni/components/wd-tour/wd-tour.vue
src/uni_modules/wot-design-uni/global.d.ts
tests/components/wd-tour.test.ts

🧰 Additional context used

🧠 Learnings (4)

📚 Learning: 2024-11-24T06:12:44.418Z

Learnt from: Moonofweisheng
Repo: Moonofweisheng/wot-design-uni PR: 733
File: src/uni_modules/wot-design-uni/components/wd-tabs/wd-tabs.vue:327-327
Timestamp: 2024-11-24T06:12:44.418Z
Learning: 在 `src/uni_modules/wot-design-uni/components/wd-tabs/wd-tabs.vue` 中，由于 `title` 可能会发生变化，涉及到 `title` 的优化不太容易实现，需谨慎处理。

Applied to files:

docs/component/tour.md
src/uni_modules/wot-design-uni/components/wd-tour/wd-tour.vue
tests/components/wd-tour.test.ts
src/subPages/tour/Index.vue

📚 Learning: 2024-11-26T02:35:53.123Z

Learnt from: Moonofweisheng
Repo: Moonofweisheng/wot-design-uni PR: 737
File: src/uni_modules/wot-design-uni/components/wd-divider/wd-divider.vue:25-25
Timestamp: 2024-11-26T02:35:53.123Z
Learning: 在 `wd-divider.vue` 文件（路径：`src/uni_modules/wot-design-uni/components/wd-divider/wd-divider.vue`）中，`props.customStyle` 是字符串类型，用于传递自定义的样式字符串。

Applied to files:

src/uni_modules/wot-design-uni/components/wd-tour/wd-tour.vue

📚 Learning: 2024-12-05T15:55:35.371Z

Learnt from: Moonofweisheng
Repo: Moonofweisheng/wot-design-uni PR: 761
File: src/uni_modules/wot-design-uni/components/wd-message-box/wd-message-box.vue:166-182
Timestamp: 2024-12-05T15:55:35.371Z
Learning: 在文件 `wd-message-box.vue` 的 `toggleModal` 方法中，当 `isPass` 为 `false` 时，应阻止执行 `confirm`，但不触发 `cancel` 操作。

Applied to files:

src/uni_modules/wot-design-uni/components/wd-tour/wd-tour.vue
tests/components/wd-tour.test.ts

📚 Learning: 2024-11-30T06:44:18.181Z

Learnt from: Moonofweisheng
Repo: Moonofweisheng/wot-design-uni PR: 748
File: src/uni_modules/wot-design-uni/components/wd-progress/wd-progress.vue:87-128
Timestamp: 2024-11-30T06:44:18.181Z
Learning: 在 `src/uni_modules/wot-design-uni/components/wd-progress/wd-progress.vue` 文件中，当 `percentage` 为 0 时，应通过 `update` 函数处理 `percentage` 为 0 的情况，而不需要在 `updateProgress` 函数中进行特殊处理。

Applied to files:

tests/components/wd-tour.test.ts

🪛 Biome (2.1.2)

src/pages.json

[error] 1331-1332: End of file expected