คู่มือ aWhere
พัฒนาWidgets

Widgets

ฝังเครื่องมือของแพลตฟอร์ม เช่น แผนที่ ฟอร์ม และตัวเลือกรายการ ลงในหน้าเว็บของคุณด้วย iframe

widget คือหน้าเว็บเล็ก ๆ ของแพลตฟอร์มที่คุณฝังในหน้าของคุณด้วย iframe แล้วคุยกับมันด้วย postMessage แอปของแพลตฟอร์มเองก็ใช้วิธีนี้ เช่น แผนที่ใน Data Studio และกล่องแชร์ใน Drive

widget ไม่ใช่ widget บนแดชบอร์ดของ App Studio ตัวนั้นคือแผนภูมิหรือตารางบนผืนงาน ดู App Studio

URL และพารามิเตอร์

widget ทุกตัวอยู่ที่ <site>/widgets/<ชื่อ> พารามิเตอร์อยู่ใน query string

พารามิเตอร์ค่า
_credential_typebearer-token หรือ api-key ไม่ใส่ widget แสดง 401
_tokenbearer token เมื่อเป็น bearer-token
_api_keyAPI key เมื่อเป็น api-key
_originorigin ของหน้าที่ฝัง เช่น https://app.example.com widget ส่งข้อความกลับไปที่ origin นี้เท่านั้น
_message_tokenข้อความสุ่มที่คุณสร้าง ใช้ยืนยันว่าข้อความมาจากคู่เดียวกัน
_localeth หรือ en
_themelight หรือ 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ทิศทางความหมาย
readywidget ถึงหน้าของคุณwidget โหลดเสร็จและรับข้อความได้ มีเฉพาะ widget ที่รับ post-widget-parameters ได้แก่ map, filter-builder และ user-and-group-picker
post-widget-parametersหน้าของคุณถึง widgetส่งค่าที่ยาวเกินจะอยู่ใน URL เช่น options และ features ของแผนที่ ส่งหลัง ready
errorwidget ถึงหน้าของคุณwidget ทำงานไม่สำเร็จ
close-with-errorwidget ถึงหน้าของคุณผู้ใช้กด ปิด บนหน้าข้อผิดพลาด

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สร้างตัวกรองของชั้นข้อมูล
ตัวสร้าง expressionexpression-builderสร้างคำอธิบายจากข้อความและฟิลด์
การ์ดบัญชีaccountการ์ดผู้ใช้และปุ่มออกจากระบบ
Launcherappเปิดแอปอื่น

ในหน้านี้