背景

这算是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. pt-online-schema-change在线修改表结构

    工具简介 pt-osc模仿MySQL内部的改表方式进行改表,但整个改表过程是通过对原始表的拷贝来完成的,即在改表过程中原始表不会被锁定,并不影响对该表的读写操作.首先,osc创建与原始表相同的不包含数 ...

  2. 使用js实现单向绑定

    详细解释单向绑定 参考资料 MDN addEventListener()定义与用法 <!DOCTYPE html> <html lang="en"> < ...

  3. hadoop生态搭建(3节点)-16.elk配置

    # ==================================================================ELK环境准备 # 修改文件限制 # * 代表Linux所有用户 ...

  4. python学习——函数进阶

    首先来看下面这个函数. def func(x,y): bigger = x if x > y else y return bigger ret = func(10,20) print(ret) ...

  5. 前端css之float浮动

    浮动的准则,先找前一个块标签,在确认有否清除浮动的条件或者是距离的情况下,如果这一行能摆得下,就继续紧贴前一个标签 如果摆不下,就会另起一行 浮动只有左边和右边 如果是块标签,设置浮动,先把displ ...

  6. python教程(一)·命令行基本操作

    先来了解下 "命令提示符". 等等?!既然本篇文章标题是"命令行基本操作",那怎么又说到"命令提示符"去了呢?客官莫要急,且听我说 命令提示 ...

  7. ERROR oslo_service.service PlacementNotConfigured 解决办法

    PlacementNotConfigured: This compute is not configured to talk to the placement service 原因:官方文档中遗漏了- ...

  8. Java设计模式(18)——行为模式之迭代子模式(Iterator)

    一.概述 概念 UML简图 // Aggregate:聚集(集合) 角色 抽象迭代子:定义遍历元素所需要的接口 具体迭代子:实现抽象迭代子接口,保持游标 聚集/具体聚集:定义/实现创建迭代子对象的接口 ...

  9. Ruby on Rails Tutorial 第2版 学习笔记

    Ruby on Rails Tutorial 第2版 在线阅读:http://railstutorial-china.org/ 英文版:http://ruby.railstutorial.org/ru ...

  10. elasticsearch安装中文分词器

    1. 分词器的安装 ./bin/elasticsearch-plugin install https://github.com/medcl/elasticsearch-analysis-ik/rele ...