更新记录
1.0.1(2026-11-21)
- 优化棋院大厅的棋鼓、双剑、棋谱与快弈棋印,为各入口加入独立的待机动作。缺少主题图时显示随包棋具。
- 优化棋院按钮的触压和松手反馈,并为入场、签到落印和胜负结算加入分层动效。棋院跟随系统减少动态效果,也可在棋院设置中关闭动效。
- 重绘设置入口与棋院设置面板,玉石滑钮直接显示动效状态。可在面板内查看、复制棋局诊断,并返回当前棋桌。
- 修复 HBuilderX H5 开发预览中象棋页面加载失败、显示连接超时的问题。
- 修复好友房退席超时后收到成功回执仍停留在棋桌的问题,旧回执与新棋桌隔离。
- 修复好友房并发操作时可能误把其他着法或终局当作本次提交成功的问题。
1.0.0(2026-11-21)
- 新增中国象棋本地会话、合法走法查询、终局判定、悔棋与会话释放。
- 新增竖屏棋院、Cocos 棋盘、同屏对局、电脑练棋、局内支招、终局和棋谱回看。
- 新增可注入的好友房与主题配置、六位房号入座、uni-app x 完整示例和传统 uni-app 棋规示例。
平台兼容性
uni-app(5.34)
| Vue2 |
Vue3 |
Chrome |
Safari |
app-vue |
app-nvue |
Android |
iOS |
鸿蒙 |
| × |
√ |
√ |
- |
- |
× |
√ |
√ |
√ |
| 微信小程序 |
支付宝小程序 |
抖音小程序 |
百度小程序 |
快手小程序 |
京东小程序 |
鸿蒙元服务 |
QQ小程序 |
飞书小程序 |
小红书小程序 |
快应用-华为 |
快应用-联盟 |
| × |
× |
× |
× |
× |
× |
× |
× |
× |
× |
× |
× |
uni-app x(5.34)
| Chrome |
Safari |
Android |
iOS |
鸿蒙 |
微信小程序 |
| √ |
- |
√ |
√ |
√ |
× |
其他
| 多语言 |
暗黑模式 |
宽屏模式 |
蒸汽模式 |
| × |
× |
√ |
√ |
朱砂棋院 · 中国象棋
介绍
在 uni-app x 中注册一个页面,就能从棋院大厅进入人机、同屏或好友对局。第一次接入,先跑基础示例。人机和同屏使用本地 UTS 棋规,棋盘使用随包的 Cocos 资源;需要好友房或自定义皮肤时,再接入对应模块。已有棋盘界面的项目可直接调用棋规。
功能特色
| 功能 |
玩家看到什么 |
接入条件 |
| 完整棋院 |
进场加载、棋院大厅、开场布子、走子动画、胜负结算与回看 |
在 uni-app x 注册完整示例页;Web 棋盘需要 WebGL |
| 人机练习 |
玩家执红先行,电脑执黑应手;可支招、翻盘和悔棋 |
离线可玩;开启悔棋后可回到玩家上个回合 |
| 同屏对弈 |
两人在同一台设备轮流走;可选子、查看落点、撤回最后一着或认输 |
离线可玩;悔棋由 allowUndo 控制 |
| 好友房 |
房主开桌,好友凭六位房号入席,双方同步走子和结算 |
配置 rooms 并提供房间服务;联机以服务端确认为准 |
| 棋规与棋谱 |
自动校验马腿、象眼、炮架、将帅照面及应将;将死或困毙判胜。回看可逐着还原吃子 |
棋谱在当局内有效;在线回看可继续收到对手新着 |
| 主题与设置 |
可替换标题、庭院、棋具、双方头像等 11 处图片。大厅棋具各有待机动作,触压时牌面下沉 |
缺图时显示随包棋具。在「设置」中切换界面动效,或打开「棋局诊断」查看、复制运行记录。系统启用减少动态效果时,开关显示关闭 |
适合哪些场景
| 你的项目 |
从哪里开始 |
需要自己提供什么 |
| 给现有应用加一个完整小游戏 |
基础示例,直接注册分发页 |
一个打开棋院的按钮 |
| 已有自己的玩法首页或退出流程 |
完整示例,把棋院组件嵌入自己的页面 |
页面路由与返回行为 |
| 已有棋盘,只缺裁判或棋谱 |
高级示例,从插件根入口调用 UTS |
棋盘绘制、输入与对局展示 |
| 已有好友、邀请或棋室业务 |
进阶示例,接入房间适配器 |
权威房间状态、席位鉴权与网络请求 |
| 希望使用自己的美术 |
模块示例,按用途替换图片 |
可访问的 PNG、原始字节数及摘要 |
下载与导入
| 宿主 |
示例代码位置 |
| uni-app x,Vue 3,页面脚本 TypeScript |
uni_modules/lizhao-xiangqi/example/uniappx/index.uvue,完整棋院 |
| 传统 uni-app,Vue 选项式 API |
uni_modules/lizhao-xiangqi/example/uniapp/index.vue,同屏规则示例 |
从基础到进阶:按业务模块使用
基础功能配置示例
目标:点一个按钮,打开棋院并走出第一着。 将完整的 uni_modules/lizhao-xiangqi/ 导入工程。把下面的一个路由对象追加到已有 pages.json 的 pages 数组,保留原来的首页和其他页面。方向、系统栏和滚动设置只对这个棋院页面生效。
{
"path": "uni_modules/lizhao-xiangqi/example/uniappx/index",
"style": {
"navigationBarTitleText": "朱砂棋院",
"navigationStyle": "custom",
"pageOrientation": "portrait",
"hideStatusBar": true,
"hideBottomNavigationIndicator": true,
"disableScroll": true
}
}
把下面的按钮和函数放到自己的首页中。启动后依次点「打开棋院 → 进入棋院 → 同屏对弈」,先点红方中兵,再点它正上方的交点。显示「第 1 着」并轮到黑方,即完成首次接入。
<template>
<button @click="openChess">打开棋院</button>
</template>
<script setup lang="ts">
function openChess() {
// pages.json 的 path 不带开头的斜杠;navigateTo 使用带斜杠的完整页面路径。
uni.navigateTo({
url: '/uni_modules/lizhao-xiangqi/example/uniappx/index',
fail: err => uni.showModal({ title: '未能打开棋院', content: err.errMsg, showCancel: false })
})
}
</script>
高级示例
目标:在自有界面中完成一次走棋、悔棋和认输。 在业务脚本中从插件根入口导入七个同步方法。坐标按黑方在上的棋盘编号,红方中兵从 58 前进到 49。翻转画面后,传给 API 的数字仍相同。
import {
createXiangqiGameSync, getXiangqiSnapshotSync, getXiangqiTargetsSync,
moveXiangqiPieceSync, undoXiangqiMoveSync, resignXiangqiGameSync,
disposeXiangqiGameSync
} from '@/uni_modules/lizhao-xiangqi'
// 成功时继续,失败时保留来源、错误码和原始原因,便于定位哪一步出错。
function check(reply: { ok: boolean; errSubject: string; errCode: number; errMsg: string }) {
if (!reply.ok) throw new Error(reply.errSubject + ' ' + reply.errCode + ' ' + reply.errMsg)
}
export function playRuleExample() {
const opened = createXiangqiGameSync({ allowUndo: true }) // 改为 false 可禁止本地悔棋
check(opened)
if (opened.snapshot == null) throw new Error('未取得初始局面')
const id = opened.snapshot.sessionId // 保留本局 ID,后续每次操作都使用它
try {
const legal = getXiangqiTargetsSync(id, 58)
check(legal)
if (!legal.targets.includes(49)) throw new Error('中兵当前不能走到 49')
check(moveXiangqiPieceSync(id, 58, 49))
const moved = getXiangqiSnapshotSync(id)
check(moved)
console.log(moved.snapshot?.ply, moved.snapshot?.turn) // 1,black
check(undoXiangqiMoveSync(id)) // 撤回一着,红兵回到 58,又轮到红方
check(resignXiangqiGameSync(id)) // 当前执棋方红方认输
const ended = getXiangqiSnapshotSync(id)
check(ended)
return ended.snapshot // 可供界面展示,winner 为 black,reason 为 resign
} finally {
// 本段只演示一局。长期运行的页面应在退出或重开时释放自己的会话。
check(disposeXiangqiGameSync(id))
}
}
进阶示例
目标:让两名玩家通过自己的业务服务器对弈。 以下代码放在 Web 宿主的业务脚本,在进入棋院前调用一次 enableFriendRooms()。示例约定六个同源 POST 路由 /api/rooms/<动作>;如果已有不同的地址、请求体或 WebSocket,可在宿主转换数据。App 宿主可用自己的网络层实现同一个 XiangqiRoomRequest。
import { configureXiangqiHost, getXiangqiHostConfig } from '@/uni_modules/lizhao-xiangqi/static/host/config.js'
import { createHttpXiangqiProvider } from '@/uni_modules/lizhao-xiangqi/static/host/rooms.js'
export function enableFriendRooms() {
const rooms = createHttpXiangqiProvider(async (action, body, token) => {
const headers = { 'Content-Type': 'application/json' }
// create/join 取得席位后,适配器会在后续请求传入本局 token。
if (token) headers.Authorization = 'Bearer ' + token
const response = await fetch('/api/rooms/' + action, {
method: 'POST', headers, body: JSON.stringify(body), cache: 'no-store'
})
if (!response.ok) {
// 保留 HTTP 状态,适配器可据 403、404、410 识别失效席位。
throw Object.assign(new Error('棋室请求失败:' + response.status), { status: response.status })
}
return response.json() // create/join 返回 {seat, token, state},其余回包见下表
})
// 此函数替换整份配置。保留已设置的主题,只更换房间服务。
configureXiangqiHost({ ...getXiangqiHostConfig(), rooms })
}
| 动作 |
发给服务端的 body |
服务端成功回执 |
create |
{game: 'xiangqi'} |
{seat, token, state};创建者取得席位 |
join |
{game: 'xiangqi', code} |
{seat, token, state};房号保留六位字符串,如 '012345' |
state |
{code} |
{state};返回当前完整棋谱及房间状态 |
move |
{code, ply, from, to} |
{state};ply 是提交前服务端已确认的着数,用于识别重复或过期指令 |
resign |
{code, ply} |
{state};服务端返回终局、胜方和原因 |
leave |
{code} |
此 Web 示例要求可解析的 JSON;按请求类型返回 {state}。适配器等待退席请求结束后停止轮询 |
两份独立客户端分别建房、加入同一房号。红方走一着后,黑方应看到相同棋谱,再轮到黑方行动。需要实现自定义提供方时,可查下文「房间协议」的字段与订阅约定。
完整示例
目标:把整套棋院放进自己的页面,处理前后台和返回。 如只需默认行为,直接将 uni_modules/lizhao-xiangqi/example/uniappx/index.uvue 复制到一个已注册的页面即可。下面是可整页使用的 .uvue 写法;将基础示例中的路由和按钮地址改为自己的页面路径。
<template>
<view class="page">
<!-- 冒号传布尔值。要关闭本地悔棋,写 :allow-undo="false"。 -->
<Xiangqi :key="generation" :active="active" :allow-undo="true" @exit="exitChess" />
</view>
</template>
<script setup lang="ts">
import { nextTick, ref } from 'vue'
import { onShow, onHide } from '@dcloudio/uni-app'
import Xiangqi from '@/uni_modules/lizhao-xiangqi/components/lizhao-xiangqi/lizhao-xiangqi.uvue'
const active = ref(true)
const generation = ref(0)
// 切后台暂停输入及本机电脑应手。回到前台后再提交 active。
onShow(() => nextTick(() => { active.value = true }))
onHide(() => { active.value = false })
function exitChess() {
// 如果棋院就是直接打开的首屏,没有上一页可退,重新挂载回到进场画面。
if (getCurrentPages().length < 2) {
generation.value++
return
}
uni.navigateBack({ delta: 1, fail: () => { generation.value++ } })
}
</script>
<style>
.page { flex: 1; width: 100%; height: 100%; background-color: #162e25; }
/* #ifdef WEB */
.page { height: 100vh; }
/* #endif */
</style>
模块示例
主题模块:把自己的图片接入棋院
可以先只换一张标题图。下表给出全部资源键;文件放在宿主可对外提供的静态目录。图片地址从游戏 WebView 访问,以完整 URL 配置最直观。
| 资源键 |
对应画面 |
资源键 |
对应画面 |
title |
入场背景 |
garden |
大厅庭院 |
court |
对局棋桌背景 |
jade |
玉牌按钮底图 |
round |
快弈圆印底图 |
rack |
签到木架 |
red |
红方头像 |
black |
黑方头像 |
drum |
好友房入口鼓 |
swords |
同屏入口双剑 |
scroll |
人机练习棋卷 |
|
|
第一步,在开发电脑计算清单。 将下段保存为 make-chess-art.mjs。准备一个目录,在里面放至少一张同名 PNG,例如 title.png。执行 node make-chess-art.mjs ./chess-art https://你的素材域名/chess-art/,第二个参数换成自己的实际部署地址。脚本会把 chess-art.json 写回图片目录,再将清单和这些 PNG 部署到同一目录。该脚本只需在更换图片时运行。
import { readFile, writeFile } from 'node:fs/promises'
import { join } from 'node:path'
import { createHash } from 'node:crypto'
const [directory, publicBase] = process.argv.slice(2)
if (!directory || !publicBase) throw new Error('请传入本地图片目录和部署目录 URL')
const base = new URL(publicBase.endsWith('/') ? publicBase : publicBase + '/')
const keys = ['title', 'garden', 'court', 'jade', 'round', 'red', 'black', 'swords', 'scroll', 'drum', 'rack']
const art = {}
for (const key of keys) {
const filename = key + '.png'
let bytes
try { bytes = await readFile(join(directory, filename)) }
catch (error) {
if (error.code === 'ENOENT') continue // 未提供的键保留随包画面
throw error
}
if (!bytes.subarray(0, 8).equals(Buffer.from('89504e470d0a1a0a', 'hex')) ||
bytes.length > 4194304) throw new Error(filename + ' 需要是 4 MiB 以内的 PNG')
art[key] = {
url: new URL(filename, base).href, // 游戏能访问的文件地址
bytes: bytes.length, // 文件字节数,不是宽高或 KB
sha256: createHash('sha256').update(bytes).digest('hex') // 对本次部署的原文件求摘要
}
}
if (!Object.keys(art).length) throw new Error('没有找到可用的棋院 PNG')
await writeFile(join(directory, 'chess-art.json'), JSON.stringify(art, null, 2))
第二步,在 Web 宿主挂载棋院前加载清单。 示例使用同源目录。业务按钮可调用 openThemedChess()。跨域部署时将清单地址改成 HTTPS 绝对地址,并为清单、图片开启对应的跨域读取。
import { configureXiangqiHost, getXiangqiHostConfig } from '@/uni_modules/lizhao-xiangqi/static/host/config.js'
export async function openThemedChess() {
try {
const res = await fetch('/chess-art/chess-art.json')
if (!res.ok) throw new Error('主题清单 HTTP ' + res.status)
const art = await res.json()
const current = getXiangqiHostConfig()
// 此处保留已设置的 rooms。要只覆盖部分皮肤键,可写 art: { ...current.art, ...art }。
configureXiangqiHost({ ...current, art })
} catch (error) {
// 首次配置失败可使用随包画面;之前的有效配置仍可继续使用。
console.warn('主题未载入', error)
}
uni.navigateTo({
url: '/uni_modules/lizhao-xiangqi/example/uniappx/index',
fail: err => console.error('跳转棋院失败', err.errMsg)
})
}
房间模块:用已有服务接管自己的联机界面
使用完整棋院时,宿主提供 rooms 即可。如果自行绘制棋桌,可使用同一配置和 createRoomTable 接收入席、着法与终局。调用下面的 takeSeat 时,开桌传空字符串,入座传六位房号。返回的棋桌由该页面持有,也可传入 showLobby 处理退席超时后的成功回执。
import * as rules from '@/uni_modules/lizhao-xiangqi'
import { getXiangqiHostConfig } from '@/uni_modules/lizhao-xiangqi/static/host/config.js'
import { createRoomTable } from '@/uni_modules/lizhao-xiangqi/static/host/rooms.js'
export async function takeSeat(code, showPosition, showError, showLobby) {
const provider = getXiangqiHostConfig().rooms
if (!provider) throw new Error('请先配置房间服务')
const table = createRoomTable({
api: rules, provider,
onState: view => showPosition(view), // 按 view.snapshot 绘制;view.seat 决定自己执方
onError: message => showError(message),
onLateLeave: () => showLobby?.() // 退席超时后才确认成功,回大厅
})
try {
if (code === '') await table.create() // 开桌;实际房号从 onState 的 view.code 读取
else await table.join(code) // 入座;保留前导零
return table
} catch (error) {
table.dispose() // 入席失败也释放本次订阅和本地核验会话
throw error
}
}
// 显示合法落点可使用 table.getTargets(from)。提交后界面等 onState 通知再移动棋子。
export async function playOnline(table, from, to) {
if (!table.getTargets(from).includes(to)) throw new Error('请重新选择合法落点')
await table.move(from, to)
}
// 认输按钮在玩家确认后调用 await table.resign()。离开按钮等待退席回执,
// 如果请求失败,向玩家显示错误并保留棋桌以供重试。页面最终卸载时调用 table.dispose()。
export async function leaveTable(table) {
await table.leave()
table.dispose()
}
API用途速查
组件与宿主配置
| 参数 |
类型 |
必填 |
说明 |
默认值 |
可选参数 |
active |
boolean |
否 |
组件前台状态;随页面显示、隐藏更新。停用时暂停本机应手和输入,在线席位仍以服务端状态为准 |
true |
true、false |
allowUndo(组件) |
boolean |
否 |
模板写作 :allow-undo;挂载时取值。要为下一桌更改,先退出当前局再重新挂载 |
true |
true、false |
@exit |
无参数事件 |
否 |
组件请求离开棋院,由宿主处理返回或重新进场 |
无监听 |
完整示例中的 exitChess |
allowUndo(UTS 建局选项) |
boolean |
是 |
每局独立快照;只影响进行中的本地对局,联机关闭悔棋 |
无 |
true、false |
rooms |
XiangqiRoomProvider 或 null |
否 |
房间提供方,在挂载前设置。为 null 时显示未配置好友房,本地玩法仍可用 |
null |
HTTP 适配器、自定义提供方 |
art |
XiangqiArt |
否 |
以资源键索引图片条目;可只提供一个键 |
空对象 |
主题模块表中的 11 个键 |
art[键].url |
string |
每张图必填 |
推荐绝对 URL。同源 HTTP/HTTPS,或允许 CORS 的跨域 HTTPS;下载图片不携带登录凭据 |
无 |
最多 2048 字符 |
art[键].bytes |
number |
每张图必填 |
原始 PNG 字节数,下载后校验 |
无 |
1 至 4194304 的整数 |
art[键].sha256 |
string |
每张图必填 |
原始 PNG 的 SHA-256,在支持 WebCrypto 的安全上下文中校验 |
无 |
64 位小写十六进制 |
| 宿主帮助函数 |
何时使用 |
configureXiangqiHost(options) |
打开页面前设置主题和房间。整份替换,省略 art 或 rooms 会分别采用空对象或 null;无参调用可恢复默认 |
getXiangqiHostConfig() |
读取当前宿主配置。图片条目是副本,rooms 保留同一提供方引用 |
createHttpXiangqiProvider(request) |
用业务请求函数创建房间提供方;request(action, body, token?) 返回 Promise,详情见进阶示例 |
createRoomTable({api, provider, onState, onError, onLateLeave?}) |
自有联机界面使用。api 为插件根导出的规则方法;provider 提供席位;onState 收到被接受的新局面,onError 收到错误消息。可用 onLateLeave 处理延迟确认的退席。页面退出须释放 |
本地规则与回执
规则方法同步返回。所有回执均有 ok、errSubject、errCode、errMsg;成功码为 0,错误来源为 lizhao-xiangqi。创建和读局面额外返回 snapshot(失败为 null),查询落点额外返回 targets(可能为空)。
| API |
用途及结果 |
createXiangqiGameSync({allowUndo}) |
标准开局,红方先走。记录 snapshot.sessionId 供本局后续调用 |
getXiangqiSnapshotSync(sessionId) |
读取局面与棋谱的副本;可供界面渲染或结算展示 |
getXiangqiTargetsSync(sessionId, from) |
返回合法目标交点;空交点或对方棋子得到成功的空数组 |
moveXiangqiPieceSync(sessionId, from, to) |
校验并提交一着;失败保持原盘面。调用读局面方法可取得最新棋盘 |
undoXiangqiMoveSync(sessionId) |
撤回最后一着,恢复被吃棋子;每次只撤一着 |
resignXiangqiGameSync(sessionId) |
当前执棋方认输;在释放前仍可读取终局 |
disposeXiangqiGameSync(sessionId) |
释放本局。对已分配的同一编号可重复释放;释放后读取或走棋会报告会话错误 |
XiangqiSnapshot 属性 |
含义 |
sessionId |
当前进程分配的棋局编号。重开一局使用新编号 |
board |
90 个字符串。行 0–9、列 0–8,交点 = 行 × 9 + 列,黑方左上为 0。空交点为 '';车、马、相、士、帅、炮、兵分别用 R/N/B/A/K/C/P,红方大写,黑方小写 |
turn、phase |
turn 为 red 或 black;phase 为 playing 或 ended |
winner、reason |
本地终局胜方为 red 或 black;原因为 mate(将死)、stalemate(困毙)或 resign(认输)。进行中两者均为空字符串 |
inCheck、canUndo |
当前行棋方是否被将军;本局当前是否可以悔棋 |
ply、lastFrom、lastTo |
已走着数及上一着起止交点;开局为 0 着,两个末着坐标均为 -1 |
moves |
按顺序记录每着的 from、to、piece(移动的棋子)、captured(被吃棋子,未吃子为空串) |
房间协议
实现 HTTP 适配器时需让服务端生成下列 state。下例是仅房主入席时的有效快照。后端每次公布新棋谱、席位或终局都应递增 version。
{
"game": "xiangqi", "code": "012345", "version": 1,
"phase": "waiting", "moves": [], "turn": 0,
"winner": null, "reason": "", "connected": [true, false]
}
| 房间字段 |
约定 |
game、code、version |
棋种固定为 xiangqi,房号为六位数字字符串,版本为非负安全整数。已确认的历史着法须保持不变 |
phase、moves |
waiting(等待)、playing(对弈)、ended(终局)。moves 是从红方第一着开始的完整数组,每项含 seat、from、to;等待时为空 |
turn、winner、reason |
红席 0、黑席 1;turn 等于 moves.length % 2。进行中 winner: null、reason: '';终局给出原因,胜方为席位编号,和局为 null |
connected |
长度为 2 的布尔数组,依次是红席、黑席的在线状态 |
transportError?、seatUnavailable? |
可选的传输错误文字和席位失效标志。传输失败、对局输赢分别处理 |
| 自定义传输的入口 |
约定 |
provider.create(game)、provider.join(game, code) |
异步返回席位句柄。句柄含 game、code、自己的 seat 以及最新的 state |
handle.subscribe(listener) |
新局面通知后由订阅者核验,返回取消订阅的函数;取消后释放对应监听 |
handle.move({from,to})、handle.resign()、handle.leave() |
返回 Promise;局面以服务端确认为准。超时仅表示结果未知,先核对最新棋谱或席位 |
onState(view) |
view 包含 phase、code、seat、snapshot、winner、reason、error、connected。席位是数字,snapshot 中棋子的执方仍使用 red、black |
onError(message) 与请求失败 |
订阅到的局面校验失败时调用此回调。由页面发起的操作还需捕获 Promise 拒绝;传输状态也可能出现在 view.error 中 |
onLateLeave() |
可选。退席超时或被重试替换后,仍收到当前席位的成功回执时调用。棋桌已释放,可返回大厅 |
XiangqiRoomTable 方法 |
create()、join(code)、move(from,to)、resign()、leave() 返回 Promise<void>;getTargets(from) 同步返回交点数组,dispose() 同步释放 |
XiangqiRoomProvider、XiangqiRoomHandle、XiangqiRoomRequest、XiangqiRoomSnapshot、XiangqiRoomView 等完整类型见 uni_modules/lizhao-xiangqi/static/host/rooms.d.ts;主题配置类型见 uni_modules/lizhao-xiangqi/static/host/config.d.ts。
错误码说明
| errCode |
含义 |
处理方式 |
| 0 |
成功 |
读取本次回执 |
| 9310001 |
建局选项或交点不合法 |
检查布尔配置,以及 0–89 范围的整数坐标 |
| 9310002 |
会话编号不存在或已释放 |
清除旧编号,按需新建 |
| 9310003 |
本局已结束 |
展示结果,或创建新局 |
| 9310004 |
当前局面不允许该着 |
重新查询所选棋子的合法目标 |
| 9310005 |
悔棋已关闭或没有历史 |
检查 canUndo,禁用悔棋入口 |
房间请求使用 Promise 和 HTTP 状态报告失败;素材配置校验失败会抛出配置错误。排查时可先确认出错的一层,再决定要重新加载素材、重新入座,还是重开本地棋局。
注意事项
平台兼容性
以 HBuilderX 5.34 为集成基线。√ 表示支持,× 表示当前未提供,– 表示尚未确认。传统 uni-app 一栏对应分发的同屏棋规示例,uni-app x 一栏对应完整棋院。标记与发布清单的 uni_modules.platforms 及 dcloudext 对应。DCloud 插件兼容性规范
uni-app(5.34)
| Vue2 |
Vue3 |
Chrome |
Safari |
app-vue |
app-nvue |
Android |
iOS |
鸿蒙 |
| × |
√ |
√ |
– |
– |
× |
– |
– |
– |
| 微信小程序 |
支付宝小程序 |
抖音小程序 |
百度小程序 |
快手小程序 |
京东小程序 |
鸿蒙元服务 |
QQ 小程序 |
飞书小程序 |
小红书小程序 |
快应用华为 |
快应用联盟 |
| × |
× |
× |
× |
× |
× |
× |
× |
× |
× |
× |
× |
uni-app x(5.34)
| Chrome |
Safari |
Android |
iOS |
鸿蒙 |
微信小程序 |
| √ |
– |
– |
– |
– |
× |
其他
| 多语言 |
暗黑模式 |
宽屏模式 |
蒸汽模式 |
| × |
× |
√ |
√ |
| 平台或能力 |
已覆盖的范围 |
| 传统 uni-app |
Vue 3 的选项式示例已通过 H5 构建;Chrome 实际走通开局、合法落点、走棋、悔棋、认输与释放。Vue 2 在 HBuilderX 5.34 的 H5 编译器中无法解析插件内的 interface.uts,当前请选择 Vue 3 |
| uni-app x Web |
Chrome 通过人机、同屏、两端好友房与棋谱回看。宽屏实测 1366×768、780×360,棋盘居中;游戏页面以竖屏为主 |
| uni-app x App 与蒸汽模式 |
Vue 3、TypeScript 的 Vapor 宿主已生成 Android 与 iOS 页面产物。Android 棋规已编成 DEX,iOS 已生成 Swift;Android 真机和 iOS 的 Xcode 联编、真机流程仍待验证 |
| 云端 |
本地玩法可离线。包内无腾讯云、阿里云或支付宝云专用实现;好友房可由外部服务通过上文协议提供 |
使用与维护
| 主题 |
接入说明 |
| 主题校验 |
首次建议用 HTTPS 或 localhost。配置不合法会报错;合法配置的图片下载、大小或摘要校验失败,可重试或继续使用随包画面 |
| 生命周期 |
规则会话和棋谱保存在内存。页面退出时释放;动效偏好、签到印记在本机保存。在线候场秒数表示等待时间 |
| 业务边界 |
正式匹配、竞技棋钟、段位与钱包由业务服务定义。机器人应手和本地签到均不会产生线上成绩或发奖 |
| App 接入 |
首次加入或更新原生 UTS 规则,需要包含本插件的匹配基座。仅更新说明或市场兼容性字段无需重打 |
| 诊断与许可 |
在棋院设置中可复制诊断;失败时可手动选取。自有代码许可见 uni_modules/lizhao-xiangqi/LICENSE,Cocos 与通信脚本依各自随包许可证使用 |
作者系列 UTS 插件
| 入口 |
说明 |
| 当前插件 |
朱砂棋院 · 中国象棋。以上示例和接口均属于此插件 |