給你的WP應用加上幫助文件

jpss發表於2014-08-28

背景

這算是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, 作為ListBox的ListItemTemplate;
  5. 將步驟2得到的列表作為步驟四ListBox的源.

呼叫方式

一些ok, 最方便的呼叫方式, 當然是封裝好, 直接一個函式搞定:

//本地文件
CuteHelper.Helper.NavigateCutePage("Contents/home.txt"); 

//線上文件
CuteHelper.Helper.NavigateCutePage("http://www.cnblogs.com/");

效果

給你的WP應用加上幫助文件 給你的WP應用加上幫助文件

給你的WP應用加上幫助文件 給你的WP應用加上幫助文件

程式碼

文字的解析和方法都存放在CuteHelper.dll中, 因為其原始碼都是wp7時代寫的, 剛才我用vs2013試了下, 發現編譯起來還需要修改不少東西, 所以為了能讓demo執行, 暫時就不扔具體原始碼了, 有興趣同學自行反編譯查閱.

專案檔案地址: http://files.cnblogs.com/jpss/20140828-TestHelpPage.zip

結語

拋磚引玉, 希望能看到大家給出更好的實現. 多思考, 多動手.

唉, 時間不多, 趕緊休息~

相關文章