pixif

pixif 是一个基于 PixiJS v8 的轻量 TypeScript 封装，目标是为 Pixi 场景提供更接近 UI/游戏对象的开发模型。

它保留 PixiJS 的渲染能力，同时补充了 GameObject、Group、组件生命周期、布局组件和 DOM 输入组件，适合构建交互式 2D 场景、工具界面和轻量 UI。

English

特性

• 基于 PixiJS v8，支持 Pixi 的 Application、Container、Graphics、Text、纹理等生态。
• 提供 GameObject.instantiate() 创建和挂载对象。
• 使用 Group 作为唯一容器节点，叶子节点不再承担子节点管理职责。
• Application 统一驱动需要更新的对象和组件，避免每个对象直接注册全局 ticker。
• 提供 Layout、GridLayout、FlexGroup 等布局能力。
• 提供 Button、ScrollView、Input、Textarea 等 UI 组件。
• 提供 Rollup 构建、Vitest 测试和 Vite 示例。

安装

pnpm add pixif pixi.js

如果在当前仓库内开发：

pnpm install

快速开始

import {
    Application,
    GameObject,
    Graphics,
    Group,
    Label,
    LabelStyle,
    Layout,
} from 'pixif';

const app = new Application();

await app.init({
    resizeTo: window,
    backgroundColor: 0xf4f0e6,
    antialias: true,
});

document.body.append(app.canvas);

const stage = app.root;

const panel = GameObject.instantiate(Group, stage, {
    width: 360,
    height: 220,
    anchorX: 0.5,
    anchorY: 0.5,
});

panel.addComponent(Layout, {
    centerX: 0,
    centerY: 0,
});

GameObject.instantiate(Graphics, panel)
    .roundRect(0, 0, panel.width, panel.height, 12)
    .fill(0xffffff)
    .stroke({ width: 1, color: 0x2f3437, alpha: 0.18 });

GameObject.instantiate(Label, panel, {
    value: 'Hello pixif',
    x: 24,
    y: 24,
    style: new LabelStyle({
        fill: 0x23272a,
        fontSize: 24,
        fontWeight: '700',
    }),
});

核心概念

Application

Application 继承自 PixiJS Application，初始化后会创建 app.root 作为 pixif 的根 Group。

对象只有挂载到 app.root 这棵树上，并且自身或组件需要 update 时，才会被 app.ticker 驱动。

GameObject

GameObject 是 pixif 的基础对象模型，负责：

• 维护 Pixi display 对象。
• 同步位置、缩放、旋转、透明度等常用属性。
• 管理组件。
• 派发添加、移除、尺寸变化、位置变化、变换变化和 ticker 事件。

推荐通过 GameObject.instantiate() 创建对象：

const group = GameObject.instantiate(Group, app.root, {
    x: 100,
    y: 80,
    width: 200,
    height: 120,
});

Group 和叶子节点

Group 是当前唯一的容器节点，用于挂载子对象。

Graphics、Label、Image、NineSliceImage 等是叶子节点，负责具体渲染，不提供子节点管理能力。

复杂 UI 可以写成 Group 子类，并在 render() 中组装内部子树。GameObject.instantiate() 会先应用传入 props，再调用 render()，因此内部结构可以读取初始化参数：

class UserCard extends Group {
    title = '';
    titleLabel!: Label;

    render() {
        this.titleLabel = GameObject.instantiate(Label, this, {
            value: this.title,
        });
    }
}

const card = GameObject.instantiate(UserCard, stage, {
    title: 'pixif',
    width: 240,
    height: 80,
});

Component

组件可以挂载到 GameObject 上：

import { Component, Group } from 'pixif';

class Spinner extends Component<Group> {
    speed = 0.02;

    update(dt: number) {
        this.gameObject.rotation += this.speed * dt;
    }
}

group.addComponent(Spinner);

