Widgets
ฝังเครื่องมือของแพลตฟอร์ม เช่น แผนที่ ฟอร์ม และตัวเลือกรายการ ลงในหน้าเว็บของคุณด้วย iframe
widget คือหน้าเว็บเล็ก ๆ ของแพลตฟอร์มที่คุณฝังในหน้าของคุณด้วย iframe แล้วคุยกับมันด้วย postMessage แอปของแพลตฟอร์มเองก็ใช้วิธีนี้ เช่น แผนที่ใน Data Studio และกล่องแชร์ใน Drive
widget ไม่ใช่ widget บนแดชบอร์ดของ App Studio ตัวนั้นคือแผนภูมิหรือตารางบนผืนงาน ดู App Studio
URL และพารามิเตอร์
widget ทุกตัวอยู่ที่ <site>/widgets/<ชื่อ> พารามิเตอร์อยู่ใน query string
| พารามิเตอร์ | ค่า |
|---|---|
_credential_type | bearer-token หรือ api-key ไม่ใส่ widget แสดง 401 |
_token | bearer token เมื่อเป็น bearer-token |
_api_key | API key เมื่อเป็น api-key |
_origin | origin ของหน้าที่ฝัง เช่น https://app.example.com widget ส่งข้อความกลับไปที่ origin นี้เท่านั้น |
_message_token | ข้อความสุ่มที่คุณสร้าง ใช้ยืนยันว่าข้อความมาจากคู่เดียวกัน |
_locale | th หรือ en |
_theme | light หรือ dark |
พารามิเตอร์ของแต่ละ widget (เช่น item_id) อยู่ในหน้าของ widget นั้น
token หรือ API key อยู่ใน URL ของ iframe ใช้ bearer token อายุสั้น (คู่มือ API) และอย่าใช้ API key ที่มีสิทธิ์กว้างในหน้าเว็บสาธารณะ
เกตเวย์ไม่รับชื่อผู้ใช้และรหัสผ่าน ดังนั้น _credential_type=basic-auth ใช้ไม่ได้
ข้อความ
ทุกข้อความเป็นอ็อบเจกต์ { messageToken, action, payload } ฝั่งที่รับต้องตรวจ origin และ messageToken ก่อนใช้
| action | ทิศทาง | ความหมาย |
|---|---|---|
ready | widget ถึงหน้าของคุณ | widget โหลดเสร็จและรับข้อความได้ มีเฉพาะ widget ที่รับ post-widget-parameters ได้แก่ map, filter-builder และ user-and-group-picker |
post-widget-parameters | หน้าของคุณถึง widget | ส่งค่าที่ยาวเกินจะอยู่ใน URL เช่น options และ features ของแผนที่ ส่งหลัง ready |
error | widget ถึงหน้าของคุณ | widget ทำงานไม่สำเร็จ |
close-with-error | widget ถึงหน้าของคุณ | ผู้ใช้กด ปิด บนหน้าข้อผิดพลาด |
action อื่นเป็นของแต่ละ widget เช่น select ของตัวเลือกรายการ
widget แสดงหน้าข้อผิดพลาดพร้อมปุ่ม ปิด เมื่อลงชื่อเข้าใช้ไม่ได้ (401) ไม่มีสิทธิ์ (403) ไม่พบ (404) หรือเกิดข้อผิดพลาด (500) การกด ปิด ส่ง close-with-error ให้หน้าของคุณ ซึ่งเป็นผู้เลือกว่าจะทำอะไรต่อ
ตัวอย่าง
<div id="box" style="height: 480px"></div>
<script>
const site = 'https://platform.example.com'
const token = '...' // bearer token จาก /api/auth/oauth2/token
const messageToken = crypto.randomUUID()
const params = new URLSearchParams({
_credential_type: 'bearer-token',
_token: token,
_origin: location.origin,
_message_token: messageToken,
_locale: 'th',
_theme: 'light',
item_id: '<id ของ web map>',
})
const frame = document.createElement('iframe')
frame.src = `${site}/widgets/map?${params}`
frame.style = 'width:100%;height:100%;border:0'
document.getElementById('box').append(frame)
addEventListener('message', (e) => {
if (e.origin !== site || e.data.messageToken !== messageToken) return
if (e.data.action === 'ready') {
frame.contentWindow.postMessage(
{ messageToken, action: 'post-widget-parameters', payload: { options: {} } },
site
)
}
})
</script>Widget ทั้งหมด
| Widget | ชื่อใน URL | ใช้ทำอะไร |
|---|---|---|
| แผนที่ | map | แสดง web map |
| ตัวแก้ไข geometry | อยู่ในฟอร์ม | วาดหรือแก้ geometry ของช่องในฟอร์ม |
| ฟอร์ม | form | กรอกฟอร์มหรือเปิดระเบียน |
| ตัวแก้ไขฟอร์ม | form-editor | สร้างฟอร์มจากฟิลด์ของตาราง |
| ตัวเลือกรายการ | item-picker | เลือกรายการจาก Drive |
| รายการของฟอร์ม | item-list | เรียกดูฟอร์มและเริ่มฟอร์มใหม่ |
| การแชร์รายการ | item-sharing | ตั้งว่าใครเปิดรายการได้ |
| ตัวเลือกข้อมูล | data-picker | เลือกระเบียนจากตาราง |
| นำเข้าข้อมูล | data-import | นำ collection ในไฟล์เข้าฐานข้อมูล |
| ตัวเลือกผู้ใช้งาน | user-and-group-picker | เลือกผู้ใช้หรือกลุ่ม |
| ตัวสร้างตัวกรอง | filter-builder | สร้างตัวกรองของชั้นข้อมูล |
| ตัวสร้าง expression | expression-builder | สร้างคำอธิบายจากข้อความและฟิลด์ |
| การ์ดบัญชี | account | การ์ดผู้ใช้และปุ่มออกจากระบบ |
| Launcher | app | เปิดแอปอื่น |