主 站 关 于 文 档 下 载 演 示 首 页
快速入门
　　微思象棋播放器（以下简称播放器）基于 Zepto/jQuery 开发，您需要在您的网页上准备一个 DOM 元素，并且调用 vschess.load 方法，播放器便会利用该 DOM 元素创建棋盘。【点击这里查看演示】
<!-- 创建一个空白棋盘 -->
<div class="vschess"></div>
<script>
var chess = new vschess.load(".vschess");
</script>
数据结构
　　播放器最核心的数据是局面数据和节点树。

　　在播放器中，局面数据由一个长度为 256 的数组构成。为了便于观察，我们将其分为 16 行，每行 16 个元素。
　　很显然，棋盘位于数组的中间位置。棋盘外用 0 填充，棋盘内 用 1 填充，如果某个位置有棋子，就用对应棋子填充。
　　17-23（16 进制 11-17） 分别为红方的车马相仕帅炮兵，33-39（16 进制 21-27） 分别为黑方的车马象士将炮卒。
　　使用 16 进制的好处在于，通过位运算可以直接获取棋子红黑和棋子类型。17 >> 4，得到 1，1 即为红方，2 为黑方；17 & 15 得到 1，1 即为车，1-7 分别为车马相（象）仕（士）帅（将）炮兵（卒）。
　　数组第一个元素（数组索引为 0，蓝色部分）表示当前走棋方，1 为红方，2 为黑方，与棋子对应。
　　数组第二个元素（数组索引为 1，绿色部分）表示当前回合数，每次黑方走完棋后，该数值 +1。
　　我们约定，在本文档中，该数组称为局面码，一个完整的对局包含多个局面码。【点击这里查看相关参考资料】

