應用程式 API
AppAPI 允許使用者在 FormEngine 和 DMView 中使用不同方法從應用程式載入系統元資料。它提供對各種資料鍵的存取，以從應用程式擷取特定資訊。
在 xlsform 中，您可以使用 pulldata() 函數搭配以下語法：
'app-api'：此關鍵字通知 FormEngine 從應用程式 API 載入資料。'data-key'：這是您想從應用程式 API 載入的資料鍵。- 如果資料鍵無效或不受支援，計算將返回「n/a」。
以下是您可以與應用程式 API 搭配使用的支援資料鍵：
osPlatform：返回當前作業系統名稱（Android 或 iOS）和作業系統版本。網頁平台將返回空值。
appPlatform：返回應用程式平台名稱，即 rtSurvey。
appVersion：返回應用程式的版本名稱。
getDisplayWidth：返回裝置螢幕寬度（以像素為單位）。
getDisplayHeight：返回裝置螢幕高度（以像素為單位）。
getScreenSize：返回裝置螢幕大小（以英寸為單位）。
projectCode：返回使用者登入的網站當前專案代碼。
projectURL：返回使用者登入的網站當前專案 URL。預設/後備值為空文字（""）。
startingPoint：返回啟動表單的點的路徑。請參閱「表單起始點」以取得更多詳細資訊。
serverTime：返回伺服器上日期和時間的最佳可用近似值。
user.[attribute]：根據指定的屬性鍵返回當前使用者屬性。請參閱「使用者屬性」表以取得可用的屬性鍵。
將以下屬性鍵與 pulldata() 參數中的 “user.” 結合，以擷取當前使用者資訊。例如，使用 user.username、user.email 等。
| 屬性鍵 | 說明 |
|---|---|
| username | 使用者的使用者名稱 |
| name | 使用者的全名 |
| staffCode | 使用者的員工代碼 |
| phone | 使用者的電話號碼 |
| 使用者的電子郵件地址 | |
| description | 使用者資訊中的說明文字 |
| organization_id | 使用者所屬的組織 ID |
| organization_name | 使用者所屬的組織名稱 |
| team_id | 使用者所屬的團隊 ID |
| supervisor_id | 使用者督導的 ID |
| is_supervisor | 如果使用者是督導則為 1，否則為 0 |
instancePath：返回當前實例資料夾路徑。
appLanguage：返回應用程式設定中設定的當前應用程式語言（例如 vi、en）。
openArgs.[attribute]：返回從 ActionButton（act_fill_form、act_get_instance）傳遞的開啟表單參數。預設/後備值為空文字（""）。
primaryAppColor：擷取應用程式的主要顏色。
使用範例
儲存調查員的使用者名稱和組織
| type | name | label | calculation |
|---|---|---|---|
| calculate | enumerator_name | pulldata('app-api', 'user.name') | |
| calculate | enumerator_org | pulldata('app-api', 'user.organization_name') | |
| calculate | enumerator_email | pulldata('app-api', 'user.email') |
在備注標籤中使用這些以進行稽核：
note | interviewer_info | Interviewer: ${enumerator_name} (${enumerator_org})
裝置和螢幕資訊
| type | name | label | calculation |
|---|---|---|---|
| calculate | device_platform | pulldata('app-api', 'osPlatform') | |
| calculate | app_ver | pulldata('app-api', 'appVersion') | |
| calculate | screen_w | pulldata('app-api', 'getDisplayWidth') |
對於疑難排解很有用：將 device_platform 和 app_ver 與您的資料一起匯出，以確定每次提交使用了哪個裝置版本。
使用伺服器時間代替裝置時間
裝置時鐘可能不準確。使用 serverTime 獲取更可靠的時間戳：
| type | name | label | calculation |
|---|---|---|---|
| calculate | server_ts | pulldata('app-api', 'serverTime') |
基於使用者角色的條件邏輯
僅向督導顯示督導專用部分：
| type | name | label | relevant |
|---|---|---|---|
| calculate | is_supervisor | pulldata('app-api', 'user.is_supervisor') | |
| begin_group | supervisor_section | Supervisor review | ${is_supervisor} = '1' |
| text | supervisor_notes | Supervisor notes | |
| end_group |
從操作按鈕傳遞參數
當表單從帶有自訂參數的 act_fill_form 操作按鈕啟動時：
| type | name | label | calculation |
|---|---|---|---|
| calculate | passed_hh_id | pulldata('app-api', 'openArgs.household_id') | |
| calculate | passed_task | pulldata('app-api', 'openArgs.task_code') |
操作按鈕必須傳遞帶有匹配鍵（例如 household_id、task_code）的參數。
使用專案資訊
| type | name | label | calculation |
|---|---|---|---|
| calculate | project | pulldata('app-api', 'projectCode') | |
| calculate | project_url | pulldata('app-api', 'projectURL') |
注意事項
- 所有
pulldata('app-api', ...)呼叫在表單開啟時評估，在會話期間不會動態重新評估（serverTime和now()除外）。 - 如果鍵不受支援或資料不可用，函數返回
'n/a'（不是空字符串——使用!= 'n/a'而不是!= ''進行測試）。 openArgs值只有在表單從操作按鈕啟動時才可用；否則返回空字符串。