@shijiu/jsview-vue-samples 2.3.0 → 2.3.728-alpha.0

package/MetroWidgetDemos/gazeFocusDiff/Item.vue

@@ -0,0 +1,87 @@
+<script setup>
+import { computed, ref } from "vue";
+
+const props = defineProps({
+  data: {
+    type: Object,
+    required: true,
+  },
+  onAction: {
+    type: Object,
+    required: true,
+  },
+  widgetTag: {
+    type: String,
+    default: "",
+  },
+});
+
+const gazed = ref(false);
+const focused = ref(false);
+
+/**
+ * 这份样例的可视化策略：
+ * - gazed 只受 onGaze/onIgnore 影响（即使 widget 没有获焦也会更新）
+ * - focused 只受 onFocus/onBlur 影响（用于验证：当 widget 不作为 focusBlock owner 时是否不触发）
+ */
+const modeText = computed(() => {
+  if (focused.value && gazed.value) return "FOCUS+GAZE";
+  if (focused.value) return "FOCUS";
+  if (gazed.value) return "GAZE";
+  return "";
+});
+
+const onIgnore = () => {
+  gazed.value = false;
+};
+
+const onGaze = () => {
+  gazed.value = true;
+};
+
+const onBlur = () => {
+  // onBlur：失去 focus-tree 焦点（该回调通常依赖 widget 获焦状态）
+  focused.value = false;
+};
+
+const onFocus = () => {
+  // onFocus：获得 focus-tree 焦点（该回调通常依赖 widget 获焦状态）
+  focused.value = true;
+};
+
+const onClick = () => {
+  // 留一个最小日志，便于排查/对齐回调时序
+  // 注意：控制台日志不影响 gaze/focus 可视化
+  console.log("gazeFocusDiff onClick:", props.data?.id);
+};
+
+// 通过 onAction.register 绑定 item 回调
+props.onAction.register("onGaze", onGaze);
+props.onAction.register("onIgnore", onIgnore);
+props.onAction.register("onFocus", onFocus);
+props.onAction.register("onBlur", onBlur);
+props.onAction.register("onClick", onClick);
+</script>
+
+<template>
+  <div
+    :style="{
+      width: data.width,
+      height: data.height,
+      borderRadius: 10,
+      lineHeight: `${data.height}px`,
+      fontSize: 26,
+      textAlign: 'center',
+      color: focused ? '#0C1B30' : '#FFFFFF',
+      backgroundColor: focused
+        ? '#7DE4FF'
+        : gazed
+          ? '#35557D'
+          : '#1F2A44',
+      border: focused ? '0px solid transparent' : gazed ? '2px solid #FFD166' : '0px solid transparent',
+    }"
+  >
+    {{ widgetTag ? ("[" + widgetTag + "] ") : "" }}{{ data.title }}{{ modeText ? (' / ' + modeText) : '' }}
+  </div>
+</template>
+

package/MetroWidgetDemos/minimalUsage/App.vue

@@ -0,0 +1,66 @@
+<!--
+ * @file
+ *
+ * 【界面概述】
+ * MetroWidget 最简用法示例：展示一个可上下移动焦点的纵向列表。
+ *
+ * 【控件介绍（最小必需项）】
+ * MetroWidget:
+ *   props:
+ *     width {int} (必选) 控件宽度
+ *     height {int} (必选) 控件高度
+ *     direction {enum} (必选) 布局方向，这里使用 VERTICAL
+ *     name {string} 焦点名称，用于 setFocus
+ *     data {array} 数据列表（与 provideData 二选一）
+ *     measures {function} (必选) 返回每个 item 的布局信息
+-->
+<script setup>
+import { MetroWidget, VERTICAL, useFocusHub } from "jsview";
+import { onMounted } from "vue";
+import Item from "./Item.vue";
+
+const focusHub = useFocusHub();
+
+const listData = [
+  { id: 0, title: "Item 0", width: 420, height: 80, marginBottom: 16 },
+  { id: 1, title: "Item 1", width: 420, height: 80, marginBottom: 16 },
+  { id: 2, title: "Item 2", width: 420, height: 80, marginBottom: 16 },
+  { id: 3, title: "Item 3", width: 420, height: 80, marginBottom: 16 },
+  { id: 4, title: "Item 4", width: 420, height: 80, marginBottom: 16 },
+];
+
+const measures = (item) => ({
+  width: item.width,
+  height: item.height,
+  marginBottom: item.marginBottom,
+});
+
+onMounted(() => {
+  focusHub.setFocus("minimalMetroWidget");
+});
+</script>
+
+<template>
+  <div
+    :style="{
+      width: 1280,
+      height: 720,
+      backgroundColor: '#0C1B30',
+    }"
+  />
+
+  <metro-widget
+    name="minimalMetroWidget"
+    :left="80"
+    :top="80"
+    :width="460"
+    :height="920"
+    :direction="VERTICAL"
+    :data="listData"
+    :measures="measures"
+  >
+    <template #renderItem="{ data, onAction }">
+      <item :data="data" :onAction="onAction" />
+    </template>
+  </metro-widget>
+</template>