组件的 start() 会在首次 update() 前执行一次；update() 会在对象挂载到 Application.root 后由 app.ticker 统一驱动。

布局

Layout

Layout 用于相对父级定位，支持居中、贴边和拉伸：

panel.addComponent(Layout, {
    centerX: 0,
    centerY: 0,
});

child.addComponent(Layout, {
    left: 20,
    right: 20,
    top: 10,
    bottom: 10,
    minWidth: 80,
    minHeight: 40,
});

GridLayout

GridLayout 用于网格排列子节点：

grid.addComponent(GridLayout, {
    col: 3,
    gridWidth: 120,
    gridHeight: 80,
    gapHorizontal: 16,
    gapVertical: 16,
});

FlexGroup

FlexGroup 用于弹性排列子节点，适合横向或纵向列表。

UI 组件

Button

Button 是一个可交互按钮，支持文字、默认图形背景、可选九宫格纹理、禁用状态和按压缩放反馈：

const button = GameObject.instantiate(Button, panel, {
    x: 24,
    y: 150,
    width: 130,
    height: 42,
    value: 'Confirm',
});

button.emitter.on('tap', () => {
    console.log('clicked');
});

按压缩放只作用于按钮内部视觉容器，按钮自身的布局尺寸和命中区域保持不变。

Input / Textarea

Input 和 Textarea 使用真实 HTML 元素承载输入，再把 DOM 元素同步到 Pixi canvas 的位置上。

const input = GameObject.instantiate(Input, form, {
    x: 18,
    y: 88,
    width: 174,
    height: 44,
    fontSize: 16,
});

input.value = 'pixif';

注意：

• 输入组件需要与目标 canvas 对齐，默认使用页面中的第一个 canvas。
• 如页面中存在多个 canvas，可通过 canvas 属性指定。
• DOM 输入组件会跟随自身 transform 变化、Layout 重定位、窗口 resize 和 scroll 来刷新位置。
• 当前实现保留自维护 DOM overlay，没有迁移到 PixiJS v8 experimental DOMContainer。

ScrollView

ScrollView 是一个可滚动容器，内部暴露 content 节点用于挂载内容：

const scroll = GameObject.instantiate(ScrollView, stage, {
    width: 720,
    height: 480,
});

GameObject.instantiate(Label, scroll.content, {
    value: 'Scrollable content',
});

scroll.refreshContentHeight();

支持滚轮和拖拽滚动，并提供 scrollY、maxScrollY、scrollTo()、scrollBy()、refreshContentHeight()。

示例

运行基础示例：

pnpm example

构建基础示例：

pnpm example:build

示例代码位于：

examples/basic/src/main.ts

Codex Skills

pixif 的 npm 包会随包发布项目专用 Codex skill：

skills/pixif-framework

未 clone 仓库时，可直接从 npm 包安装到当前用户的 Codex skills 目录：

npm exec --package pixif -- pixif-skills --replace

如果 pixif 已作为当前项目依赖安装：

pnpm exec pixif-skills --replace

在 pixif 源码仓库内开发时：

pnpm skills:install

默认安装目标是 ${CODEX_HOME:-$HOME/.codex}/skills。如需安装到其他目录：

node scripts/install-skills.mjs --target /path/to/skills --replace

安装后可以在 Codex 中使用 $pixif-framework，用于处理 pixif 的组件、布局、示例、测试和发布入口等项目约定。

开发脚本

pnpm test

运行 Vitest 测试。

pnpm build

使用 Rollup 构建 dist。

pnpm example

启动 Vite 示例。

pnpm skills:install

从源码仓库安装当前维护的 Codex skills。

pnpm example:build

构建示例项目。

包入口

import { Application, GameObject, Group } from 'pixif';
import { Button, Input, ScrollView, Textarea } from 'pixif/ui';
import { Layout, GridLayout } from 'pixif/core';

当前导出入口：

• pixif
• pixif/core
• pixif/ui

许可证

MIT