garsoncron/payload-plugin-content-tree
GitHub: garsoncron/payload-plugin-content-tree
为 Payload CMS 提供类 Sitecore 风格的层级内容树管理视图，支持拖拽重构与右键菜单，解决深层级复杂内容的管理与迁移痛点。
Stars: 0 | Forks: 0
# @garsoncron/payload-plugin-content-tree
[](https://www.npmjs.com/package/@garsoncron/payload-plugin-content-tree)
[](https://www.npmjs.com/package/@garsoncron/payload-plugin-content-tree)
[](https://github.com/garsoncron/payload-plugin-content-tree/actions/workflows/ci.yml)
[](https://opensource.org/licenses/MIT)
[](https://bundlephobia.com/package/@garsoncron/payload-plugin-content-tree)
## 为什么会有这个插件
Payload CMS 3.x 将每个集合作为扁平列表进行浏览。这对于文章和产品来说运作良好。但是当你拥有一个页面树——嵌套三到四层的文件夹层次结构、编辑人员需要一眼看出的父子关系，以及决定何种内容类型可以存在于何种父级之下的插入选项时，这种模式就会失效。
从 Sitecore 迁移过来的团队会立刻感受到这一点。Sitecore 内容编辑器将树作为主要的导航界面。编辑人员通过扫描它来定位，通过右键单击来插入，并通过拖动来重构——所有这些都不需要离开树形视图。Payload 开箱即用时并不提供这些功能。
本插件添加了一个即插即用的 `/admin/tree` 视图，该视图基于 [react-arborist](https://github.com/brimdata/react-arborist) 构建，提供了你的编辑人员已经熟悉的 Sitecore 风格用户体验：插入选项、工作流侧边栏、锁定指示器，以及用于在不丢失树上下文的情况下进行编辑的 iframe 侧边轨道。它在今天就能正常运行，同时 Payload 官方的 Tree View RFC (#13982) 仍在开发中，并且它有针对性地解决了即使 Payload 原生树视图发布后也不太可能涵盖的 Sitecore 迁移用例。完整的 v1.0 范围请参见 [`PRD.md §5`](./PRD.md)。
## 安装
```
pnpm add @garsoncron/payload-plugin-content-tree
```
然后在你的 Payload admin 布局中导入一次样式表（通常是 `app/(payload)/layout.tsx`）：
```
import '@garsoncron/payload-plugin-content-tree/styles.css'
```
## 用法
在 `payload.config.ts` 中注册插件，并将其指向定义了所需字段的集合：
```
// payload.config.ts
import { buildConfig } from 'payload'
import { contentTreePlugin } from '@garsoncron/payload-plugin-content-tree'
export default buildConfig({
collections: [Pages],
plugins: [
contentTreePlugin({
collectionSlug: 'pages',
insertOptions: {
root: ['page', 'folder'],
folder: ['page', 'folder'],
page: ['page'],
},
contentTypeLabels: { page: 'Page', folder: 'Folder' },
}),
],
})
```
然后访问 `/admin/tree`。
该插件会在 `buildConfig` 阶段验证你的集合，如果缺少任何必需的字段，将抛出可复制的错误信息。有关包含所有配置选项（`editUrlBuilder`、`canPerformAction`、`features`、`maxDepth` 等）的完整 API 契约，请参见 [`PRD.md §6`](./PRD.md)。
### 必需的集合结构
该插件不会注入字段——你的集合必须定义它们：
| 字段 | 类型 | 必需 |
| --------------- | ----------------------- | -------- |
| `parent` | `relationship` (self) | 是 |
| `sortOrder` | `number` | 是 |
| `contentType` | `select` | 是 |
| `title` | `text` (any text-ish) | 是 |
| `slug` | `text` | 否 |
| `workflowState` | `select` | 否 |
| `lockedBy` | `relationship` to users | 否 |
可以通过 `fields: { parent: 'parentPage', sortOrder: 'order', ... }` 覆盖任何字段名称。
## 功能
- react-arborist 树视图——虚拟化、延迟加载展开状态、每个集合在 localStorage 中持久化
- 带有配置驱动的插入选项的右键上下文菜单（与 Sitecore 插入选项对等）
- 拖放重新排序和重新设置父级，并带有原子性的 parent + sortOrder 写入
- 深度搜索并自动展开至祖先节点
- 侧边栏中可选的 workflow + 锁定指示器（通过 `fields.workflowState` 和 `fields.lockedBy` 选择启用）
- 用于右侧 iframe 目标的 `editUrlBuilder` —— 已准备好集成 Puck
- `canPerformAction` 回调，用于基于角色的操作门控
- 错误时的 Toast 通知
## 示例
- [`./examples/basic`](./examples/basic) —— 可运行的沙盒：Next 15 + SQLite，零额外依赖
- [`./examples/with-puck`](./examples/with-puck) —— 通过 `editUrlBuilder` 集成 Puck 页面构建器
- [`./examples/sitecore-migration`](./examples/sitecore-migration) —— 从 Sitecore XM 迁移至 Payload 的叙述
分步迁移指南另请参见 [`MIGRATING.md`](./MIGRATING.md)。
## 主题
所有可供使用者覆盖的值均作为 `--ct-*` CSS 自定义属性暴露。可以在你自己的 admin CSS 中覆盖它们：
```
:root {
--ct-row-bg-selected: #c7f0d4;
--ct-row-height: 32px;
}
```
或者将覆盖范围限定到自定义的 admin 包装器类：
```
.my-app-admin {
--ct-text: #111827;
--ct-border: #d1d5db;
}
```
回退到 Payload `--theme-elevation-*` 色阶的变量会自动识别你的 Payload 主题——对于 dark-mode（暗黑模式）支持，无需进行额外配置。
**变量分组**（事实来源：`packages/plugin/src/client/styles.css` `:root` 块）：
- **布局** — `--ct-row-height`、`--ct-indent-step`
- **颜色 — 文本** — `--ct-text`、`--ct-text-muted`
- **颜色 — 表面** — `--ct-surface`
- **颜色 — 错误** — `--ct-error`
- **颜色 — 交互状态** — `--ct-bg-hover`、`--ct-bg-selected`、`--ct-row-bg-selected`、`--ct-row-bg-hover`、`--ct-row-bg-highlighted`
- **边框和阴影** — `--ct-border`、`--ct-shadow-card`
- **Z-index 堆叠** — `--ct-z-context-menu`、`--ct-z-modal`、`--ct-z-modal-backdrop`、`--ct-z-toast`
- **动画** — `--ct-anim-fast`、`--ct-anim-base`
- **工具栏** — `--ct-toolbar-height`、`--ct-toolbar-border`、`--ct-search-input-width`
- **DnD** — `--ct-drop-indicator`
## 质量
- 默认渲染时 0 个 axe-core 违规
- 覆盖率门控：服务端辅助函数 ≥80%，客户端 ≥60%
- 打包体积：admin chunk ≤ 80 KB gzip（超出此阈值将在 CI 中直接失败）
- CI 矩阵：Node 20 + 22 × SQLite（包含 Postgres + React 18 / Payload 3.0 组合）
- 严格的 TypeScript，带有 `noUncheckedIndexedAccess`，除了带有记录原因的 disable-islands 之外不使用 `any`
## 状态
## 路线图
v1.0 在 [PRD §5](./PRD.md) 中交付了锁定的范围。可以通过 [GitHub issues](https://github.com/garsoncron/payload-plugin-content-tree/issues) 和 [milestones](https://github.com/garsoncron/payload-plugin-content-tree/milestones) 跟踪正在进行的工作。
## 贡献
开发循环、代码风格和发布流程请参见 [`CONTRIBUTING.md`](./CONTRIBUTING.md)。在提交 issue 或 PR 之前，请阅读 [`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md)。安全漏洞请参见 [`SECURITY.md`](./SECURITY.md) —— 请勿为它们提交公开的 issue。
## 许可证
MIT —— 详见 [`LICENSE`](./LICENSE)。
标签：CMS插件, CMS迁移, MIT许可, NPM包, OSV-Scalibr, Payload CMS, React, react-arborist, Sitecore, Syscalls, TypeScript, UX优化, 内容树, 内容管理, 内容编辑器, 右键菜单, 安全插件, 层级结构, 拖拽排序, 无头CMS, 管理后台, 管理界面, 自动化攻击, 节点层级, 页面树