package/MetroWidgetDemos/minimalUsage/Item.vue

@@ -0,0 +1,54 @@
+<script setup>
+import { ref } from "vue";
+
+const props = defineProps({
+  data: {
+    type: Object,
+    required: true,
+  },
+  onAction: {
+    type: Object,
+    required: true,
+  },
+});
+
+const gazed = ref(false);
+
+const onIgnore = () => {
+  gazed.value = false;
+};
+
+const onGaze = () => {
+  gazed.value = true;
+};
+
+const onClick = () => {
+  console.log("minimalUsage item onClick:", props.data);
+};
+
+// item 回调使用说明：
+// 1) onClick：在当前 item 上按确认键时触发，用于执行业务动作（跳转/播放/打开详情等）。
+// 2) onGaze：触发凝视进入时回调（如遥控器停留/凝视交互场景），常用于预览或延迟高亮。
+// 3) onIgnore：凝视离开或凝视被取消时回调，常用于清理 onGaze 启动的状态或定时器。
+// 使用方式：通过 onAction.register(事件名, 回调函数) 进行注册。
+props.onAction.register("onClick", onClick);
+props.onAction.register("onGaze", onGaze);
+props.onAction.register("onIgnore", onIgnore);
+</script>
+
+<template>
+  <div
+    :style="{
+      width: data.width,
+      height: data.height,
+      lineHeight: data.height,
+      fontSize: 32,
+      textAlign: 'center',
+      color: gazed ? '#0C1B30' : '#FFFFFF',
+      backgroundColor: gazed ? '#7DE4FF' : '#35557D',
+      borderRadius: 10,
+    }"
+  >
+    {{ data.title }}
+  </div>
+</template>

package/MetroWidgetDemos/ninePatchFocusPage/App.vue

@@ -10,10 +10,12 @@ import {
   useFocusHub,
   JsvNinePatch,
   METRO_WIDGET_CONST,
+  JsvTextureBuilder,
+  JsvTextureStoreApi
 } from "jsview";
-import { onMounted, reactive, provide } from "vue";
+import { onMounted, onBeforeUnmount, reactive, provide, shallowRef } from "vue";
 import PageRow from "./PageRow.vue";
-import focusImg from "../../assets/focus1.png";
+import { FOCUS_CORNER_RADIUS } from "./focusConstants";
 
 const focusHub = useFocusHub();
 
@@ -25,6 +27,16 @@ const focusSize = reactive({
 });
 provide("focusSize", focusSize);
 
