背景

这算是Windows Phone编程回顾续篇, 接着给大家聊WP开发经验. 在开发了数个WP应用并发布后, 陆续收到很多反馈邮件, 其中接近一半的邮件是在问"某某功能有没有?" "某某设置在哪儿?".

作为开发者, 面对这种情况, 首先考虑我的设计是否有问题? 为什么他们没有发现如何使用? 其次..是否应该提供一个像样的帮助文档呢?

调研

为了查看其他应用如何提供帮助文档, 我下载了一些热门和某些专业性强的app, 大概有以下类型:

  • 简单粗暴的MessageBox类, 常见于一些个人开发者, 内容往往在一页~三页, 除去一些闷骚的程序员自嘲语句和版权,版本信息, 有用信息很少;
  • 单独帮助页: 所有信息汇聚一页, 冗长拖沓, 常见于一些信息类app, 估计是复用了显示文章的UserControl;
  • 多个页面, 分门别类, 带有折叠或者反馈界面, 层次清晰, 交互爽快. 常见于大公司的通讯类,游戏类. 比如QQ;

整体需求和思路

当时我正在开发手指画画, 这个App有较强的专业性, 一些功能需要详细的帮助说明才能充分使用. 所以结合上面的调研, 大概总结了帮助文档需要实现的功能:

  • 帮助首页: 包含分类链接;
  • 页面分主标题/文档标题h2-h5, 包含链接,按钮;
  • 正文显示
  • 一些特殊功能:比如查看市场更新, 发送反馈邮件;
  • 支持显示图片

需求明确后, 开始思考文档格式, 有以下备选:

  • 直接写在xaml页面上: 简单粗暴, 可维护性差, 不利于在线升级;
  • xml/json格式: 格式比较严格, 容易出错, 编写稍微费时, 后续还有解析并显示开发工作;
  • markdown: 格式简单, 但现有库只能生成HTML, 嵌在WeiBrowser中稍微有些山寨, 而且速度不佳;
  • 自定义格式: 自定一些简单规则, 并生成Model, 通过xaml绑定, 显示在xaml页面中, 工作量稍大, 但可以完全自定义, 实现自己需求.

想到自己后续可能还会开发更多的应用, 所以有必要搞定一个可扩展, 可在线升级, 易于编写的解决方案, 最终我选择了"自定义格式", 并列举了所有想到的情况.

详细设计

格式

采用类似markdown语法, 但更加易读的格式. 因为我更多从事web开发, 所以语法设计上倾向于html和css风格:

