# @anubhav1ks/catalogue-designer 中文文档

规范地址：https://npmcn.com/package/%40anubhav1ks/catalogue-designer/

版本：0\.1\.14
npm 元数据更新时间：2026-11-06T07:47:23.376Z
中文译文更新时间：2026-11-07T04:57:16.888Z
软件包许可：UNLICENSED

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40anubhav1ks/catalogue-designer
原文对照：https://npmcn.com/package/%40anubhav1ks/catalogue-designer/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：8.6 MB，287 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：9 个
- peer 依赖：react ^18\.2\.0，react-dom ^18\.2\.0
- 首次发布：2026-11-04T06:31:49.000Z
- 最新版本发布：2026-11-06T07:47:23.090Z
- 近 30 天下载量：2309（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：15（近 12 个月 15 个）

## 中文简介

基于 HTML 的设计编辑器

## 安装

```sh
npm install @anubhav1ks/catalogue-designer
```

也可以使用：`pnpm add @anubhav1ks/catalogue-designer`、`yarn add @anubhav1ks/catalogue-designer`、`bun add @anubhav1ks/catalogue-designer`

## README

# 目录设计器

建筑目录的反应设计编辑器,以及任何网站上显示这些目录的取景器.

-   **设计编辑器 :** 创建和编辑目录页面.
-   **目录查看器 :** 显示已完成目录,或者作为反应组件,或者使用脚本标记.

编辑器和观看器使用 **单独的许可密钥**。编辑器键只打开编辑器,而取景器键只打开取景器。 缺少或错误的密钥会显示一个错误消息而不是组件 .

## 安装

```bash
npm install @anubhav1ks/catalogue-designer
# or
yarn add @anubhav1ks/catalogue-designer
```

同伴依赖性 : `react` 财务报告和审定财务报表 `react-dom` (18) CKEditor与软件包一起被自动安装.

* * *

## 设计编辑器

```tsx
import DesignEditor, { DesignEditorContext } from '@anubhav1ks/catalogue-designer';
import '@anubhav1ks/catalogue-designer/css/design-editor.css';

export default function App() {
  return (
    <DesignEditorContext.Provider
      value={{
        viewerScriptUrl: 'https://your-site.com/catalogue-viewer.js',
        viewerLicenseKey: 'YOUR-VIEWER-LICENSE-KEY',
      }}
    >
      <div style={{ height: '100vh' }}>
        <DesignEditor
          licenseKey="YOUR-EDITOR-LICENSE-KEY"
          value={design}
          onChange={(next) => save(next)}
        />
      </div>
    </DesignEditorContext.Provider>
  );
}
```

### 编辑道具

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `licenseKey` | `string` | —— 说 | **要求.** 编辑器许可证密钥 . |
| `value` | `IDesign` | —— 说 | 设计开通. |
| `onChange` | `(design: IDesign) => void` | —— 说 | 当设计改变时调用. |
| `storageKey` | `string | false` | —— 说 | 保存到浏览器的密钥 . `false` 关闭储蓄. |
| `height` | `number | string` | `'100%'` | 编辑高度. |
| `minHeight` | `number | string` | `600` | 最小编辑高. |
| `className` | `string` | —— 说 | 额外CSS课. |
| `style` | `CSSProperties` | —— 说 | 额外的内线样式 . |

### 编辑器设置( E)`DesignEditorContext`(中文(简体) )

| 外地 | 类型 | 说明 |
| --- | --- | --- |
| `templates` | `any[]` | 编辑器中显示的模板 . |
| `shapes` | `any[]` | 外形为外形. |
| `viewerScriptUrl` | `string` | URL 时间 `catalogue-viewer.js`打开“在新标签中打开预览” . |
| `viewerLicenseKey` | `string` | 查看器密钥,添加到预览页和嵌入的代码片段. |
| `plan` | `number` | 目前计划水平. |
| `planConfig` | `Partial<PlanConfig>` | 计划以及每个计划的具体内容. |
| `uploadFile` | `(file: File) => Promise<string>` | 上传一个文件并返回其 URL. |

其他出口: `usePlan`, (中文(简体) ), `DEFAULT_PLAN_CONFIG`, (中文(简体) ), `clearSavedDesign`, (中文(简体) ), `designStorageKey`, (中文(简体) ), `parseCatalogueJson`。 。 。 .

* * *

## 目录查看器

从编辑器下载目录 JSON (**预览并嵌入 — 下载目录 JSON**)并传于观者.

观众填充 **集装箱的宽度和高度100%**,因此给予母元素一个高度.

### 反应

```tsx
import { CatalogueViewer } from '@anubhav1ks/catalogue-designer/viewer';

<div style={{ height: 600 }}>
  <CatalogueViewer
    licenseKey="YOUR-VIEWER-LICENSE-KEY"
    design={catalogue}
    type="full"
    inView={true}
  />
</div>;
```

#### 单视图

只显示页面,一次一个,没有工具栏、箭头或缩略图。 访客通过刷取来更改页面,有箭头键,或者在页面上有链接.

```tsx
<div style={{ height: 600 }}>
  <CatalogueViewer
    licenseKey="YOUR-VIEWER-LICENSE-KEY"
    design={catalogue}
    type="single"
    inView={true}
    startPage={0}
  />
</div>
```

#### 动画和录像`inView`(中文(简体) )

-   `inView={true}` 播放页面动画和自动播放视频.
-   `inView={false}` 停止动画并暂停所有视频和音频,包括YouTube嵌入.

使用它来暂停访问者无法看到的目录,例如在旋转木马或滚动列表中:

