qiling-web-virtual-list 0.0.0-stage → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 炼器师
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,33 @@
-# Temporary Holding Version
+# qiling-web-virtual-list
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+QiLing Web 虚拟列表拓展包。只渲染可视区与缓冲区的虚拟滚动列表。
+
+## 安装
+
+```bash
+npm install qiling-web qiling-web-virtual-list
+# 或
+bun add qiling-web qiling-web-virtual-list
+```
+
+> `qiling-web-virtual-list` 通过 peer dependency 使用 `qiling-web`，请同时安装核心包。
+
+## 使用
+
+```js
+import 'qiling-web'
+import 'qiling-web-virtual-list'
+
+// 导入即注册：ql-virtual-list
+```
+
+组件标签：`ql-virtual-list`。
+
+## 文档
+
+- [QiLing Web 文档](http://47.93.3.131:18105/docs/)
+- [源码仓库](https://gitee.com/i-o-i/qiling-web)
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,26 @@
+import{Registry as p}from"qiling-web/internal";import{Ql as r}from"qiling-web";import{QlElement as c}from"qiling-web";class n extends c{constructor(){super(...arguments);this.state={items:r.signal([]),scrollTop:r.signal(0),viewportHeight:r.signal(0),version:r.signal(0),visible:r.computed(()=>{this.state.version.value;let t=this.state.items.value,i=this.actions.itemHeight(),e=this.actions.buffer(),s=this.state.scrollTop.value,a=this.state.viewportHeight.value,h=Math.max(0,Math.floor(s/i)-e),u=Math.min(t.length,Math.ceil((s+a)/i)+e),l=[];for(let o=h;o<u;o+=1)l.push({item:t[o],index:o});return l})};this.#i=null;this.#t=null;this.#e=!1;this.layout={type:"div",ref:"viewport",props:{class:"viewport"},on:{scroll:()=>this.actions.scrolled()},children:[{type:"div",slot:"spacer",props:{class:"spacer"}},{type:"div",slot:"window",props:{class:"window"}}]};this.actions={itemHeight(){return Math.max(1,Number(this.getProp("itemHeight"))||32)},buffer(){return Math.max(0,Number(this.getProp("buffer"))||0)},totalHeight(){return this.state.items.value.length*this.actions.itemHeight()},offset(){return Math.max(0,Math.floor(this.state.scrollTop.value/this.actions.itemHeight())-this.actions.buffer())*this.actions.itemHeight()},scrolled(){let t=this.ref("viewport");if(!t)return;this.state.scrollTop.value=t.scrollTop,this.actions.checkReachEnd()},checkReachEnd(){let t=this.ref("viewport");if(!t)return;let i=Math.max(0,Number(this.getProp("reachEndOffset"))||0),e=t.scrollTop+t.clientHeight>=t.scrollHeight-i;if(e&&!this.#e)this.#e=!0,this.emit("ql-reach-end");else if(!e)this.#e=!1},measure(){let t=this.ref("viewport");if(!t)return;if(this.state.viewportHeight.value=t.clientHeight,t.scrollHeight>t.clientHeight)t.setAttribute("tabindex","0");else t.removeAttribute("tabindex");this.actions.checkReachEnd()}}}static tag="ql-virtual-list";static props={itemHeight:{type:"number",default:32,description:"每项高度（px，定高虚拟滚动）"},buffer:{type:"number",default:4,description:"可视区上下各多渲染几项（滚动缓冲）"},height:{type:"length",default:"",description:"容器高度（缺省由外部约束）"},reachEndOffset:{type:"number",default:64,description:"距底部多少像素算「接近底部」（0 表示必须滚到底）"}};static emits={"ql-reach-end":{desc:"滚动接近底部时触发（用于触底加载）"}};static cssVars={height:"--ql-virtual-height",itemHeight:"--ql-virtual-item-height"};static styles=`
+    :host { display: block; }
+    .viewport {
+      position: relative;
+      box-sizing: border-box;
+      /* 视口必须有**固定高度** —— 虚拟化的前提（高度不定就等于全渲染） */
+      height: var(--ql-virtual-height, 240px);
+      overflow-y: auto;
+      overscroll-behavior: contain;
+      outline: none;
+    }
+    /* 键盘可达时才可聚焦（内容溢出时由 measure() 加 tabindex，规范 §4.4⑤） */
+    .viewport:focus-visible { box-shadow: inset 0 0 0 2px var(--ql-color-primary); }
+    /* 只负责撑出滚动条长度，不参与布局 */
+    .spacer { width: 1px; pointer-events: none; }
+    /* 窗口随滚动位移；里面只放可视区 + 缓冲的那些项 */
+    .window {
+      position: absolute;
+      top: 0;
+      left: 0;
+      right: 0;
+      will-change: transform;
+    }
+    /* 每项按 itemHeight 定高 —— 与虚拟化假设一致，避免内容把行高撑歪 */
+    .window > * { box-sizing: border-box; height: var(--ql-virtual-item-height, 32px); }
+  `;#i;#t;#e;set items(t){this.state.items.value=Array.isArray(t)?t:[],this.#e=!1}get items(){return this.state.items.value}set renderItem(t){this.#i=typeof t==="function"?t:null,this.state.version.value+=1}get renderItem(){return this.#i}render(t){t.spacer?.bind("style",()=>`height:${this.actions.totalHeight()}px`),t.window?.bind("style",()=>`transform:translateY(${this.actions.offset()}px)`),t.window?.add((i)=>{i.each(()=>this.state.visible.value,(e,s)=>{this.#i?.(e.item,e.index,s)},(e)=>e.index)})}onMounted(){if(this.actions.measure(),typeof ResizeObserver<"u"){this.#t=new ResizeObserver(()=>this.actions.measure()),this.#t.observe(this);let t=this.ref("viewport");if(t)this.#t.observe(t)}}onUnmounted(){this.#t?.disconnect(),this.#t=null}}p.define(n);export{n as QlVirtualList};

package/dist/types/index.d.ts

@@ -0,0 +1,3 @@
+import { QlVirtualList } from './ql-virtual-list';
+export { QlVirtualList };
+export type { VirtualEntry, VirtualItemRenderer } from './types';

package/dist/types/ql-virtual-list.d.ts

@@ -0,0 +1,81 @@
+import { Ql } from 'qiling-web';
+import type { GroupMethod } from 'qiling-web';
+import { QlElement } from 'qiling-web';
+import type { CssVarMap } from 'qiling-web';
+import type { PropSchema } from 'qiling-web';
+import type { VirtualEntry, VirtualItemRenderer } from './types';
+/**
+ * 虚拟滚动列表：**只渲染可视区 + 缓冲**，滚动时复用 DOM。
+ *
+ * 用于「上万条也要流畅」的场景（日志、大表格、长选项列表）。
+ *
+ * 用法（两处注入，都保持声明式）：
+ * ```js
+ * const list = document.querySelector('ql-virtual-list')
+ * list.items = rows                       // 数据注入（数组不能用 prop 表达）
+ * list.renderItem = (row, index, view) => {   // 逐项渲染
+ *   view.add('ql-text').text(row.name)
+ * }
+ * ```
+ *
+ * 事件：`ql-reach-end`（滚动接近底部，用于触底加载）。
+ */
+export declare class QlVirtualList extends QlElement {
+    #private;
+    static tag: string;
+    static props: PropSchema;
+    static emits: {
+        'ql-reach-end': {
+            desc: string;
+        };
+    };
+    static cssVars: CssVarMap;
+    static styles: string;
+    /**
+     * 2. 状态：滚动位置与可视高度是**窗口计算的输入**，必须响应式。
+     *
+     * 这也是组件侧第一次用到 `state` —— 其余 63 个组件都靠 `props` 驱动，
+     * 不需要内部可变状态。
+     */
+    state: {
+        /** 数据源 */
+        items: import("@preact/signals-core").Signal<unknown[]>;
+        /** 滚动位置 */
+        scrollTop: import("@preact/signals-core").Signal<number>;
+        /** 容器可视高度（尺寸变化时由 ResizeObserver 更新） */
+        viewportHeight: import("@preact/signals-core").Signal<number>;
+        /** 渲染回调的版本号 —— 换回调时靠它触发窗口重算 */
+        version: import("@preact/signals-core").Signal<number>;
+        /** 可视区（含缓冲）的项 */
+        visible: import("@preact/signals-core").ReadonlySignal<VirtualEntry[]>;
+    };
+    /** 数据注入（数组无法用 prop 表达）—— 规范 §4.1 的「数据注入契约」 */
+    set items(value: unknown[] | null);
+    get items(): unknown[];
+    /** 逐项渲染回调（注入） */
+    set renderItem(fn: VirtualItemRenderer | null);
+    get renderItem(): VirtualItemRenderer | null;
+    /** 骨架：滚动视口（内含撑高垫层与位移窗口）；会增减的项在 `render(area)` 里装 */
+    layout: {
+        type: string;
+        ref: string;
+        props: {
+            class: string;
+        };
+        on: {
+            scroll: () => any;
+        };
+        children: {
+            type: string;
+            slot: string;
+            props: {
+                class: string;
+            };
+        }[];
+    };
+    protected render(area: Record<string, Ql>): void;
+    /** 3. 操作：业务动作。**不挂 `Ql.desc()` 即内部方法**，不对外暴露 */
+    actions: Record<string, GroupMethod>;
+    protected onMounted(): void;
+    protected onUnmounted(): void;
+}

package/dist/types/types.d.ts

@@ -0,0 +1,8 @@
+import type { Ql } from 'qiling-web';
+/** 窗口里的一项（带它在整个列表里的下标） */
+export interface VirtualEntry {
+    item: unknown;
+    index: number;
+}
+/** 逐项渲染回调 */
+export type VirtualItemRenderer = (item: unknown, index: number, row: Ql) => void;

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "qiling-web-virtual-list",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.2",
+  "description": "QiLing UI 拓展组件：虚拟滚动列表",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "sideEffects": [
+    "./dist/index.js"
+  ],
+  "peerDependencies": {
+    "qiling-web": "^0.1.2"
+  },
+  "devDependencies": {
+    "qiling-web": "workspace:*"
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "bun run clean && bun run build:ui && bun run build:types",
+    "build:ui": "bun build src/index.ts --outdir=dist --target=browser --format=esm --minify --splitting --entry-naming=index.js --chunk-naming=chunk-[hash].js --min-chunk-size=16384 --external qiling-web --external qiling-web/internal",
+    "build:types": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "prepublishOnly": "bun run build && bun run typecheck"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitee.com/i-o-i/qiling-web.git",
+    "directory": "packages/qiling-web-virtual-list"
+  },
+  "homepage": "http://47.93.3.131:18105/docs/",
+  "bugs": {
+    "url": "https://gitee.com/i-o-i/qiling-web/issues"
+  },
+  "keywords": [
+    "qiling",
+    "qiling-web",
+    "web-components",
+    "ui",
+    "framework"
+  ],
+  "author": {
+    "name": "炼器师"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}