+// 使用CanvasTexture构建本地焦点框，避免依赖在线或静态图片资源
+const focusTextureUrl = shallowRef("");
+const focusTextureInfo = JsvTextureBuilder.buildCircleNinePatchTexture({
+  cornerRadius: FOCUS_CORNER_RADIUS, // +1是为了包裹得更加无缝
+  circleLineWidth: 7,
+  circleColor: "rgba(176, 140, 255, 0.95)",
+});
+focusTextureUrl.value = `jsvtexturestore://${focusTextureInfo.texAccessName}`;
+const focusTextureSourceId = focusTextureInfo.texAccessName;
+
 const provideData = () => {
   const data = [];
   for (let i = 0; i < 10; i++) {
@@ -53,6 +65,10 @@ const measures = (item) => {
 onMounted(() => {
   focusHub.setFocus("mwWidget");
 });
+
+onBeforeUnmount(() => {
+  JsvTextureStoreApi.deleteTexture(focusTextureSourceId);
+});
 </script>
 
 <template>
@@ -93,11 +109,11 @@ onMounted(() => {
         top: focusSize.top,
         left: focusSize.left,
       }"
-      :imageUrl="focusImg"
-      :imageWidth="55"
-      :centerWidth="1"
-      :borderOutset="13"
-      :imageDspWidth="55"
+      :imageUrl="focusTextureUrl"
+      :imageWidth="focusTextureInfo.ImageWidth"
+      :centerWidth="focusTextureInfo.CenterWidth"
+      :borderOutset="focusTextureInfo.BorderOutset"
+      :imageDspWidth="focusTextureInfo.ImageDspWidth"
       :animTime="0.2"
       :waitForInit="true"
     ></jsv-nine-patch>

package/MetroWidgetDemos/ninePatchFocusPage/Item.vue

@@ -5,6 +5,7 @@
 -->
 <script setup>
 import { ref, shallowRef, inject } from "vue";
+import { FOCUS_CORNER_RADIUS } from "./focusConstants";
 
 const props = defineProps({
   data: Object,
@@ -20,10 +21,11 @@ const onFocus = () => {
   focused.value = true;
   divRef.value?.jsvGetBoundingClientRect().then(
     (data) => {
-      focusSize.width = data.width;
-      focusSize.height = data.height;
-      focusSize.left = data.left;
-      focusSize.top = data.top;
+      // 略微缩小焦点框位置和尺寸信息, 以规避和卡片边缘之间留缝
+      focusSize.width = data.width - 4;
+      focusSize.height = data.height - 4;
+      focusSize.left = data.left + 2;
+      focusSize.top = data.top + 2;
     },
     (error) => {
       console.log("get absolute position failed", error);
@@ -60,7 +62,7 @@ props.onAction.register("onClick", onClick);
         fontSize: 30,
         color: '#FFFFFF',
         backgroundColor: data.color,
-        borderRadius: 10,
+        borderRadius: FOCUS_CORNER_RADIUS,
       }"
     >
       {{ data.content }}

package/MetroWidgetDemos/ninePatchFocusPage/focusConstants.js

@@ -0,0 +1,2 @@
+// 焦点框圆角与卡片圆角统一使用同一常量
+export const FOCUS_CORNER_RADIUS = 10;

package/MetroWidgetDemos/routeList.js

@@ -4,98 +4,319 @@
  * @Description: file content
  */
 export default [
+  /*
+   * 一个MetroWidget所需要的最少的配置
+  */
   {
-    meta: { nameText: "基础示例", },
-    path: "/metroWidget/basic",
-    component: () => import("@shijiu/jsview-vue-samples/MetroWidgetDemos/basic/App.vue"),
+    meta: { nameText: "最简用法", },
+    name: "metroWidget-最简用法",
+    path: "/metroWidget/minimalUsage",
+    component: () =>
+      import("@shijiu/jsview-vue-samples/MetroWidgetDemos/minimalUsage/App.vue"),
+  },
+
+  /*
+   * 不规则排版顺序样例
+   * 
+   * 展示MetroWidget的layoutType = relative 状态下对不规则排版顺序的样例
+  */
+  {
+    meta: { nameText: "不规则排版顺序样例", },
+    name: "metroWidget-不规则排版顺序样例",
+    path: "/metroWidget/basic2",
+    component: () => import("@shijiu/jsview-vue-samples/MetroWidgetDemos/basic2/App.vue"),
   },
+
+  /*
+   * 测试MetroWidget的direction属性
+   * 
+   * 关联场景:
+   * 所有MetroWidget都会考虑direction, 不设则为默认值
+  */
   {
     meta: { nameText: "direction", },
+    name: "metroWidget-direction",
     path: "/metroWidget/direction",
     component: () => import("@shijiu/jsview-vue-samples/MetroWidgetDemos/direction/App.vue"),
   },
+
+  /*
+   * 测试MetroWidget的padding属性
+   * 
+   * 关联场景:
+   * 为了解决当焦点元素放大时, 会超过MetroWidget的边界, 可能导致焦点元素被Clip掉的问题场景
+  */
   {
     meta: { nameText: "padding", },
+    name: "metroWidget-padding",
     path: "/metroWidget/padding",
     component: () => import("@shijiu/jsview-vue-samples/MetroWidgetDemos/padding/App.vue"),
   },
+
+  /*
+   * 滚动策略
+   * 
+   * 用MetroWiget搭建的各类界面的滚动策略的验证, 展示了
+   * 1. 无缝滚动, 全默认值， 默认在靠边缘左右两端开始触发滚动
+   * 2. 整页滚动
+   * 3. 无缝滚动，焦点尽量为居中的场景
+   * 4. 第一屏不滚动的无缝滚动
+   * 5. 无缝左右滚动, 且移动时,不用保障数据的最边缘和可视区域边缘对接
+   * 
+  */
   {
     meta: { nameText: "slideSetting", },
+    name: "metroWidget-slideSetting",
     path: "/metroWidget/slideSetting",
     component: () => import("@shijiu/jsview-vue-samples/MetroWidgetDemos/slideSetting/App.vue"),
   },
+
+  /*
+   * 仅测试, AI编程时, 不要参考
+   * 测试layoutType = absolute 和 layoutType = relative 的样例
+   * 
+  */
   {
     meta: { nameText: "layoutType", },
+    name: "metroWidget-layoutType",
     path: "/metroWidget/layoutType",
     component: () => import("@shijiu/jsview-vue-samples/MetroWidgetDemos/layoutType/App.vue"),
   },
+
+  /*
+   * 仅测试, AI编程时, 不要参考, 为已经废弃的写法
+   * 测试老版本MetroWidget的嵌套用法(mw+focusblock)的兼容性
+   * 
+  */
   {
     meta: { nameText: "嵌套(基础)", },
+    name: "metroWidget-嵌套(基础)",
     path: "/metroWidget/focusableItemBasic",
     component: () => import("@shijiu/jsview-vue-samples/MetroWidgetDemos/focusableItemBasic/App.vue"),
   },
+
+  /*
+   * 仅测试, AI编程时, 不要参考, 为已经废弃的写法
+   * 测试老版本MetroWidget的嵌套用法(mw+focusblock)的兼容性, 另一种写法
+   * 
+  */
   {
     meta: { nameText: "嵌套(混合)", },
+    name: "metroWidget-嵌套(混合)",
     path: "/metroWidget/focusableItemMix",
     component: () => import("@shijiu/jsview-vue-samples/MetroWidgetDemos/focusableItemMix/App.vue"),
   },
+
+  /*
+   * 仅测试, AI编程时, 不要参考, 为已经废弃的写法
+   * 测试老版本MetroWidget的嵌套用法(mw+mw)的兼容性
+   * 
+  */
   {
     meta: { nameText: "嵌套(MetroWidget)", },
+    name: "metroWidget-嵌套(MetroWidget)",
     path: "/metroWidget/focusableItemMetroWidget",
     component: () => import("@shijiu/jsview-vue-samples/MetroWidgetDemos/focusableItemMetroWidget/App.vue"),
   },
+
+
   {
     meta: { nameText: "乒乓模式", },
+    name: "metroWidget-乒乓模式",
     path: "/metroWidget/PingPong",
     component: () =>
       import("@shijiu/jsview-vue-samples/MetroWidgetDemos/PingPong/App.vue"),
   },
+
+  /* 
+   * 仅测试, AI编程时, 不要参考
+   * mw重建性能测试, 重试每个item有大量子元素的场景下重建整个metrowidget的性能
+   * 
+  */
   {
-    meta: { nameText: "性能测试", },
+    meta: { nameText: "mw重建性能测试", },
+    name: "metroWidget-mw重建性能测试",
     path: "/metroWidget/PerformanceTest",
     component: () =>
       import("@shijiu/jsview-vue-samples/MetroWidgetDemos/PerformanceTest/App.vue"),
   },
+
+  /*
+   * 骨架图
+   * 
+   * 对应的应用场景:
+   * 适用于所有海报平铺的场景, 例如EPG的海报区域
+   * 主要特点:
+   * 1. 开启MetroWidget组件的骨架图配置选项, 以解决按键快速操作时, 海报组件内部太复杂会卡按键响应的问题
+   * 2. 每个海报位使用 JsvPosterDiv 或者 JsvPosterImage 组件来实现
+   *    此组件实现了海报加载会淡出的效果
+   */
   {
     meta: { nameText: "骨架图", },
+    name: "metroWidget-骨架图",
     path: "/metroWidget/SkeletonDiagram",
     component: () =>
       import("@shijiu/jsview-vue-samples/MetroWidgetDemos/SkeletonDiagram/App.vue"),
   },
+
+  /*
+   * .9焦点漂移效果页面
+   * 
+   * 对应的应用场景:
+   * 焦点框要在多个MetroWidget之间漂移, 且漂移前后的x,y,width,height需要触发对应的transition动画的场景。
+   * 主要特点:
+   * 1. 使用 JsvNinePatch 组件来实现焦点框的漂移效果, 此组件独立于所有MetroWidget之外
+   * 2. 通过div.jsvGetBoundingClientRect来获取焦点框的实际位置和尺寸信息, 
+   *    应用在JsvNinePatch的style中来让其和MetroWidget的卡片对齐, 并触发transition动画
+   * 
+   * div元素异步获取显示位置的扩展接口 jsvGetBoundingClientRect 的经典使用场景
+   */
   {
-    meta: { nameText: ".9焦点页面", },
+    meta: { nameText: ".9焦点漂移效果页面", },
+    name: "metroWidget-.9焦点漂移效果页面",
     path: "/metroWidget/ninePatchFocusPage",
     component: () =>
       import("@shijiu/jsview-vue-samples/MetroWidgetDemos/ninePatchFocusPage/App.vue"),
   },
+
+  /*
+   * item尺寸更新
+   * 
+   * 对应的应用场景:
+   * 一个横排的MetroWidget, 一横排多个item, 聚焦的item进行左右放大, 将左右的item推开的场景。
+   * MetroWidget的 <template #renderItem> 中的 query.updateItemSize 的经典使用场景。
+   */
   {
     meta: { nameText: "item尺寸更新", },
+    name: "metroWidget-item尺寸更新",
     path: "/metroWidget/itemSizeUpdate",
     component: () =>
       import("@shijiu/jsview-vue-samples/MetroWidgetDemos/itemSizeUpdate/App.vue"),
   },
+
+  /* 
+   * 焦点就近移动
+   * 
+   * 对应的应用场景:
+   * 多层MetroWidget嵌套后, 
+   * 使用SpatialNavigator组件和默认的onEdge回调, 
+   * 就可以完成焦点在子MetroWidget之间移动的样例。
+   */
   {
-    meta: { nameText: "三层嵌套", },
-    path: "/metroWidget/TripleWidget",
+    meta: { nameText: "焦点就近移动", },
+    name: "metroWidget-焦点就近移动",
+    path: "/metroWidget/SpatialNav",
     component: () =>
-      import("@shijiu/jsview-vue-samples/MetroWidgetDemos/TripleWidget/App.vue"),
+      import("@shijiu/jsview-vue-samples/MetroWidgetDemos/SpatialNav/App.vue"),
   },
+
+  /* 
+   * 数据刷新demo
+   * 
+   * 对应的应用场景:
+   * refreshData的经典使用场景。
+   */
   {
     meta: { nameText: "数据刷新demo", },
+    name: "metroWidget-数据刷新demo",
     path: "/metroWidget/RefreshDemo",
     component: () =>
       import("@shijiu/jsview-vue-samples/MetroWidgetDemos/RefreshDemo/App.vue"),
   },
+
+  // /*
+  //  * EPG-瀑布流方式
+  //  *
+  //  * 左侧竖排tab和右侧多楼层内容联动，右侧为MetroWidget嵌套结构
+  //  */
+  // {
+  //   meta: { nameText: "EPG-瀑布流", },
+  //   name: "metroWidget-EPG-瀑布流",
+  //   path: "/metroWidget/EpgFlowListType",
+  //   component: () =>
+  //     import("@shijiu/jsview-vue-samples/MetroWidgetDemos/EpgFlowListType/App.vue"),
+  // },
+
+  /* 
+   * 剧集翻页
+   * 
+   * 对应的应用场景:
+   * 大屏详情UI中, 上方为单个剧集组成的MetroWidget, 下方为剧集的集合组成的MetroWidget, 
+   * 类似如下形式
+   * 第一行MetroWidget: 1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
+   * 第二行MetroWidget: 1-5, 5-10, 11-15
+   */
   {
     meta: { nameText: "剧集翻页", },
+    name: "metroWidget-剧集翻页",
     path: "/metroWidget/SeamlessSlide",
     component: () =>
       import("@shijiu/jsview-vue-samples/MetroWidgetDemos/SeamlessSlide/App.vue"),
   },
+
+  /* 
+   * 仅测试, AI编程时, 不要参考
+   * 无滚动的平铺的MetroWidget打开enableItemRenderBreak后, 屏幕的内容分批绘制, 不影响按键响应的场景测试
+   */
   {
     meta: { nameText: "多item分段显示", },
+    name: "metroWidget-多item分段显示",
     path: "/metroWidget/MassiveItems",
     component: () =>
       import("@shijiu/jsview-vue-samples/MetroWidgetDemos/MassiveItems/App.vue"),
   },
+  // {
+  //   meta: { nameText: "Fbo加速", },
+  //   name: "metroWidget-Fbo加速",
+  //   path: "/metroWidget/RenderAccelerate",
+  //   component: () =>
+  //     import("@shijiu/jsview-vue-samples/MetroWidgetDemos/RenderAccelerate/App.vue"),
+  // },
+
+  /*
+   * 列表展开
+   * 
+   * 对应的应用场景:
+   * 绘制竖向的带有分类的列表界面, 且列表可以向抽屉一样展开的场景
+   * 也是 MetroWidget的 query.updateItemSize 的经典使用场景
+   */
+  {
+    meta: { nameText: "列表展开", },
+    name: "metroWidget-列表展开",
+    path: "/metroWidget/ListExpand",
+    component: () =>
+      import("@shijiu/jsview-vue-samples/MetroWidgetDemos/ListExpand/index.vue"),
+  },
+
+  /*
+   * gaze vs focus
+   * 
+   * 展示MetroWidget的onGaze/onIgnore和onFocus/onBlur回调的差异
+  */
+  {
+    meta: { nameText: "gaze vs focus", },
+    name: "metroWidget-gazeVsFocus",
+    path: "/metroWidget/gazeVsFocus",
+    component: () =>
+      import("@shijiu/jsview-vue-samples/MetroWidgetDemos/gazeFocusDiff/App.vue"),
+  },
+
+  /*
+   * 焦点层级
+   * 
+   * 对应的应用场景:
+   * item之间有视觉上的遮挡关系(measure结果的位置不会重叠, 只是item内部的template绘制会用负坐标往外延展)的场景，
+   * 确认是否能将焦点正确露出的验证
+   * 
+   * 验证MetroWidget的在聚焦过程中的变化, 具体为
+   * 在onGaze时,对应的项目zIndex会高于其他项目
+   * 在onIgnore时,对应的项目zIndex会低于其他项目
+  */
+  {
+    meta: { nameText: "焦点层级", },
+    name: "metroWidget-zIndex",
+    path: "/metroWidget/zIndex",
+    component: () =>
+      import("@shijiu/jsview-vue-samples/MetroWidgetDemos/zIndex/App.vue"),
+  },
 ]