# @johnmorrisdotca/kazoku-ui 中文文档

规范地址：https://npmcn.com/package/%40johnmorrisdotca/kazoku-ui/

版本：0\.2\.1
npm 元数据更新时间：2026-11-01T12:41:04.848Z
中文译文更新时间：2026-11-01T14:17:45.481Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40johnmorrisdotca/kazoku-ui
原文对照：https://npmcn.com/package/%40johnmorrisdotca/kazoku-ui/?lang=original
项目主页：https://johnmorrisdotca.github.io/kazoku-ui/
源码仓库：https://github.com/johnmorrisdotca/kazoku-ui

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

- 包体积（解压后）：81.8 kB，22 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：0 个
- 首次发布：2026-11-01T12:00:30.954Z
- 最新版本发布：2026-11-01T12:41:04.514Z
- 已发布版本数：4（近 12 个月 4 个）

## 中文简介

家族的共享接口部件作为自己的版本化包。第一部分：任何3D或可缩放视图的视图控件（角度，倾斜，自动旋转，缩放指针，平移，触摸，地址状态）作为无框架自定义元素和pl

## 安装

```sh
npm install @johnmorrisdotca/kazoku-ui
```

也可以使用：`pnpm add @johnmorrisdotca/kazoku-ui`、`yarn add @johnmorrisdotca/kazoku-ui`、`bun add @johnmorrisdotca/kazoku-ui`

## README

# 和风