[h1] 一级标题
[h2] 二级标题
[h3] 三级标题 一段纯文本, 不需要任何特殊标记. [text] {color:#ff0000} {fontsize:50} 一段带有格式的文本, 在大括号内写样式控制;
[btn] {url:http://www.cnblogs.com/} {content:查看博客园首页HTML源码} 高宽自定义的图片
[img] http://static.cnblogs.com/images/logo_small.gif 固定高宽的图片,可以避免图片加载产生抖动
[img] {img: http://static.cnblogs.com/images/logo_small.gif} {width:100} {height:200} 这是一段很长的测试文本这是一段很长的测试文本这是一段很长的测试文本这是一段很长的测试文本这是一段很长的测试文本这是一段很长的测试文本这是一段很长的测试文本这是一段很长的测试文本这是一段很长的测试文本这是一段很长的测试文本这是一段很长的测试文本这是一段很长的测试文本 带有链接的图片
[img] {href:http://static.cnblogs.com/images/logo_small.gif} {img:http://static.cnblogs.com/images/logo_small.gif} 显示一个应用下载
[app] {appid: 7e0f3d2f-890a-4818-bbbd-6ee57689325e} {title:下载手指画画} {content:应用介绍应用介绍应用介绍应用介绍应用介绍应用介绍应用介绍应用介绍应用介绍} 一个链接
[link] {content:你好} {href:https://dev.windowsphone.com/a/132123/devCenterLogo.png} [code] 这是一段和系统样式符合的文字 [email] {content:发送邮件} {href:xxx@xxx.com} {title:邮件标题} {body:邮件内容} [email] 发送邮件 [review] 给个好评,亲 [app] {img:http://cdn.marketplaceimages.windowsphone.com/v8/images/674083d6-0047-47d7-a5eb-01164dfe381e?imageType=ws_icon_small} {title:蜂鸟浏览器} 甚至可以嵌入一个浏览器页面
[browser] {href:http://www.baidu.com}{height:300} [xxx] 一段不识别的文本

一些约定

  1. 开头[xxx]表示这款文本类型, 如果是正文, 可以省去;
  2. 属性通过{key:value}形式描述, 通用的属性有{content:内容}, {href:链接}, {url:链接到帮助页}, {color:前景色}, {fontsize:字体大小};
  3. 链接支持本地链接/外部链接/xaml页面;
  4. 帮助文档如果在应用内部, 则以内容类型编译;
  5. 如果帮助文档为在线地址, 则设置'url'属性, 例如{url:http://www.cnblogs.com/}, 则将url:http://www.cnblogs.com/作为在线帮助文本的地址;

具体实现

流程

  1. 根据上面的规范定义一些get``set公共属性, 使其可以供xaml绑定即可, 比如类名为CutePageItemTemplateSelector;
  2. 解析输入文本, 得到List<CutePageItemTemplateSelector>类型的列表;
  3. 实现类CutePageItemTemplateSelector, 继承DataTemplateSelector实现动态选择DataTemplate, 让不同类型的元素显示不同样式;
  4. xaml中定义各种元素的DataTemplate, 作为ListBoxListItemTemplate;
  5. 将步骤2得到的列表作为步骤四ListBox的源.

调用方式

一些ok, 最方便的调用方式, 当然是封装好, 直接一个函数搞定:

//本地文档
CuteHelper.Helper.NavigateCutePage("Contents/home.txt"); //在线文档
CuteHelper.Helper.NavigateCutePage("http://www.cnblogs.com/");

效果

代码

文本的解析和方法都存放在CuteHelper.dll中, 因为其源码都是wp7时代写的, 刚才我用vs2013试了下, 发现编译起来还需要修改不少东西, 所以为了能让demo运行, 暂时就不扔具体源码了, 有兴趣同学自行反编译查阅.

项目文件地址: http://files.cnblogs.com/jpss/20140828-TestHelpPage.zip

结语

抛砖引玉, 希望能看到大家给出更好的实现. 多思考, 多动手.

唉, 时间不多, 赶紧休息~

给你的WP应用加上帮助文档的更多相关文章

  1. Kotlin开发语言文档(官方文档)-- 目录

    开始阅读Kotlin官方文档.先上文档目录.有些内容还未阅读,有些目录标目翻译还需琢磨琢磨.后续再将具体内容的链接逐步加上. 文档链接:https://kotlinlang.org/docs/kotl ...

  2. 6.JAVA基础复习——JAVA中文档注释与帮助文档的生成

    java中的文档注释:用于说明该类的功能作用方便他人使用关键词前需要加@符 用于类的注释 @author name 作者 @version v1.0 版本 …… 用于函数的注释 @param para ...

  3. 洗礼灵魂,修炼python(21)--自定义函数(2)—函数文档,doctest模块,形参,实参,默认参数,关键字参数,收集参数,位置参数

    函数文档 1.什么是函数文档: 就是放在函数体之前的一段说明,其本身是一段字符串,一个完整的函数需要带有函数文档,这样利于他人阅读,方便理解此函数的作用,能做什么运算 2.怎么查看函数文档: func ...

  4. 让Myeclipse自动生成的get set方法 自动加上文本注释,并且注释内容包含字段中我们加的文档注释

    在进行编码写实体类的时候发现,一个实体类有好多的字段要进行注释,他们都是私有的不能直接访问,我们在写的时候加入的文档注释也起不到效果,但是自动生成的get,set方法的文档注释有不符合我们要求(没有包 ...

  5. Hibernate配置文档详解

    Hibernate配置文档有框架总部署文档hibernate.cfg.xml 和映射类的配置文档 ***.hbm.xml hibernate.cfg.xml(文件位置直接放在src源文件夹即可) (在 ...

  6. POI加dom4j将数据库的数据按一定格式生成word文档

    一:需求:将从数据库查处来的数据,生成word文档,并有固定的格式.(dom4j的jar包+poi的jar包) 二:解决:(1)先建立固定格式的word文档(2007版本以上),另存成为xml文件,作 ...

  7. hugo主题文档-manpassant

    +++ date="2020-10-17T10:32:00+08:00" title="hugo主题文档manpassant" tags=["hugo ...

  8. 注释生成Api文档

    1.开发背景 最近一直在写dubbo接口,以前总是用word文档写接口描述然后发给别人.现在太多了,而且跟别人对接联调的人家急着用,根本没时间去写word文档.那就想想怎么用doc文档注释自动生成接口 ...

  9. PHP 高级编程(1/5) - 编码规范及文档编写

    PHP 高级程序设计学习笔记20140612 软件开发中的一个重要环节就是文档编写.他可以帮助未来的程序维护人员和使用者理解你在开发时的思路.也便于日后重新查看代码时不至于无从下手.文档还有一个重要的 ...

随机推荐

  1. Java代码注释

    单行注释: 选中代码,按下ctrl+/ 一条代码单行注释:选中一条代码按下ctrl+/,则为一条代码单行注释: 多条代码单行注释:选中多条代码按下ctrl+/,则为多条代码单行注释: 取消注释:对已经 ...

  2. CentOS 7.x下升级Python版本到3.x系列(新老版本共存)

    由于python官方已宣布2.x系列即将停止支持,为了向前看,我们升级系统的python版本为3.x系列服务器系统为当前最新的CentOS 7.4 1.安装前查看当前系统下的python版本号 # p ...

  3. 【Spark】源码分析之SparkContext

    一.概述 SaprkContext非常重要,是Spark提交任务到集群的入口 SparkContext中没有main方法,在SparkContext主构造器中,主要做一下四件事情: 1. 调用crea ...

  4. GitLab 基本操作

    登录 在浏览其中输入http://192.168.3.11:8888 如图1登录界面.   图1 注:第一次新增用户,会发送修改密码链接到用户的邮箱中,用户会收到如图2邮件. 图2 2. 修改密码 点 ...

  5. Python交换两个变量值的函数

    方法1:(错误) def func(a,b): a,b = b,a a = 1 b = 2 func(a,b) print(a," ",b) 方法2:(正确) def func(a ...

  6. vuetify.js框架 下拉框数据改变DOM原数据未清除

    今天遇到一个奇怪的bug 需求很简单,就是将“引擎能力”下拉框选中的值作为筛选条件传入到“样本类型”下拉框中,默认“样本类型”下拉框显示所有样本类型 看图: 如图所示,功能很简单. 其实还是对vuet ...

  7. war2 洛谷模拟赛day2 t3 状压

    (new )   war2 题解:总体数据而言,我们很容易想到着就是DP啊,我们DP数组,用状态压缩,代表有那些点已经被占领过了,代表上一次我占的是那个.对于每一次状态转移,若当前我们要占领的Port ...

  8. ChipScope Pro Inserter - "ERROR:NgdBuild:924 - bidirect pad net '<oDRAM0_A>' is driving non-buffer primitives

    解决方案: Using a IOBUF signal as a trigger for the ILA Inserter flow will cause a NGDBuild error. These ...

  9. 成都Uber优步司机奖励政策(3月17日)

    滴快车单单2.5倍,注册地址:http://www.udache.com/ 如何注册Uber司机(全国版最新最详细注册流程)/月入2万/不用抢单:http://www.cnblogs.com/mfry ...

  10. CLR via c#读书笔记八:泛型

    1.定义泛型类型或方法时,为类型指定的任何变量(比如T)都称为类型参数.使用泛型类型或方法时指定的具体数据类型称为类型实参. 2.System.Collections.Concurrent命名空间提供 ...