　　在播放器中，着法列表和变着支持由节点树来支撑，每一层节点都包含该着法的相关信息，子节点为其之后的着法。
　　节点的基本格式如下：
根节点：{ fen: "rnbakabnr/9/1c5c1/p1p1p1p1p/9/9/P1P1P1P1P/1C5C1/9/RNBAKABNR w - - 0 1", comment: "开局的注释", next: [], defaultIndex: 0 }
着法节点：{ move: "h2e2", comment: "该着法的注释", next: [], defaultIndex: 0 }
　　其中，fen 为棋谱起始局面的 Fen 串，move 为着法，comment 为相对应的注释，next 为子节点列表，defaultIndex 为默认子节点索引号。
　　假设一个棋局双方走了 20 个回合，共 40 步，那么节点树就应该有 41 层（含起始局面），可以通过 next 来递归。
参数说明
　　使用 vschess.load 创建棋盘时，可以设定一些参数，用以创建不同的棋盘。【点击这里查看演示】
<!-- 创建一个带参数的棋盘 -->
<div class="vschess"></div>
<script>
var chess = new vschess.load(".vschess", {
　　ChineseChar: { Piece: "車馬相仕帥炮兵車馬象士將炮卒" },
　　defaultTab: "edit",
　　turn: vschess.code.turn.round
});
</script>
  • chessData String/Boolean 指定棋盘初始棋谱，默认值：false。当且仅当该参数为 false 时，将使用 DOM 元素中的 HTML 代码作为默认棋谱。
  • style String 棋盘棋子风格，默认值："default"。该参数对应 style 下的目录名。
  • layout String 播放器界面风格，默认值："default"。该参数对应 layout 下的目录名。
  • globalCSS String 全局样式文件路径，默认值：程序路径 + "global.css"。一般不建议您修改该参数，除非您清楚它是如何工作的。
  • currentStep Number 自动展示局面编号，默认值：0。可以定义棋谱加载完成后立即显示第 N 个局面（走了 N - 1 步棋后的局面）。
  • sound Boolean 音效开关，默认值：true。
  • soundStyle String 音效风格，默认值："default"。该参数对应 sound 下的目录名。
  • volume Number 音效音量，默认值：100。范围：0-100。
  • soundPath String 自定义音效目录路径，默认值：""。如果您希望使用 CDN 提供的音效文件，请设定此参数，但要注意跨域问题。
  • IE6Compatible_CustomPieceUrl String/Boolean IE6 自定义棋子图片路径，默认值：false。播放器尽可能兼容低版本 IE 浏览器，但是部分功能无法提供支持。此参数一般无需修改，如需修改请参考【IE 6 兼容性设置】
  • parseType String 强制指定棋谱格式，默认值："auto"，即自动识别。可选值：DhtmlXQ：东萍，pfc：鹏飞，qqnew：QQ 新中国象棋，shijia：象棋世家，pgn：标准 PGN，ccm：中国游戏中心。
  • turn Number 棋盘方向，默认值：0。可选值：0：不翻转，1：左右翻转，2：上下翻转，3：对角旋转。为了便于记忆，播放器还提供了一组常量来用于该参数：vschess.code.turn.none/mirror/reverse/round：none：不翻转，mirror：左右翻转，reverse：上下翻转，round：对角旋转。
  • clickResponse Number 棋子单击事件是否响应，开发对弈功能时会用到此参数，默认值：3。可选值：0：双方不响应，1：仅黑方响应，2：仅红方响应，3：双方响应。为了便于记忆，播放器还提供了一组常量来用于该参数：vschess.code.clickResponse.none/black/red/both：none：双方不响应，black：仅黑方响应，red：仅红方响应，both：双方响应。
  • animationTime Number 走子动画时间，单位毫秒，默认值：200。最小值为 100，100 以下视为 0。
  • playGap Number 播放间隔时间，单位百毫秒（0.1秒），默认值：5。
  • moveFormat String 默认着法格式，默认值："chinese"，即中文格式。可选值：chinese、wxf、iccs。
  • click String 单击事件名称，默认值：PC端："click"；无线端："touchend"。一般无需修改。
  • quickStepOffset Number 快进快退局面数，默认值：10。最小值为 1。
  • defaultTab String 默认打开标签，默认值："comment"，即棋谱注释。可选值：comment：棋谱注释，info：棋局信息，export：导出棋谱，edit：编辑局面，config：棋盘选项。
  • moveTips Boolean 走子提示，默认值：true。
  • saveTips Boolean 保存提示，默认值：false。
  • startTips Array 默认提示信息（起始局面变着处），默认值请查看演示。
  • ChineseChar Object 中文着法所用汉字，默认值请参考下述列表。此参数共分为四个分支，支持单独修改，修改时请注意保持字符的对应关系。
  • ChineseChar.Piece String 棋子所用汉字，默认值："车马相仕帅炮兵车马象士将炮卒"。红在前，黑在后。
  • ChineseChar.Number String 着法所用数字，默认值："一二三四五六七八九１２３４５６７８９"。红在前，黑在后。
  • ChineseChar.PawnIndex String 特殊兵编号所用汉字，默认值："一二三四五一二三四五"。红在前，黑在后。
  • ChineseChar.Text String 其他汉字，默认值："前中后进退平"。
  • cloudApi Object 云服务 URL，默认值请参考下述列表。此参数共分为两个分支，支持单独修改。您可以自行开发云服务，请参考【云服务开发说明】。
  • cloudApi.startfen String 编辑局面推荐列表，默认值："https://www.xiaxiangqi.com/api/cloud/startfen"。
  • cloudApi.savebook String 保存（下载）棋谱，默认值："https://www.xiaxiangqi.com/api/cloud/savebook"。
  • recommendList Array 默认编辑局面用起始局面列表，默认值为常用开局，格式请参考【https://www.xiaxiangqi.com/api/cloud/startfen】中的 data。
