yuffie-browser

Yuffie Browser

vue3 版阿拉丁 h5 基础库 主要有容器、客户端、配置平台的通信及模拟，前端路由导航（活动入口）功能

0.4.0版本以后，layout组件支持新配置平台，不再对group_id进行判断过滤

[[TOC]]

项目初始化方式

项目建议使用 vite 提供的 vue 模板初始化，可参考文档。

h5 库安装方法

yarn add yuffie-browser

全局注册

createYuffie 创建一个 vue 插件，并且在 main.ts 中注册，使用方法如下：

--- yuffie.ts
import { createYuffie, YuffieConfig } from 'yuffie-browser'

// 活动树，用于声明活动顺序
const routeTree = [
  // 层级1
  {
    type: '10001',
  },
  {
    type: '10002',
    children: [
      {
        type: '10002-1',
      },
      {
        type: '10002-2',
      },
    ],
  },
  {
    type: '10003',
    children: [
      {
        type: '10003-1',
      },
      {
        type: '10003-2',
      },
    ],
  },
  {
    type: '10004',
    children: [
      {
        type: '10004-1',
      },
      {
        type: '10004-2',
      },
    ],
  },
]

// 活动目录扫描
const activities = import.meta.glob('/src/activities/**/activity.vue')
const apiMockFiles = import.meta.globEager('/src/activities/**/api_mock.*')
const clientMocksFiles = import.meta.globEager('/src/activities/**/client_mock.*')
const configMocksFiles = import.meta.globEager('/src/activities/**/config_mock.*')

// 根据活动树结构生成路由
const createRoute = (rt: typeof routeTree, p = '/src/activities') => {
  const routes: YuffieConfig['routes'] = []
  rt.forEach((r, i) => {
    const path = `${p}/${r.type}`
    routes[i] = {
      type: r.type,
      component: activities[`${path}/activity.vue`],
      apiMock: apiMockFiles[Object.keys(apiMockFiles).find(file => RegExp(`${path}/api_mock.*`).test(file))!]?.default,
      clientMock:
        clientMocksFiles[Object.keys(clientMocksFiles).find(file => RegExp(`${path}/client_mock.*`).test(file))!]
          ?.default,
      configMock:
        configMocksFiles[Object.keys(configMocksFiles).find(file => RegExp(`${path}/config_mock.*`).test(file))!]
          ?.default,
    }
    if (r.children) {
      routes[i].children = createRoute(r.children, path)
    }
  })
  return routes
}
const config: YuffieConfig = {
  url: 'ws://121.4.214.235:1945',
  useMock: true,
  // 也支持手写yuffie-routes
  routes: createRoute(routeTree),
}

export default createYuffie(config)



--- main.ts
createApp(root).use(Yuffie).mount('#app')

YuffieConfig 是注册配置的类型文件，包括：

use(Yuffie)后根节点会注册一些全局状态，提供给活动页面。同时该插件也能自动判断运行时的活动 id，如果是 mock 启动，则会自动替换 mock 响应。

活动中使用

在活动代码中，使用useYuffie方法获取 h5 库的 context，示例如下：

import { useYuffie } from 'yuffie-browser'
const { onCreate, send, getActivityConfig, client } = useYuffie()

此方法等同于

import { yuffieInjectToken } from 'yuffie-browser'
inject(yuffieInjectToken)

上下文中注入的方法

包含路由，通信，事件监听等。详见下表

• yuffieNotice
• yuffieRuntimeConfig
• yuffieSession
• activityConfigs
• send
• getActivityConfig
• client
• onCreate

方法如果需要推导类型，则可传入方法泛型参数，如：

const res = send<string>(...payload)

示例中会自动推断请求返回的 res 类型为 string

client 对象为浏览器注入的 js 方法，包含以下内容：

方法对应的作用见阿拉丁接入文档。

event 对象和 yuffieNotice 使用方法大致相同，包含 on，和 off 两个方法。用于订阅游戏主动通知的事件，事件包含on-bag-change， on-browser-show两种。

如果是 mock 模式启动，调用 client 的方法，会自动读取当前活动目录下的 client_mock.js 读取 mock 的返回值。

Layout 组件

根据代码（自动路由中为文件路径），和配置平台的条件，自动生成带红点的导航栏，和 router-view 的组件。

如果全局注册时传递 useMock 为 true，导航栏会根据全局注册 routes，不判断条件直接展示路径下的全部活动。 否则则会判断配置中的组号（group_id）时间（activity_time）显示标题（show_title）等条件，过滤出对应的活动。

可以多层级嵌套使用，用于展示树形系列活动布局。