```tsx
const [visible, setVisible] = useState(false);
const ref = useRef<HTMLDivElement>(null);

useEffect(() => {
  const io = new IntersectionObserver(([entry]) => setVisible(entry.isIntersecting));
  if (ref.current) io.observe(ref.current);
  return () => io.disconnect();
}, []);

<div ref={ref} style={{ height: 500 }}>
  <CatalogueViewer
    licenseKey="YOUR-VIEWER-LICENSE-KEY"
    design={catalogue}
    type="single"
    inView={visible}
  />
</div>;
```

#### 页面跳转链接( E)`onPageJump`(中文(简体) )

默认情况下,页面上的页面跳转链接(下个,上个,上个,上个,上个)会翻转收看者自己的页面. 过 `onPageJump` 比如当你的旋转木马的每张幻灯片 都是自己的取景器时:

```tsx
<CatalogueViewer
  licenseKey="YOUR-VIEWER-LICENSE-KEY"
  design={catalogue}
  type="single"
  startPage={index}
  inView={index === activeSlide}
  onPageJump={(page) => setActiveSlide(page)}
/>
```

`page` 以 0 为基础,并已仅限于目录的页面。 第二个论点是链接的原件 目标:页码,或 `'prev'`, (中文(简体) ), `'next'`, (中文(简体) ), `'first'` 或者说 `'last'`。 。 。 .

### 查看器道具

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `licenseKey` | `string` | —— 说 | **要求.** 查看器许可密钥 . |
| `design` | `IDesign | string` | —— 说 | 目录 JSON,作为对象或字符串. |
| `src` | `string` | —— 说 | 装入目录 JSON 的 URL `design` (未给出). |
| `type` | `'full' | 'single'` | `'full'` | `full` =工具栏,箭头,放出,缩略图. `single` = 仅限页数. |
| `inView` | `boolean` | `true` | `true` 播放动画和视频, `false` 拦住他们. |
| `width` | `number | string` | `'100%'` | 取景器宽度. |
| `height` | `number | string` | `'100%'` | 观者高. |
| `mode` | `'auto' | 'book' | 'single'` | `'auto'` | 页面布局在 `full` 视图. `auto` 在宽屏幕上使用分布. |
| `theme` | `'light' | 'dark'` | `'light'` | 颜色主题 . |
| `startPage` | `number` | `0` | 要打开的页面 (0 = 第1页). |
| `showThumbnails` | `boolean` | `false` | 以缩略图条显示打开( O)`full` 仅限查看). |
| `linkColor` | `string` | —— 说 | 链接热点的颜色 . |
| `flipOnClick` | `boolean` | `false` | 点击一页的左半或右半会翻转一页. |
| `className` | `string` | —— 说 | 额外CSS课. |
| `style` | `CSSProperties` | —— 说 | 额外的内线样式 . |
| `onLoad` | `(design) => void` | —— 说 | 目录装入时调用 . |
| `onError` | `(error) => void` | —— 说 | 目录无法装入时调用. |
| `onPageJump` | `(page, target) => void` | —— 说 | 当点击一个页面跳转链接时调用,并使用基于0的页面去取. 设定时,取景者不会更改页面本身. |

### 脚本标签( 无反应)

添加 `catalogue-viewer.js` (从) `dist/`在你的页面。 每个元素 `data-catalogue-src` 或者说 `data-catalogue` 成为观众.

```html
<div
  data-catalogue-src="/catalogue.json"
  data-license-key="YOUR-VIEWER-LICENSE-KEY"
  data-type="single"
  data-in-view="true"
  style="height: 600px"
></div>
<script src="https://your-site.com/catalogue-viewer.js" defer></script>
```

也可以将JSON放入元素中:

```html
<div data-catalogue data-license-key="YOUR-VIEWER-LICENSE-KEY" data-height="700">
  <script type="application/json">
    { ...catalogue JSON... }
  </script>
</div>
```

| 属性 | 与道具相同 |
| --- | --- |
| `data-license-key` | `licenseKey` |
| `data-catalogue-src` | `src` |
| `data-type` | `type` |
| `data-in-view` | `inView` (单位:千美元)`"false"` 暂停) |
| `data-width` | `width` |
| `data-height` | `height` |
| `data-mode` | `mode` |
| `data-theme` | `theme` |
| `data-start-page` | `startPage` (单位:千美元)**从 1 开始**(中文(简体) ) |
| `data-thumbnails` | `showThumbnails` |
| `data-link-color` | `linkColor` |
| `data-flip-on-click` | `flipOnClick` |

如果元素没有高度,则得到640px.

#### Java 脚本 API

```js
const viewer = window.CatalogueViewer.mount(element, {
  licenseKey: 'YOUR-VIEWER-LICENSE-KEY',
  src: '/catalogue.json',
  type: 'full',
});

viewer.update({ inView: false }); // change any prop later
viewer.unmount();

window.CatalogueViewer.autoMount(); // mount elements added to the page later
```

## 常见问题

### @anubhav1ks/catalogue-designer 是什么？

基于 HTML 的设计编辑器

### 如何安装 @anubhav1ks/catalogue-designer？

在项目目录运行 npm install @anubhav1ks/catalogue-designer，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18\.2\.0）、react-dom（^18\.2\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @anubhav1ks/catalogue-designer 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @anubhav1ks/catalogue-designer 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @anubhav1ks/catalogue-designer 可以商用吗？

@anubhav1ks/catalogue-designer 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

### @anubhav1ks/catalogue-designer 的下载量有多少？

根据 npm 官方下载统计，@anubhav1ks/catalogue-designer 在 2026/10/07 – 2026/11/05 这 30 天内被下载 2,309 次，日均约 77 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @anubhav1ks/catalogue-designer 还在维护吗？

最新版本 0\.1\.14 发布于 2026/11/06（1 天前）；至今共发布 15 个版本，其中过去 12 个月发布了 15 个；首次发布于 2026/11/04。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。