通用属性
　　播放器类库中提供了一些常用的通用属性，可供调用，但请不要修改它们的值，否则会造成播放器异常。调用方式统一为：vschess.xxx（xxx 即为属性名称），点击属性名，您可以在控制台中看到对应的值。
  • version 播放器版本号。
  • situation 起始局面的局面码，需要修改时请使用 slice 方法【vschess.situation.slice(0)】克隆一个副本，避免污染原始数据，所有数组类属性（本文档中标红）都应如此做，下同，不再赘述。
  • castle 局面码对应的九宫格判断。
  • b2s 棋子索引号（1-89）到局面码索引号（51-203）转换映射。
  • s2b 局面码索引号（51-203）到棋子索引号（1-89）转换映射。
  • b2i 棋子索引号（1-89）到 iccs 坐标（a0-i9）转换映射。
  • i2b iccs 坐标（a0-i9）到棋子索引号（1-89）转换映射。
  • s2i 局面码索引号（51-203）到 iccs 坐标（a0-i9）转换映射。
  • i2s iccs 坐标（a0-i9）到局面码索引号（51-203）转换映射。
  • n2f 棋子标识（17-23，33-39）到 Fen 字符（RNBAKCPrnbakcp）转换映射。
  • f2n Fen 字符（RNBAKCPrnbakcp）到棋子标识（17-23，33-39）转换映射。
  • chessList 已创建棋盘实体对象列表。
  • defaultFen 起始局面 Fen 串。
  • blankFen 空白棋盘 Fen 串。
  • code 状态参数语义化，请参考【参数说明】。
公共函数
　　播放器公共函数是开放的函数库，无需创建棋盘即可使用。调用方式统一为：vschess.xxx(param1, param2, ...)（xxx 即为函数名称）。
  • load(selector, config) 创建一个棋盘。selector 为选择器，必须，字符串或 DOM 对象均可；config 为自定义参数，可选，请参考【参数说明】。