![The demo: a white card with a blue circle and a black triangle, turned a little and tipped, in a frame with a dotted floor. Under it the view controls: Angle and Tilt sliders, Auto-turn and Front buttons, zoom out, 2 times, zoom in and Fit, four arrows to move the zoomed view, and the Move and Turn choice for a drag.](https://raw.githubusercontent.com/johnmorrisdotca/kazoku-ui/main/docs/images/hero-light.webp)

家族的共享接口部分，作为它们自己的版本化包：每个子路径一个部分，所以一个页面只加载它使用的部分。没有运行时依赖，MIT。 第一部分是 **视图控件** 用于任何3D或可缩放视图。它们从不绘制场景：它们告诉你的页面读者选择了什么，而你的画布，WebGL， SVG或CSS 3D应用它。

[演示](https://johnmorrisdotca.github.io/kazoku-ui/) · [标签，英文和中文](https://npmcn.com/package/%40johnmorrisdotca/kazoku-ui/docs/labels.md) · [更新日志](https://npmcn.com/package/%40johnmorrisdotca/kazoku-ui/CHANGELOG.md)

```sh
npm install @johnmorrisdotca/kazoku-ui
```

部分（每个部分都有自己的子路径；后面的部分：图片贴图选择器，带有明暗的主题色板，英文和中文开关，帮助，GitHub和npm药丸，保存SVG和PNG，家庭背景）：

| 子路径 | 它是什么？ |
| --- | --- |
| `@johnmorrisdotca/kazoku-ui/view-controls` | 控制器，算法，地址和标签。服务器上的导入。 |
| `@johnmorrisdotca/kazoku-ui/view-controls/element` | 这个 `ViewControlsElement` 类（需要浏览器）。 |
| `@johnmorrisdotca/kazoku-ui/view-controls/define` | 寄存器 `<kazoku-view-controls>` （一次，且仅当标签是空闲的时候）。 |

## 视图控件

-   角度和倾斜滑块，自动旋转与播放和暂停，前面。
-   缩小，2倍，放大和适合。缩放是关于指针（Ctrl或Command与滚轮，或触控板的捏）。
-   四个箭头平移键（放大后显示）和移动或转向选项用于拖动。
-   触摸：一根手指旋转1x，放大时移动视图；两根手指捏。
-   键在视图上：箭头转动和倾斜， `+` 和 `-` 变焦, `0` 或者Home is Front and Fit。
-   选项保存在地址中，其中的键可以重命名。
-   英文和日文标签；光明与黑暗；48像素触摸目标；手机上的小型酒吧；对于喜欢减少运动的读者来说，没有自动旋转。
-   **控件永远不会停止或重置回合。** 缩放，倾斜，平移，移动或转向选择，Fit和Front都会使自动旋转运行（Front只将角度设置为0，并且从那里开始旋转）。在角度滑块上的手，或者通过拖动来转动视图，在视图向下时保持转弯不动，并且从手离开的位置继续转弯。只有自动旋转按钮暂停它。

### 在纯HTML中

```html
<div id="scene" tabindex="0" style="height: 320px">...your scene...</div>
<kazoku-view-controls for="scene" address></kazoku-view-controls>

<script type="module">
  import "@johnmorrisdotca/kazoku-ui/view-controls/define";

  const scene = document.getElementById("scene");
  document.querySelector("kazoku-view-controls").addEventListener("kazoku-viewchange", (event) => {
    const { yaw, tilt, zoom, panX, panY } = event.detail;
    scene.style.transform = `translate(${panX}px, ${panY}px) scale(${zoom}) rotateX(${tilt}deg) rotateY(${yaw}deg)`;
  });
</script>
```

将元素放在视图上或它的右边，这样它就和视图一起出现在屏幕上。 `for` 命名手绑定到的元素（指针、缩放、转轮和键）；给它一个机会 `tabindex` 如果你想把键放在上面，根据视图来调整大小，因为平移是在房间里缩放的。与 `overlay` 该工具条位于其父工具条的底部。

### 在框架中

该元素是普通的DOM，因此任何框架都将其与一个ref和一个侦听器一起使用。反应:

```jsx
import "@johnmorrisdotca/kazoku-ui/view-controls/define";
import { useEffect, useRef } from "react";

export function Viewer({ draw }) {
  const view = useRef(null);
  const controls = useRef(null);
  useEffect(() => {
    const bar = controls.current;
    bar.view = view.current;
    const on = (event) => draw(event.detail);
    bar.addEventListener("kazoku-viewchange", on);
    return () => bar.removeEventListener("kazoku-viewchange", on);
  }, [draw]);
  return (
    <>
      <div ref={view} tabIndex={0} style={{ height: 320 }} />
      <kazoku-view-controls ref={controls} lang="en" />
    </>
  );
}
```

### 没有元素

`createViewController` 是相同的手和状态，没有自己的标记，对于绘制自己按钮的页面。它只在 `bind`.

```js
import { createViewController } from "@johnmorrisdotca/kazoku-ui/view-controls";

const view = createViewController({
  speed: 30, // degrees a second for Auto-turn
  onChange(state, { final, reason }) {
    draw(state); // { yaw, tilt, zoom, panX, panY, turning, drag }
  },
});
const unbind = view.bind(document.getElementById("scene")); // pointer, pinch, wheel, keys
myPlayButton.onclick = () => view.toggle();
myZoomIn.onclick = () => view.zoomBy(1.4);
```

选项的 `createViewController` 匹配: `zoom` （`"fit"` 或者一个数字)， `fitScale`， `ignore`． 控制器也有 `ignore` (的), `fitScale`， `startZoom` ( `zoom` 视图在)和处打开 `setFitScale(n)`， `setStartZoom(zoom)`； `DEFAULT_IGNORE` 是默认的选择器。

### 视图中的按钮和链接

手抓住指针上的 `for` 元素，因此按下放置在其中的按钮或链接将被视为拖动，而其点击将丢失。按下任何符合的 `ignore` （没有捕获，没有拖动，没有双击），然后点击就完成了。给其他孩子做标记 `data-kazoku-ignore`． 从视图的空部分拖动使其像以前一样转动。

`ignore` 也可以通过阴影DOM看到：它会测试事件路径上的每个元素，从最里面的那个元素一直到视图，所以即使事件的目标是组件，web组件打开的阴影根中的按钮（比如卡片自己的Animate按钮）也不会受到影响。封闭的影子根将其内部隐藏在页面中，因此只有组件本身可以匹配：将主机标记为 `data-kazoku-ignore`，或将其标记名添加到 `ignore`.

### 以现场的自然大小开场

缩放1表示适合，无论页面大小如何。一页在 `fitScale` （例如，当它适合视图时，它的自然大小为0.4），并希望以自然大小集打开 `zoom="1"` 并告诉控制者刻度：

```js
const controls = document.querySelector("kazoku-view-controls");
controls.setAttribute("zoom", "1"); // natural size
controls.setFitScale(measure()); // the scale the scene is drawn at when it fits, for example 0.4
// the event's zoom is now 2.5; draw at event.detail.zoom * controls.fitScale
```

`setFitScale` 将视图移动到新比例的开始缩放，除非阅读器已经缩放。Fit和Fit键仍然是缩放1，当地址是打开的时候，它会留下一个缩放。 `zoom="fit"`，或者没有 `zoom`，与以前没有任何改变。

## 事件API

`kazoku-viewchange` 在元素上分配（它冒泡并穿过阴影根）。 `event.detail`的第一个参数 `onChange`是:

| 场 | 意义 |
| --- | --- |
| `yaw` | 度，从-180度到180度：垂直方向的转弯。向右拖动会使其变大。 |
| `tilt` | 度，保持正负 `tilt-max` 当它变大时，顶部会向外倾斜（向上拉）。 |
| `zoom` | 1至5 (`zoom-min`， `zoom-max`我很健康。这场面被画得很逼真 `zoom * fitScale` (见下文)。 |
| `panX`， `panY` | CSS像素，缩放后的图片从视图的中间移动；x = 0。 |
| `turning` | 当Auto-turn运行时为True。 |
| `drag` | `"move"` 或者 `"turn"`：普通拖动在放大时的效果。 |
| `final` | 对于拖动、缩放、滑动和自动转弯的步骤为False；当事情解决时是真的。这张昂贵的汇票是什么 `final`，对每个事件进行廉价的变换。 |
| `reason` | 是什么改变了它： `init`， `auto`， `drag`， `pinch`， `wheel`， `key`， `slider`， `zoom`， `pan`， `front`， `fit`， `fit-scale`， `play`， `pause` 或者 `set`. |

一个 `init` 事件在元素连接后立即发送一次，并使用起始视图（来自属性和地址）。 `element.state` 是任何时候的当前视图。

### 属性

| 属性 |  |
| --- | --- |
| `for` | 手绑定到的视图的id。或一组 `element.view = someElement`. |
| `lang` | `en` 或者 `ja`． 否则最近的 `lang` 高于它，否则是英语。 |
| `yaw`， `tilt` | 起始角度和倾斜度。 |
| `zoom` | 起始变焦： `fit` （默认值）或一个数字，其中1是场景的自然大小。打开数除以 `fit-scale`;与 `fit-scale` 左边是1 `zoom` 事件的。 |
| `fit-scale` | 页面在Fit（事件）时绘制场景的比例 `zoom` 1): zoom 1表示什么。默认为1。或打电话 `element.setFitScale(n)` 一旦场景被测量。 |
| `ignore` | 一个CSS选择器，用于在视图内指针按下后留下的内容，因此它的点击经过： `button, a, input, select, textarea, label, [data-kazoku-ignore]` 默认情况下。一个光秃秃的 `ignore=""` 什么都不留下。 |
| `autoplay` | 从一开始就自动转动，除非读者喜欢减少转动。 |
| `speed` | 每秒30度。 |
| `flat` | 视图不能转动：没有角度、倾斜、自动转动或前方，拖拽可以移动它。 |
| `tilt-max`， `zoom-min`， `zoom-max` | 极限（30,1,5）。 |
| `address` | 将选择保留在页面地址(`?yaw=40&tilt=10&zoom=2&drag=turn`）。 |
| `address-keys` | 其他键: `yaw:a,zoom:z`. |
| `theme` | `light` 或者 `dark`;否则页面的配色方案。 |
| `overlay` | 坐在定位父级的底部。 |

方法: `play()`， `pause()`， `front()`， `fit()`， `set({ yaw, tilt, zoom, panX, panY, drag })`， `setFitScale(n)`, `controller` ( `createViewController` 对象)。 `element.words = { front: "Home" }` 替换标签。 颜色是自定义属性： `--kazoku-ink`， `--kazoku-surface`， `--kazoku-line`， `--kazoku-accent`;这些部分是 `bar`， `field`， `slider` 和 `button`.

### 的地址

只保留读者选择的内容：角度、倾斜、缩放和拖动选项。平移是以一个屏幕的像素为单位的，转动是瞬间的，所以两者都不是；当视图自己转动时，角度被忽略了。在其开始处的值(Fit或 `zoom` 页面在)打开时留下地址，其他参数保留。该地址每秒最多写入4次（Safari会在30秒内停止更改地址超过100次的页面）。不含元素的： `parseAddress(search, keys?)` 和 `formatAddress(search, choices, keys?, leaveYaw?, startZoom?)`.

### 为什么标签只有在空闲时才被定义

`customElements.define` 当取一个名称时抛出，并且页面可以毫无错误地满足这个要求：该包的两个副本（每个包一个应用程序和一个小部件，或两个版本），脚本加载两次，或者注册了标记以提供自己的元素的页面。throw会停止导入模块和与之相关的页面脚本。所以 `define` 调用 `customElements.get` 第一种定义获胜； `defineViewControls(registry?)` 返回它是否定义了标记。

## 大小

压缩，未捆绑：元素及其定义约5.0 KB，控制器约3.9 KB，数学约1.4 KB，地址约1.2 KB，标签约0.7 KB，样式约1.6 KB (`pnpm test:package` 打印)。没有从网络中加载任何内容。

## 检查

`pnpm check` （lint，类型，数学的29个单元测试，地址，控制器和包，构建和打包包），以及 `pnpm test:demo` （chrome和WebKit在手机和桌面的宽度上的演示：第一个屏幕上的控件，自动旋转时的切换使角度前进，视图内的按钮或链接在拖动旋转时仍然点击，打开缩放和适合比例，缩放指针，缩放时的平移，触摸，地址，标签，减少运动）。

## 没有

还没有发布到npm。日语标签还没有被母语人士读过。演示的场景是一个CSS 3D卡；这个包对什么画没有意见。

执照:麻省理工学院。此包中没有品牌、联赛或赞助商的标志。

## 常见问题

### @johnmorrisdotca/kazoku-ui 是什么？

家族的共享接口部件作为自己的版本化包。第一部分：任何3D或可缩放视图的视图控件（角度，倾斜，自动旋转，缩放指针，平移，触摸，地址状态）作为无框架自定义元素和pl

### 如何安装 @johnmorrisdotca/kazoku-ui？

在项目目录运行 npm install @johnmorrisdotca/kazoku-ui，或使用 pnpm add / yarn add / bun add。

### @johnmorrisdotca/kazoku-ui 支持 TypeScript 吗？

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

### @johnmorrisdotca/kazoku-ui 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @johnmorrisdotca/kazoku-ui 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @johnmorrisdotca/kazoku-ui 可以商用吗？

@johnmorrisdotca/kazoku-ui 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @johnmorrisdotca/kazoku-ui 还在维护吗？

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