<script lang="ts">
  import { YuffieLayout } from 'yuffie-browser'

  export default {
    name: 'App',
    components: {
      YuffieLayout,
    },
  }
</script>
<template>
  <YuffieLayout>
    <!-- 导航 -->
    <template #menu="{ activity, showMark }">
      <div class="menu">
        <div>{{ activity.name }}</div>
      </div>
    </template>
    <!-- 自定义菜单 -->
    <template #custom>
      <div>自定义内容</div>
    </template>
    <!-- 关闭 -->
    <template #close>
      <div class="close" />
    </template>
  </YuffieLayout>
</template>

其中有 slot menu 需要自行编写，用于活动的导航定义。 建议在根组件编写一下两个 slot：

• custom
• close

custom 用于右上角的自定义按钮，目前在天龙怀旧中为刷新和问号按钮。close 用于右上角的关闭按钮。 menu 和 close 都已经绑定好了点击的事件（切换路由，点击关闭游戏窗口）

slot menu 提供的上下文参数包括

• activity: 单个活动的配置
• showMark: 是否显示红点
• filterResult: 是否被配置过滤, 即根据条件此 activity 是否应该显示（needFilter 为 true 时默认会过滤显示的配置，此值会为 true；当组件中使用 needFilter 为 false，活动配置不被过滤时，则 filterResult 的值为根据配置中活动是否显示计算的结果）
• clientEvent: 跳转事件，当点击阻止冒泡时，可以使用此字段

layout 组件的 props：

layout 组件的暴露属性(使用 definExpose 声明，通过组件的 ref 调用)：

以下是默认样式，可以覆盖，实现布局的自定义

// layout
.layout-main-container {
  display: flex;
  position: relative;
  box-sizing: border-box;
  overflow: auto;
  .layout-menu {
    overflow-y: auto;
  }
  .layout-view {
    flex: 1;
  }
  .layout-tools {
    position: absolute;
    top: 0;
    right: 0;
    display: flex;
  }
}

注意：使用主题时，会等待后台配置推送后后，再加载主题 css。 使用树形布局时，每层 v-deep 的覆盖都会影响子节点，因此建议使用行内样式，来控制布局的结构。如果必须使用外部样式，在子层级可能需要手动清除样式的影响。

树形布局如果父级节点没有活动 id，即进入层级后只有导航情况，则需要在子活动中配置 parent_type， parent_title 两个字段，用于找到父级组件，并展示标题。自动生成的父级配置会自动计算子活动的红点和展示时间。

建议的活动代码组织方式

活动需要以下四种文件：

• activity.vue
• api_mock.js
• client_mock.js
• config_mock.js

activity.vue 为单文件组件，包含一种活动类型的前端代码逻辑。

api_mock.js 为对后端接口的数据模拟，需要 export 一个 js object, key 为调用后台的 method, value 为需要模拟的响应，示例如下：

export default {
  main: [
    {
      levelId: 1,
      limit: 1,
    },
    {
      levelId: 2,
      limit: 1,
    },
    {
      levelId: 3,
      limit: 0,
    },
  ],
  get_items: {
    code: 0,
    msg: '领取成功',
  },
}

client_mock.js 为对注入到浏览器环境的 js 事件模拟，需要 export 一个 js object, key 为注入 window 中的方法名称, value 为需要模拟的结果，示例如下：

export default {
  showEntry: true,
  hideEntry: true,
  isOnline: true,
  showMark: true,
  hideMark: true,
  showBrowser: true,
  hideBrowser: true,
  getItemsCount: 1000,
  canPutInBag: true,
}

config_mock.js 为对活动静态配置的模拟，具体结构需要参照活动的具体需求来定义，示例如下:

export default {
  id: '2021070199',
  title: '标题',
}

Mock

库中提供了虚拟数据生成的工具，使用方法如下：

import { faker } from 'yuffie-browser'
const guid4 = faker.guid4()
const num = faker.digitOnes()
const url = faker.imgUrl()

faker 基于 mockjs 库的 random 模块封装，补充提供了以下方法：

字符串转换

库中提供了驼峰和下划线字符串互转的方法

使用方法如下：

import { toHump, toLine, record2Line } from 'yuffie-browser'
console.log(toHump('group_id')) // 'groupId'
console.log(toLine('groupId')) // 'group_id'
console.log(record2Line({ roleId: '1', groupId: '2' })) // {role_id: '1', group_id: '2'}
console.log(record2Line({ role_id: '1', group_id: '2' })) // { roleId: '1', groupId: '2' }

框架如何发布

编译后上传 npm 发布即可。

yarn build && yarn publish