　　该函数支持以下两种调用方式：
var chess = new vschess.load(selector, config);
　　此种方式下，将为选择器集合中的第一个未创建棋盘的元素创建棋盘，返回棋盘实体对象，可以直接调用实体方法。
var chessList = vschess.load(selector, config);
　　此种方式下，将为选择器集合中的所有未创建棋盘的元素创建棋盘，返回棋盘实体对象集合，允许直接调用实体方法，方法将作用于该集合中的所有棋盘实体对象。
  • dataToInfo(chessData, parseType) 从棋谱中抽取棋局信息。chessData 为棋谱内容，必须，字符串；parseType 为棋谱格式，可选，默认为 auto，可选值：auto：自动识别，pfc：鹏飞，DhtmlXQ：东萍，pgn：标准 PGN。
  • dataToInfo_PFC(chessData) 从鹏飞棋谱中抽取棋局信息。chessData 为棋谱内容，必须，字符串。
  • dataToInfo_PGN(chessData) 从标准 PGN 棋谱中抽取棋局信息。chessData 为棋谱内容，必须，字符串。
  • dataToInfo_DhtmlXQ(chessData) 从东萍棋谱中抽取棋局信息。chessData 为棋谱内容，必须，字符串。
  • dataToNode(chessData, parseType) 将棋谱转换为节点树。chessData 为棋谱内容，必须，字符串；parseType 为棋谱格式，可选，默认为 auto，可选值：auto：自动识别，pfc：鹏飞，DhtmlXQ：东萍，pgn：标准 PGN，qqnew：QQ 新中国象棋，shijia：象棋世家，ccm：中国游戏中心。
  • dataToNode_PFC(chessData) 将鹏飞棋谱转换为节点树。chessData 为棋谱内容，必须，字符串。
  • dataToInfo_PGN(chessData) 将标准 PGN 棋谱转换为节点树。chessData 为棋谱内容，必须，字符串。
  • dataToNode_DhtmlXQ(chessData) 将东萍棋谱转换为节点树。chessData 为棋谱内容，必须，字符串。
  • dataToNode_QQNew(chessData) 将 QQ 新中国象棋棋谱转换为节点树。chessData 为棋谱内容，必须，字符串。
  • dataToNode_ShiJia(chessData) 将象棋世家棋谱转换为节点树。chessData 为棋谱内容，必须，字符串。
  • dataToNode_CCM(chessData) 将中国游戏中心棋谱转换为节点树。chessData 为棋谱内容，必须，字符串（中国游戏中心 CCM 格式为二进制格式，需要将“文本”原样输入）。
  • stepListToNode(fen, stepList) 将节点 iccs 着法列表转换为节点树。fen 为起始 Fen 串，可选，但是必须占参数位，字符串；stepList 为着法列表，着法集合数组，如【["h2e2", "h9g7"]】，可选。
  • limit(number, min, max, default) 将整数限制在指定范围内。number 为输入的数，min 为最小值，max 为最大值，default 为 number 无效时的默认值。
  • RegExp() 新建一组正则表达式，全新的正则可以避免 lastIndex 冲突。共有以下九个正则表达式：
  • FenLong 长 Fen 串匹配，可直接使用。
  • FenShort 短 Fen 串匹配，可直接使用。
  • Chinese 中文着法匹配，可直接使用。
  • Node 节点 iccs 匹配，可直接使用。
  • ICCS ICCS 着法匹配，可直接使用。
  • WXF WXF 着法匹配，可直接使用。
  • QQNew QQ 新中国象棋格式匹配，可直接使用。
  • ShiJia 象棋世家格式匹配，播放器内部使用，不推荐调用。
  • Pawn 特殊兵东萍表示法匹配，播放器内部使用，不推荐调用。
  • fenChangePlayer(fen) Fen 串改变走棋方，即红黑转换。fen 为需要改变的 Fen 串，必须。返回更改后的 Fen 串。
  • fenToSituation(fen) 根据 Fen 串生成局面码。fen 为 Fen 串，必须。返回 Fen 串对应的局面码。
  • situationToFen(situation) 根据局面码生成 Fen 串。situationToFen 为局面码，必须。返回局面码对应的 Fen 串。
  • turnFen(fen) Fen 串左右镜像。fen 为需要镜像的 Fen 串，必须。返回镜像后的 Fen 串。
  • roundFen(fen) Fen 串对角旋转。fen 为需要旋转的 Fen 串，必须。返回旋转后的 Fen 串。
  • turnMove(move) iccs 节点着法左右镜像。move 为需要镜像的着法，必须。返回镜像后的着法。
  • roundMove(move) iccs 节点着法对角旋转。move 为需要旋转的着法，必须。返回旋转后的着法。
  • turnWXF(move) WXF 着法左右镜像。move 为需要镜像的着法，必须。返回镜像后的着法。注意：此函数不可以用来转换特殊兵着法。
  • countPieceLength(fen/situation) 统计 Fen 串或局面码中棋子数量。fen/situation 为 Fen 串或局面码，必须。返回棋子数量。
  • compareFen(start, end, format) 根据前后 Fen 串计算着法。start 为走棋前 Fen 串，必须；end 为走棋后 Fen 串，必须；format 为着法格式，可选，默认为 chinese，可选值：chinese、wxf、iccs。
  • guid() 随机生成一个 GUID。
  • checkThreat(fen/situation) 根据 Fen 串或局面码判断此时是否被将军。fen/situation 为 Fen 串或局面码，必须。返回 true/false。
  • legalMoveList(fen/situation) 根据 Fen 串或局面码生成所有合法着法。fen/situation 为 Fen 串或局面码，必须。返回 Array。Array 长度为 0 时意味着被将杀或困毙，结合 checkThreat 可以区分将杀和困毙。
  • checkFen(fen) Fen 串合法性检查。fen 为需要检查的 Fen 串，必须。返回 Array（错误列表）。Array 长度为 0 时意味着 Fen 串是合法有效的。
  • Chinese2Node(move, fen) 中文着法转换为节点 iccs。move 为需要转换的中文着法，必须；fen 为与之相对应的 Fen 串，必须（不填视为标准开局）。返回 { move: "节点 iccs", movedFen: "走子之后的 Fen 串" }。当返回值中 move 为 none 时，表示着法或 Fen 串出错。
  • WXF2Node(move, fen) WXF 着法转换为节点 iccs。move 为需要转换的 WXF 着法，必须；fen 为与之相对应的 Fen 串，必须（不填视为标准开局）。返回 { move: "节点 iccs", movedFen: "走子之后的 Fen 串" }。当返回值中 move 为 none 时，表示着法或 Fen 串出错。
  • ICCS2Node(move, fen) ICCS 着法转换为节点 iccs。move 为需要转换的 ICCS 着法，必须；fen 为与之相对应的 Fen 串，必须（不填视为标准开局）。返回 { move: "节点 iccs", movedFen: "走子之后的 Fen 串" }。当返回值中 move 为 none 时，表示着法或 Fen 串出错。
  • ICCS2Node_NoFen(move) ICCS 着法直接转换为节点 iccs。move 为需要转换的 ICCS 着法，必须。返回节点 iccs 着法。
  • stepList2nodeList(moveList, startFen) 着法列表转换为节点 iccs 列表。moveList 为需要转换的着法列表，必须；startFen 为起始局面 Fen 串，必须（不填视为标准开局）。返回 Array，即节点 iccs 着法列表，其中结果集第一个元素为起始局面 Fen 串。moveList 参数亦可以将起始局面 Fen 串作为输入列表第一个元素传入。
  • moveListToData_PGN(moveList, startFen, commentList, infoList) 生成标准 PGN 格式棋谱。moveList 为着法列表，必须；startFen 为起始局面 Fen 串，必须（不填视为标准开局）；commentList 为注释列表，数组下标要与着法下标相对应；infoList 为棋谱信息列表。返回 PGN 文本。
  • moveListToText(moveList, startFen, commentList, infoList) 生成文本格式棋谱。moveList 为着法列表，必须；startFen 为起始局面 Fen 串，必须（不填视为标准开局）；commentList 为注释列表，数组下标要与着法下标相对应；infoList 为棋谱信息列表。返回棋谱文本。
  • nodeToData_DhtmlXQ(nodeData, infoList, isMirror) 棋谱节点树转换为东萍 DhtmlXQ 格式棋谱。nodeData 为棋谱节点树，必须；infoList 为棋谱信息列表，可选；isMirror 为是否生成镜像棋谱开关，可选 true/false，默认值：false。返回棋谱文本。
  • turn_DhtmlXQ(chessData) 生成东萍 DhtmlXQ 格式棋谱的镜像棋谱。chessData 为原始棋谱数据，必须。返回镜像后的棋谱。
  • nodeToData_PengFei(nodeData, infoList, result, isMirror) 棋谱节点树转换为鹏飞 PFC 格式棋谱。nodeData 为棋谱节点树，必须；infoList 为棋谱信息列表，可选；result 为对局结果，可选；isMirror 为是否生成镜像棋谱开关，可选 true/false，默认值：false。返回棋谱文本。
  • turn_PengFei(chessData) 生成鹏飞 PFC 格式棋谱的镜像棋谱。chessData 为原始棋谱数据，必须。返回镜像后的棋谱。
  • moveListToData_QQ(moveList, isMirror) 着法列表转换为 QQ 新中国象棋 CHE 格式棋谱。moveList 为着法列表，必须；isMirror 为是否生成镜像棋谱开关，可选 true/false，默认值：false。返回棋谱文本。该格式不支持残局展示，故传入的着法列表必须以标准开局为其实局面（参数不需要含 Fen 串）。
  • Node2Chinese(move, fen) 节点 iccs 转换为中文着法。move 为需要转换的节点 iccs，必须；fen 为与之相对应的 Fen 串，必须（不填视为标准开局）。返回 { move: "中文着法", movedFen: "走子之后的 Fen 串" }。当返回值中 move 为 无效着法 时，表示节点 iccs 或 Fen 串出错。
  • Node2WXF(move, fen) 节点 iccs 转换为 WXF 着法。move 为需要转换的节点 iccs，必须；fen 为与之相对应的 Fen 串，必须（不填视为标准开局）。返回 { move: "WXF 着法", movedFen: "走子之后的 Fen 串" }。当返回值中 move 为 None 时，表示节点 iccs 或 Fen 串出错。
  • Node2ICCS(move, fen) 节点 iccs 转换为 ICCS 着法。move 为需要转换的节点 iccs，必须；fen 为与之相对应的 Fen 串，必须（不填视为标准开局）。返回 { move: "ICCS 着法", movedFen: "走子之后的 Fen 串" }。
  • Node2ICCS_NoFen(move) 节点 iccs 直接转换为 ICCS 着法。move 为需要转换的节点 iccs，必须。返回 ICCS 着法。
  • nodeList2moveList(moveList, startFen, format, options, mirror) 节点 iccs 列表转换为着法列表。moveList 为需要转换的节点 iccs 列表，必须；startFen 为起始局面 Fen 串，必须（不填视为标准开局）；format 为目标格式，可选值：chinese wxf iccs，可选，默认值：chinese；options 为自定义汉字，参考格式请参考 vschess.defaultOptions，可选；mirror 为是否生成镜像棋谱开关，可选 true/false，默认值：false。返回 Array，即对应目标格式的着法列表，其中结果集第一个元素为起始局面 Fen 串。moveList 参数亦可以将起始局面 Fen 串作为输入列表第一个元素传入。
  • WXF2ECCO(wxfList) 根据 WXF 格式着法列表识别 ECCO 开局类型。wxfList 为 WXF 着法列表，必须。返回 { ecco: "ECCO 编号", opening: "开局名称", variation: "变例名称" }
  • ECCOIndex2Name(ecco) ECCO 编号转换为开局名称。ecco 为 ECCO 开局编号，必须。返回 开局名称 或 开局名称#变例名称。
