企业官网建设流程全解析

• 人工智能
• 大模型
• AI Agent
• 提示工程
• AI 评测
• 可观测性
• 后端
• 前端

导读

本文围绕 Coze Loop 开源仓库中frontend/packages/loop-components/components-with-adapter这一前端组件包展开，系统讲解其在 monorepo 中的定位、通过 Rush 工作区安装与引用的方式、对外开放的组件与工具函数 API，并结合源码逐一剖析RouteBackAction返回按钮、handleFormCancel表单离开确认、getRequiredRule必填校验规则等核心实现原理。读完本文，你将掌握如何在 Coze Loop 前端项目中按"基础组件 + 适配层组件"的分层思路组织 UI 代码，并能够直接复用这套组件完成页面返回、表单防误触与校验规则等典型开发任务。

一、包定位：Coze Loop 组件体系中的"带适配器组件"

Coze Loop（下一代 AI Agent 优化平台，覆盖开发、调试、评测与监控全生命周期）的前端采用 Rush 管理的 TypeScript monorepo，组件代码集中在frontend/packages/loop-components目录下，其中既有components-with-adapter这样的"带适配器组件"包，也有biz-components、evaluate-components、observation-components、prompt-components等业务组件包。

components-with-adapter包的package.json声明其名称为@cozeloop/base-with-adapter-components，描述为 "common components with adapter for cozeloop"，即：作为 Coze Loop 通用组件的适配层。它依赖两个关键的工作区包：

• @cozeloop/biz-hooks-adapter（对应 biz-hooks/package.json）：提供模块级路由跳转等业务 hooks；
• @cozeloop/i18n-adapter：提供国际化文本能力；

以及第三方设计体系@coze-arch/coze-design（含Button、Modal等基础组件与图标）。

从源码结构看，可以推断这套"组件 + 适配器"的组织方式是为了让通用组件能够通过 adapter 解耦具体宿主环境的业务上下文（如路由、国际化），从而在不同前端应用之间复用。

二、安装与引入

在 Rush monorepo 中，包之间通过workspace:*协议互相引用。在任一需要用到该组件包的工程（如 frontend/apps/cozeloop/package.json）中声明依赖：

{ "dependencies": { "@cozeloop/base-with-adapter-components": "workspace:*" } }

然后执行：

rush update

rush update会依据rush.json与各子包的package.json重新生成工作区链接（对应 pnpm-lock 与 node_modules 链接），使workspace:*指向仓库内的真实源码目录。

由于包的main与types均直接指向./src/index.ts（见 package.json），TypeScript 工程引用该包时会直接获得类型定义与源码，无需额外构建产物，这在该 monorepo 的组件包中是常见做法。

包的实际对外出口

src/index.ts 是该包唯一的对外出口，实际只导出三样东西：

export { RouteBackAction, type RouteBackActionProps, } from './route/route-back-action'; export { handleFormCancel } from './form/handle-form-cancel'; export { getRequiredRule } from './form/rules';

注意：该包目录下的 README.md 中列出的ColumnSelector、LoopTable、PageLoading等导出项，与@cozeloop/components（即 loop-base/components 包）的 src/index.ts 导出一致，属于文档模板化复用留下的更宽泛组件清单；本包实际提供的 API 以上述三组导出为准。两类包在应用层可以配合使用。

三、API 详解与源码剖析

3.1RouteBackAction：智能返回按钮

功能定位：提供一个带返回箭头图标的按钮，点击后根据页面来源决定是"浏览器回退"还是"跳转到模块默认路由"。

Props 定义（见 route-back-action.tsx）：

核心逻辑getBackRoute（route-back-action.tsx）：

1. 如果跳转时通过location.state?.from标明了来源，则返回-1（浏览器历史回退）；
2. 否则读取window.performance.getEntriesByType('navigation')中导航条目的type：
   • 若为navigate（用户通过地址栏直接输入/刷新进入），判定为新导航，返回defaultModuleRoute；
   • 否则（reload、back_forward等）返回-1走浏览器回退。

交互细节：按钮实际渲染为@coze-arch/coze-design的Button（secondary 配色，固定32x32尺寸），内部是IconCozLongArrowUp图标，通过-rotate-90旋转成"返回"方向的箭头。点击流程为：优先调用onBack，否则用useNavigateModule()（来自@cozeloop/biz-hooks-adapter，其实现基于createUseNavigateModule包装路由信息，见 use-navigate-module.ts）执行回退或模块跳转。

使用示例：