实体方法
　　播放器实体方法需要创建棋盘才可以使用，每个棋盘有自己对应的实体方法，棋盘之间互相独立，互不冲突。调用方式统一为：chess.xxx(param1, param2, ...)（xxx 即为方法名称）。
  • unload() 卸载当前棋盘，但不恢复原有的事件。
  • resetDPR() 重置棋盘的 DPR。
  • isR/isB(index, step) 检查指定局面号下指定位置是否为红方/黑方棋子。index 为棋子索引号，范围 0-89，必须；step 为局面编号，范围 0-(局面列表长度-1)，可选，默认值：当前局面号。返回 true/false。
  • isN(index, step) 检查指定局面号下指定位置是否为无棋子。index 为棋子索引号，范围 0-89，必须；step 为局面编号，范围 0-(局面列表长度-1)，可选，默认值：当前局面号。返回 true/false。
  • isPlayer/isEnermy(index, step) 检查指定局面号下指定位置是否为己方/敌方棋子。index 为棋子索引号，范围 0-89，必须；step 为局面编号，范围 0-(局面列表长度-1)，可选，默认值：当前局面号。返回 true/false。当前走棋方为己方。
  • getLegalByStartPieceIndex(startIndex) 获取指定起始棋子的所有合法目标坐标。index 为棋子索引号，范围 0-89，必须。返回合法目标点列表，数据范围：0-89。
  • clearPiece(index) 移除指定位置的棋子。index 为棋子索引号，范围 -1-89，-1表示用于走子动画的棋子（下同，不在赘述），必须。返回棋盘实体。
  • clearSelect(index) 移除指定位置棋子的选中状态。index 为棋子索引号，范围 -1-89，必须。返回棋盘实体。
  • clearBoard(index) 移除指定位置棋子及棋子的选中状态。index 为棋子索引号，范围 -1-89，必须。返回棋盘实体。
  • setCommentByStep(step) 将指定局面号的注解填充到棋谱注解区域。step 为局面编号，范围 0-(局面列表长度-1)，可选，默认值：当前局面号。返回棋盘实体。
    • 　　　　
© 2009- 微思象棋播放器 Margin.Top 版权所有 津ICP备2023003610号-3