import { RouteBackAction } from '@cozeloop/base-with-adapter-components'; // 在详情页头部放置：有来源则回退，直接进入则回到数据集列表 <RouteBackAction defaultModuleRoute="/datasets" /> // 自定义返回行为 <RouteBackAction defaultModuleRoute="/datasets" onBack={() => { // 自定义关闭抽屉/清理状态等逻辑 }} />

3.2handleFormCancel：表单离开确认

功能定位：在表单"取消/离开"时拦截，避免用户误触导致已填写内容丢失。

签名与行为（见 handle-form-cancel.ts）：

handleFormCancel(changed?: boolean, onCancel?: () => void): void

• changed为true（表单有未保存改动）时，弹出Modal.confirm二次确认框，标题为form_leave_title、内容为form_leave_desc（均通过@cozeloop/i18n-adapter的I18n.t取国际化文案），确认后执行onCancel；
• changed为false（无改动）时直接调用onCancel?.()，不弹窗打扰用户。

典型用法：

import { handleFormCancel } from '@cozeloop/base-with-adapter-components'; // 表格表单场景：isDirty 表示是否有未保存改动 <Button onClick={() => handleFormCancel(isDirty, () => { /* 真正取消并关闭面板 */ })} > 取消 </Button>

3.3getRequiredRule：表单必填校验规则

功能定位：生成一条必填校验规则，错误提示使用国际化文案fornax_base_required_error（见 rules.ts）。

getRequiredRule(): { required?: boolean; message?: string } // 返回 { required: true, message: I18n.t('fornax_base_required_error') }

典型用法（与 antd 风格的表单 rules 兼容）：

import { getRequiredRule } from '@cozeloop/base-with-adapter-components'; const rules = { name: [getRequiredRule()], // 必填，提示语来自 i18n // 可继续追加其他校验规则 };

四、与基础组件包的配合使用

components-with-adapter包本身保持精简（仅 3 组导出），页面级开发常与@cozeloop/components（frontend/packages/loop-base/components）配合：后者提供PageLoading、PageError、PageNoAuth、PageNoContent、PageNotFound等整页状态组件，以及LoopTable、TableWithPagination（含DEFAULT_PAGE_SIZE、PAGE_SIZE_OPTIONS）、ColumnSelector、TableColActions、LoopTabs、LargeTxtRender、InputSlider、handleCopy、sleep等通用能力，均从 src/index.ts 统一导出。

Coze Loop 主应用 frontend/apps/cozeloop/src/routes/base-route.tsx 即是一个真实组合示例：登录状态为settling时渲染<PageLoading />，not_login时<Navigate to={LOGIN_PATH} />，登录成功后才进入GuardProvider包裹的业务路由。这种"状态页组件 + 路由守卫"的模式可以直接借鉴到自己的页面骨架中。

五、开发与质量工具链

该包开发环境统一由以下工具支撑（见 package.json 的 scripts 与 devDependencies）：

• TypeScript+ React 18.2：组件与 hooks 均以 TSX 编写，@types/react18.2 提供类型；
• Vitest ~3.0.5+happy-dom：测试运行环境（仓库内vitest.config.mts已配置），@vitest/coverage-v8用于覆盖率；
• ESLint（@coze-arch/eslint-config）：npm run lint执行eslint ./ --cache；
• Tailwind CSS（@cozeloop/tailwind-config）：组件类名大量使用 Tailwind 原子类，如!w-[32px] !h-[32px]、-rotate-90等；
• Rush 工程配置：config/rush-project.json声明ts-check操作输出到./dist。

常用命令：

# 在包目录内执行 rushx lint # 代码规范检查 rushx test # 运行测试（当前包脚本为 exit 0 占位，可结合 vitest 运行） rushx build # 构建（当前脚本为 exit 0 占位，包以源码直引为主）

六、小结

@cozeloop/base-with-adapter-components是 Coze Loop 前端 monorepo 中一个典型的"薄适配层"组件包：它只沉淀与业务环境（路由、国际化）相关的三个通用能力——智能返回按钮RouteBackAction、表单离开确认handleFormCancel、必填校验规则getRequiredRule，其余纯 UI 组件交由@cozeloop/components承载。理解这种拆分思路，并掌握workspace:*+rush update的接入流程，是后续在 Coze Loop 前端工程中高效复用餐具、保持代码分层清晰的关键。

该包遵循 Apache-2.0 开源协议，源码与完整导出清单可分别查看 src/index.ts 与 README.md。

• 人工智能
• 大模型
• AI Agent
• 提示工程
• AI 评测
• 可观测性
• 后端
• 前端